plan-execute

Plan Execute — Execution to Merged PR

Execute the validated plan in an isolated worktree. Spawn per-task agents, verify quality, create and merge the PR. Handles everything through to cleanup.

Run /clear before this command.

---

Prerequisite

A validated plan must exist at docs/plans/plan-{name}.md with all issues resolved (output of /plan-validate).

---

Step 1: Worktree Setup

Create an isolated git worktree:

git worktree add .worktrees/{plan-name} -b feature/{plan-name}

All execution happens inside the worktree. Main branch remains clean throughout.

---

Step 2: TDD Scaffolding

Only for tasks marked as TDD in the plan.

For each TDD task, before any implementation:

1. Write the failing test(s) that define the acceptance criteria
2. Run tests to confirm they fail (red)
3. Commit the failing tests
4. Mark the test file in the task for the implementation agent to find

Do not write implementation code in this step.

---

Step 3: Level-Based Parallel Execution

Parse the task list from the plan. Group tasks by layer (Layer 1 = foundation, Layer 2 = depends on Layer 1, etc.).

For each layer:

1. Identify all tasks in the layer
2. Spawn one agent per task in parallel (Task tool, run_in_background: true)
3. Each agent receives: its task description, files to modify, acceptance criteria, and relevant ADRs
4. Monitor all agents by reading .claude/tasks/<id>/output.log via Read (TaskOutput is deprecated since v2.1.83)
5. Each agent commits on task completion: git commit -m "feat: {task-description}"
6. Wait for all tasks in the layer to complete before starting the next layer

Drift detection: after each layer, diff the actual changes against the plan spec. If implementation deviates significantly from the plan (new files not in plan, plan files not touched), flag and ask how to proceed. Do not silently continue on drift.

Agent instructions for each task:

You are implementing one task from a validated plan.
Task: {description}
Files to modify: {file list}
Acceptance criteria: {criteria}
Relevant ADRs: {adr list}

First principles:
- Build state-of-the-art. No workarounds, no legacy patterns.
- Fix at the correct architectural level, never with component-level hacks.
- If you discover that the plan is wrong or missing context, stop and report — do not improvise architecture.

Commit your changes when complete with message: "feat: {task-description}"