Planning Mode

Tasks can be created in planning mode, which requires the agent to submit an implementation plan for human review before writing any code.

Task Modes

Set the mode when creating a task:

curl -X POST https://buildd.dev/api/tasks \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_xxx",
    "title": "Refactor auth middleware",
    "description": "Consolidate auth logic into shared middleware",
    "mode": "planning"
  }'

Workflow

1. Worker Claims Task

The worker claims the planning-mode task like any other task. The task mode is included in the claim response.

2. Worker Submits Plan

Instead of implementing directly, the worker investigates the codebase and submits a plan:

# Via MCP server
buildd_submit_plan \
  --workerId "worker-id" \
  --plan "## Plan\n\n1. Extract auth logic from route handlers\n2. Create shared middleware in lib/auth.ts\n3. Update all API routes to use middleware\n\n## Files to Change\n- src/app/api/*/route.ts\n- src/lib/auth.ts (new)"

The plan is submitted as markdown and stored on the worker. The worker status changes to awaiting_plan_approval.

3. Admin Reviews Plan

The task author (or any admin) reviews the plan in the dashboard or via the API/MCP.

Dashboard — Plan Review Panel

When a planning task completes with a plan, the task detail page displays a Plan Review Panel showing each proposed step with its reference code, title, description, dependencies, and required capabilities. Two buttons are available:

• Approve Plan — creates child execution tasks from the plan steps, with dependencies wired automatically
• Reject Plan — opens a feedback form; submitting creates a new planning task with the feedback attached for the agent to revise

API

# Approve
curl -X POST https://buildd.dev/api/tasks/{id}/approve-plan \
  -H "Authorization: Bearer bld_xxx"

# Reject
curl -X POST https://buildd.dev/api/tasks/{id}/reject-plan \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "feedback": "Add error handling for the edge cases" }'

MCP (admin)

buildd action=approve_plan params={ taskId: "..." }
buildd action=reject_plan params={ taskId: "...", feedback: "Add tests" }

4. Child Tasks Execute

After approval, Buildd creates one child task per plan step using a two-pass approach:

1. All tasks are created with the interpolated titles and descriptions
2. Inter-step dependsOn references are resolved to actual task IDs

Child tasks respect the mode, priority, and outputRequirement from each plan step. Workers claim and execute them like any other task, with dependency blocking enforced automatically.

5. Auto-Aggregation

When all child tasks of a planning parent complete, Buildd automatically creates an aggregation task. This task collects the results from all children so a worker can produce a final summary or deliverable. Duplicate aggregation tasks are prevented — only one is created per planning parent.

Requesting Plans Mid-Task

Admins can also request a plan from an already-running worker using the instruction system:

buildd_send_instruction \
  --workerId "worker-id" \
  --message '{"type": "request_plan", "message": "Please submit a plan before continuing"}'

The worker receives this as a structured instruction and pauses implementation to submit a plan.

Plan Expiration

Plans that go unreviewed are automatically expired during cleanup. The buildd_run_cleanup tool handles this, marking workers with expired plan approvals as failed.