Execute Beads Plan

Execute Beads Implementation Plan

Orchestrate execution of an implementation plan using parallel task agents, verification agents, and fix agents.

Arguments

$ARGUMENTS - Path to implementation plan. Defaults to most recent in docs/plans/*-implementation.md

Architecture

Orchestrator Instructions

The orchestrator (this skill's main loop) stays lean - minimal context, just coordination.

Startup

1. Load the implementation plan
2. Verify source (1) plan still exists (referenced in header)
3. Query current state: br list --json
4. Identify tasks by status in the plan

Main Loop

while tasks remain:
    1. Find ready tasks: `br ready --json`
    2. Match ready beads to plan tasks
    3. Batch independent ready tasks
    4. Spawn Task Agents (parallel, using Task tool)
    5. Wait for batch completion
    6. Spawn Verification Agent for batch
    7. If failures: Spawn Fix Agent(s)
    8. Update plan with statuses
    9. Check for blockers requiring plan changes

Spawning Task Agents

For each ready task, spawn using the Task tool:

Task tool parameters:
  subagent_type: 'general-purpose'
  model: [from task's Model field]
  prompt: [see Task Agent Prompt below]

Launch multiple Task Agents in parallel (single message with multiple Task tool calls) when tasks have no dependencies between them.

Task Agent Prompt Template

You are implementing a task from an implementation plan.

## Context

**Implementation Plan:** [path]
**Source Plan:** [path from plan header]
**Your Task:** [task title]
**Bead ID:** [bead-id]

## Your Task Details

[Copy the full task section from implementation plan]

## Instructions

1. First, mark the task in progress:
   ```bash
   br update [bead-id] --status in_progress

2. Read the implementation plan to understand overall context

3. Check completed tasks' notes for relevant file references

   • Only read files that are relevant to YOUR task
   • Use judgment - don't read everything

4. Implement the task

5. Update the implementation plan with your progress:

   • Change Status to: IN_PROGRESS
   • Add: **Working on:** [current focus]

6. When complete, update the plan:

   • Change Status to: DONE (pending verification)
   • Add: **Notes:** [what you did, key files with line refs]

7. Mark bead as done:

   br update [bead-id] --status done
   

Do NOT run verification - the Verification Agent handles that.

If you hit a blocker that suggests the plan is wrong:

• Document the issue in the task notes
• Set status to ERROR
• Explain clearly what's wrong and why

### Spawning Verification Agent

After each batch completes, spawn one Verification Agent:

Task tool parameters: subagent_type: 'general-purpose' model: 'haiku' prompt: [see Verification Agent Prompt below]

### Verification Agent Prompt Template

You are verifying completed tasks from an implementation plan.

Tasks to Verify

[List each task that was just completed with its verification criteria]

Instructions

For each task, run every verification check:

1. Execute each check command
2. Record pass/fail for each
3. Return results in this format:

Task: [title] ([bead-id])

• Check 1: passed
• Check 2: FAILED - [error output]
• Check 3: passed Result: PASS / FAIL

If ALL checks pass for a task: Result is PASS If ANY check fails: Result is FAIL

Return summary:

• Tasks verified: N
• Passed: M
• Failed: K
• Failed tasks: [list with reasons]

### Spawning Fix Agent

For each failed verification, spawn a Fix Agent:

Task tool parameters: subagent_type: 'general-purpose' model: 'sonnet' prompt: [see Fix Agent Prompt below]

### Fix Agent Prompt Template

You are fixing a verification failure.

Context

Task: [title] ([bead-id]) Implementation Plan: [path]

What Was Implemented

[Task's Notes section from plan]

Verification Failure

[Failed check and error output]

Instructions

1. Analyze the failure
2. Read relevant files to understand the issue
3. Fix the specific problem
4. Update the task notes in the implementation plan:
   • Add: **Fix Applied:** [what you changed]
5. Do NOT re-run verification (orchestrator will re-verify)

If the fix requires changes beyond this task's scope:

• Document what's needed
• Set task status to ERROR
• Explain the blocker clearly

### Status Updates

After verification, update the implementation plan:

**On PASS:**
```markdown
**Status:** DONE
**Verified:** [timestamp]

On FAIL after fix attempt:

**Status:** ERROR
**Error:** [what failed]
**Fix Attempted:** [what was tried]

Change Detection

If a Task Agent or Fix Agent reports a blocker suggesting the plan is wrong:

1. Graceful pause - Let in-flight tasks finish, don't start new batches
2. Document - Note the issue in the implementation plan
3. Propose - Suggest what needs to change in the (1) Plan
4. Wait - Pause for human decision

Report to user:

Execution paused - potential plan issue detected.

Task [bead-id] reported: [blocker description]

Suggested action: [what might need to change]

Options:
1. Update (1) plan and re-plan affected tasks
2. Manually resolve and continue
3. Abort execution

Completion

When all tasks are DONE:

Execution complete.

Results:
- Tasks completed: N
- Verification passed: N
-
Implementation plan: [path]
Source plan: [path]

All beads closed. Run `br stats` to see summary.

When blocked on errors:

Execution blocked.

Completed: M tasks
Errors: K tasks
  - [task]: [error summary]

Awaiting resolution before continuing.

Batch Size

Limit parallel Task Agents to avoid overwhelming:

• Default: 3-5 concurrent agents
• Adjust based on task complexity
• Haiku tasks can have higher concurrency

Reference

For agent coordination details, see: references/agent-coordination.md