# Execute Beads Plan

> This skill should be used when the user asks to "execute implementation plan", "run beads plan", "start working on plan", "execute tasks from plan", or wants to run an implementation plan that was created with plans-to-beads. Orchestrates parallel task agents with verification and change handling.

- Skill: `amitkot/execute-beads-plan` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add amitkot/execute-beads-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/execute-beads-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: amitkot (https://skillmd.com/u/amitkot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amitkot/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

| Agent | Role | Context | Model |
|-------|------|---------|-------|
| **Orchestrator** | Coordinate, dispatch, track | Minimal | sonnet |
| **Task Agent** | Implement one bead | Medium | Per-task |
| **Verification Agent** | Run checks | Small | haiku |
| **Fix Agent** | Address failures | Medium | sonnet |

## 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:
   ```bash
   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])
  - [x] Check 1: passed
  - [ ] Check 2: FAILED - [error output]
  - [x] 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:**
```markdown
**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`