Reference for the plan default tool: create_plan, update_plan, and get_plan for tracking multi-step tasks.

Plan Tool

Script: powers/plan.py Dependencies: pydantic

Create, track, and update structured plans with steps. Plans are stored as JSON files in .supyagent/plans/ within the working directory. This tool helps agents break down complex tasks into manageable steps and track progress.

create_plan

Create a new plan with a list of steps.

Input

Field	Type	Default	Description
`title`	`str`	required	Title of the plan
`steps`	`list`	required	List of plan step objects (see below)
`working_dir`	`str`	`"."`	Working directory for storing the plan

Each step object:

Field	Type	Default	Description
`description`	`str`	required	Description of this step
`status`	`str`	`"pending"`	Status: `"pending"`, `"in_progress"`, `"completed"`, `"skipped"`
`notes`	`str`	`""`	Optional notes for this step

Output

Field	Type	Description
`ok`	`bool`	`true` if plan was created
`plan_id`	`str`	8-character unique plan identifier
`title`	`str`	Plan title
`steps_count`	`int`	Number of steps in the plan
`error`	`str`	Error message on failure

Examples

// Create a deployment plan
{
  "title": "Deploy to production",
  "steps": [
    {"description": "Run test suite"},
    {"description": "Build Docker image"},
    {"description": "Push to container registry"},
    {"description": "Deploy to cluster"},
    {"description": "Run smoke tests"},
    {"description": "Update documentation"}
  ]
}

// Create with pre-set statuses
{
  "title": "Code review checklist",
  "steps": [
    {"description": "Read the PR description", "status": "completed", "notes": "Looks good"},
    {"description": "Review code changes", "status": "in_progress"},
    {"description": "Run tests locally", "status": "pending"},
    {"description": "Leave review comments", "status": "pending"}
  ]
}

update_plan

Update the status or notes of a specific step in a plan.

Input

Field	Type	Default	Description
`plan_id`	`str`	required	ID of the plan to update
`step_index`	`int`	required	Zero-based index of the step to update
`status`	`str`	`"completed"`	New status: `"pending"`, `"in_progress"`, `"completed"`, `"skipped"`
`notes`	`str`	`null`	Optional notes to add to the step
`working_dir`	`str`	`"."`	Working directory where the plan is stored

Output

Field	Type	Description
`ok`	`bool`	`true` if update succeeded
`plan_id`	`str`	Plan identifier
`step_description`	`str`	Description of the updated step
`new_status`	`str`	The new status that was set
`error`	`str`	Error message on failure

Examples

// Mark first step as completed
{"plan_id": "abc12345", "step_index": 0, "status": "completed"}

// Mark step as in progress with notes
{
  "plan_id": "abc12345",
  "step_index": 1,
  "status": "in_progress",
  "notes": "Docker build started at 14:30"
}

// Skip a step
{"plan_id": "abc12345", "step_index": 3, "status": "skipped", "notes": "Not needed for this release"}

get_plan

Retrieve a plan by ID, or get the most recent plan if no ID is given.

Input

Field	Type	Default	Description
`plan_id`	`str`	`null`	ID of the plan to retrieve. If omitted, returns the most recent plan
`working_dir`	`str`	`"."`	Working directory where plans are stored

Output

Field	Type	Description
`ok`	`bool`	`true` if plan was found
`plan_id`	`str`	Plan identifier
`title`	`str`	Plan title
`steps`	`list`	Array of step status objects (see below)
`completed_count`	`int`	Number of completed steps
`total_count`	`int`	Total number of steps
`error`	`str`	Error message on failure

Each step status object:

Field	Type	Description
`index`	`int`	Zero-based step index
`description`	`str`	Step description
`status`	`str`	Current status
`notes`	`str`	Notes for this step

Examples

// Get a specific plan
{"plan_id": "abc12345"}

// Get the most recent plan
{}

Example Output

{
  "ok": true,
  "plan_id": "abc12345",
  "title": "Deploy to production",
  "steps": [
    {"index": 0, "description": "Run test suite", "status": "completed", "notes": "All 42 tests passed"},
    {"index": 1, "description": "Build Docker image", "status": "completed", "notes": ""},
    {"index": 2, "description": "Push to container registry", "status": "in_progress", "notes": ""},
    {"index": 3, "description": "Deploy to cluster", "status": "pending", "notes": ""},
    {"index": 4, "description": "Run smoke tests", "status": "pending", "notes": ""},
    {"index": 5, "description": "Update documentation", "status": "pending", "notes": ""}
  ],
  "completed_count": 2,
  "total_count": 6
}

Storage

Plans are stored as JSON files in .supyagent/plans/:

.supyagent/
  plans/
    abc12345.json
    def67890.json

Each plan file contains:

{
  "plan_id": "abc12345",
  "title": "Deploy to production",
  "steps": [
    {"description": "Run test suite", "status": "completed", "notes": "All passed"},
    {"description": "Build Docker image", "status": "pending", "notes": ""}
  ]
}

Tips

Plans help agents manage complex multi-step tasks without losing track of progress
Use get_plan with no arguments to quickly check the current plan's status
The notes field is useful for recording details about each step (durations, results, issues)
Plans persist across agent sessions, so work can be resumed later
Step indices are zero-based -- the first step is index 0

Plan Tool

On this page