implement-plan

Implement Plan

Execute plans with persistent beads-backed progress tracking.

When To Use

• User says "implement plan", "execute plan", "build it"
• User references a plan file with "@thoughts/shared/plans/..."

Core Behavior

1. Parse plan into beads tasks with dependencies
2. Track progress via bd (survives /clear, /compact)
3. Check context at 50% → pause, sync, suggest compact
4. Resume via bd ready after compact

---

Workflow

Phase 1: Pre-Implementation Check

# Check if beads initialized
if [ ! -d .beads ]; then
  bd init --stealth
fi

# Sync any existing state
bd sync

1. Check current context level
2. If context > 30%:
   → bd sync (save state)
   → Output: "Context at X%. Recommend /compact before starting."
   → Stop and wait
3. If context < 30%:
   → Proceed to Phase 2

Phase 2: Setup - Create Beads Tasks

# Create epic for the plan
bd create "Implement: [Plan Name]" -t epic --json
# Returns bd-xxxx (epic ID)

# Create task group 1
bd create "Group 1: [Description]" --deps parent:$EPIC_ID -p 1 --json
bd create "Task 1.1: [Description]" --deps parent:$GROUP1_ID -p 1 --json
bd create "Task 1.2: [Description]" --deps parent:$GROUP1_ID -p 1 --json

# Create task group 2 (depends on group 1)
bd create "Group 2: [Description]" --deps parent:$EPIC_ID -p 1 --json
bd dep add $GROUP2_ID $GROUP1_ID --type blocks

# ... continue for all groups

Task grouping: 3-5 tasks per group, dependencies between groups.

Phase 3: Execute (by group)

# Get first ready task
bd ready --json

# For each task:
bd update $TASK_ID --status in_progress --json

For each task:

1. Implement the task
2. Test
3. Commit: "feat(scope): description - step X.Y"
4. Close the task:
   bd close $TASK_ID --reason "commit: abc123" --json
5. Check context level
6. If context > 50%:
   → bd sync
   → Output: "Context at Y%. Recommend /compact."
   → Output: "After compact, say 'continue' - beads knows where you are"
   → Stop

Phase 3b: Parallel Execution for Independent Tasks

Key Insight: Within a task group, tasks without dependencies on each other can run in parallel.

Dependency Analysis

# Get all ready tasks (may be multiple!)
bd ready --json
# Returns: [{"id": "bd-a1b2", "title": "Task A"}, {"id": "bd-c3d4", "title": "Task B"}]

If multiple tasks are ready simultaneously, they have NO dependencies on each other.

Parallel Execution Pattern

1. ANALYZE: Get all ready tasks
2. CLASSIFY:
   - File-disjoint? (different files) → Can parallelize
   - Same files? → Must be sequential
3. SPAWN: For file-disjoint tasks, spawn background agents:

Task:
  subagent_type: general-purpose
  description: "Implement Task A"
  prompt: |
    Implement: [Task A description]
    Files: [list of files]
    Tests: [test requirements]
    Commit when done with message: "feat(scope): Task A"
  run_in_background: true

Task:
  subagent_type: general-purpose
  description: "Implement Task B"
  prompt: |
    Implement: [Task B description]
    Files: [list of files]
    Tests: [test requirements]
    Commit when done with message: "feat(scope): Task B"
  run_in_background: true

4. CONTINUE: Main agent can work on another task or wait
5. POLL: Check background agents via TaskOutput
6. CLOSE: Mark completed tasks in beads

Example: Parallel Independent Tasks

Given ready tasks:
- bd-a1: "Create user model" (touches: models/user.py)
- bd-b2: "Create product model" (touches: models/product.py)
- bd-c3: "Add auth middleware" (touches: middleware/auth.py)

Analysis: All touch DIFFERENT files → Parallelize ALL

Spawn 3 background agents simultaneously.
Main agent polls periodically.
As each completes: bd close <id> --reason "commit: xyz"

Parallel Execution Benefits

When NOT to Parallelize

• Tasks modify same files
• Task B uses output from Task A
• Beads shows dependency: bd dep tree shows blocker
• Context already high (>40%) - sequential is safer

Phase 4: Completion

# All tasks done
bd close $EPIC_ID --reason "Plan completed" --json
bd sync

# Verify
bd list --status closed --json | grep $EPIC_ID

---

Beads Task Structure

Epic: "Implement: Auth System"
├── Group 1: "Setup" (3 tasks)
│   ├── Task 1.1: "Create user model"
│   ├── Task 1.2: "Add password hashing"
│   └── Task 1.3: "Create auth middleware"
├── Group 2: "Endpoints" (4 tasks) [blocked by Group 1]
│   ├── Task 2.1: "Login endpoint"
│   ├── Task 2.2: "Logout endpoint"
│   ├── Task 2.3: "Register endpoint"
│   └── Task 2.4: "Password reset"
└── Group 3: "Tests" (3 tasks) [blocked by Group 2]
    ├── Task 3.1: "Unit tests"
    ├── Task 3.2: "Integration tests"
    └── Task 3.3: "E2E tests"

---

Context Thresholds

---

Resuming After Compact

After /compact, beads knows exactly where you are:

bd sync              # Pull latest state
bd ready --json      # Shows next unblocked task
bd list --status in_progress --json  # Shows any in-progress

User just says "continue" and you pick up exactly where you left off.

---

Commit Format

type(scope): description - step X.Y

Types: feat, fix, refactor, test, docs, chore

Each commit references the beads task:

bd close $ID --reason "commit: abc123"

---

Session End (Critical!)

Before ending any session:

bd sync  # ALWAYS sync before session end

This ensures all progress is persisted and resumable.

---

Handling Issues

Context Running Low

1. Complete current task if close
2. bd sync to save all progress
3. Output: "Context at X%. Stopping."
4. Suggest: "/compact then 'continue'"

Unexpected Complexity

1. Create new beads task for the complexity:

   bd create "Handle edge case: X" --deps parent:$CURRENT -p 0 --json
   

2. If blocking, pause and ask user
3. Don't deviate from plan without approval

Test Failures

1. Fix immediately if simple
2. Create blocker task if complex:

   bd create "Fix: test failure in X" -t bug -p 0 --json
   

---

Keywords

implement plan, execute plan, run plan, build it, continue, bd ready