run-implementation-plan

name	run-implementation-plan
description	Execute an entire implementation plan end-to-end. Parallelizes tasks within batches, reviews each batch, fixes issues, commits, and opens a PR when done. Set-it-and-forget-it orchestration.
argument-hint	[prefix] [batch number to start from, e.g. "client 3" or "client" or "3"]

Execute an entire implementation plan autonomously — batch by batch, parallelizing independent tasks, reviewing, fixing, committing, and opening a PR at the end.

This skill is the orchestrator. It does NOT implement tasks itself. It delegates to /implement-task-code agents for implementation and /review-code for reviews.

Input

• $ARGUMENTS (optional): May contain a design prefix and/or a batch number (e.g., "client 3" to use prefix "client" and start from Batch 3, "client" to use prefix "client" and start from the first incomplete batch, or "3" to start from Batch 3 with auto-discovered prefix). If omitted, the prefix is discovered and execution starts from the first batch with incomplete tasks.

Prerequisites

Before invoking this skill, the following must exist:

project/
├── plan/
│   └── {prefix}-plan.md            # Task plan with batches, tracks, dependencies, status tracker
├── design/
│   ├── {prefix}-requirements.md
│   ├── {prefix}-high-level-design.md
│   └── {prefix}-low-level-design.md

The plan must follow the format produced by /implementation-task-plan, with:

• Batch Execution Overview section (batch -> track -> task structure)
• Task detail sections with prerequisites, conflicts, parallel annotations
• Task Status Tracker table with [ ], [~], [x] statuses

Process

---

Phase 1: Read the Plan and Determine Starting Point

1. Parse $ARGUMENTS and discover the design prefix

   • $ARGUMENTS may contain a prefix and/or a batch number. A prefix is a non-numeric word. A batch number is numeric.
   • Examples: "client 3" (prefix=client, batch=3), "client" (prefix=client, no batch), "3" (no prefix, batch=3), empty (no prefix, no batch).

2. Resolve the plan file

   • If a prefix was provided, look for plan/{prefix}-plan.md.
   • If no prefix was provided, scan the plan/ directory for files matching *-plan.md. Also check for an unprefixed plan.md.
     • One match: Use it and infer the prefix from the filename (e.g., client-plan.md means prefix is client; unprefixed plan.md means no prefix is used).
     • Multiple matches: Use AskUserQuestion listing the options and ask the user which plan to use.
     • No matches: Use AskUserQuestion to ask where the plan file is located.
   • Once the plan file is found and the prefix is established, use the same prefix for all design doc references throughout.

3. Read plan/{prefix}-plan.md — specifically:

   • The Batch Execution Overview section to understand the batch/track/task topology
   • The Task Status Tracker table to know what's done and what's remaining
   • Count completed tasks vs total

4. Determine starting batch:

   • If $ARGUMENTS specifies a batch number, start there
   • Otherwise, find the first batch that has any task with status [ ] or [~]
   • If all tasks are [x], inform the user and offer to create a PR

5. Validate plan integrity:

   • Check that no task is [~] (in progress) — if so, warn the user and ask whether to reset it to [ ] or continue it
   • Verify the plan has the expected structure

Phase 2: Discover Project Tooling

1. Check for CLAUDE.md or AGENTS.md in the project root
   • Extract: test runner, linter, formatter, build command
2. If not found, check for Makefile, Cargo.toml, package.json, go.mod, etc.
3. Record discovered commands — these are used for verification after each batch

Phase 3: Git Branch Management

1. Check current branch — run git branch
2. If on main or master, create a feature branch:
   • Convention: feature/implementation (or implementation)
   • Push with -u to set upstream tracking
3. If already on a feature branch, continue using it
4. Ensure working tree is clean — if dirty, warn and ask user

Phase 4: Execute Batches

For each batch (starting from the determined starting point), repeat the following cycle:

Step 1: Identify Eligible Tasks in This Batch

1. Read the batch section from the plan to identify all tasks in this batch
2. Cross-reference with the Task Status Tracker — skip tasks already marked [x]
3. Parse the track structure to identify:
   • Parallel tracks: Tasks on different tracks that can run simultaneously
   • Serial tasks within a track: Tasks that must run in order (Task A -> Task B)
4. Build an execution schedule:
   • Within each track, tasks run sequentially (first to last)
   • Across tracks marked PARALLEL, the first eligible task from each track can run simultaneously

Step 2: Launch Parallel Task Agents

For each wave of parallelizable tasks:

1. Identify the current wave — one task per parallel track (the first incomplete task on each track)
2. Launch task-implementation-agent subagents in parallel using the Task tool:
   • Each agent gets a prompt containing:
     • The task number and full task details from the plan
     • Design prefix: {prefix}
     • Plan: plan/{prefix}-plan.md
     • Design docs: design/{prefix}-requirements.md, design/{prefix}-high-level-design.md, design/{prefix}-low-level-design.md
     • The tooling commands (test, lint, format, build)
     • Instructions to follow strict TDD
     • Instructions to update the task status in plan/{prefix}-plan.md from [ ] to [~] at start
     • Instructions NOT to commit — just implement and verify
   • Use run_in_background: true for all agents
   • Use subagent_type: "task-implementation-agent"
3. Wait for all agents in the wave to complete
   • Use TaskOutput to check on each agent
   • If any agent fails, log the failure and continue with remaining agents
4. If a track has more serial tasks, launch the next task on that track in the next wave
5. Repeat until all tasks in this batch are complete

Important parallelization rules:

• Tasks on tracks marked "PARALLEL" launch simultaneously
• Tasks on the same track run one after another
• If a task has a prerequisite from the SAME batch (serial within track), wait for it
• If a task has conflicts with annotation, do NOT run it in parallel with the conflicting task
• Maximum parallel agents: 5 (to avoid overwhelming the system)

Step 3: Verify Batch Completion

After all tasks in the batch are implemented:

1. Run the full test suite using discovered tooling
2. Run the formatter (format before lint)
3. Run the linter
4. Run the build to confirm compilation
5. If any verification fails, attempt to fix:
   • Read the error output
   • Make targeted fixes
   • Re-run verification
   • If stuck after 2 attempts, ask the user for help

Step 4: Review the Batch

1. Invoke /review-code on the uncommitted changes
   • This will use the review-code skill to produce a structured review document
2. Read the review document to check for findings:
   • If Critical findings: fix them immediately, re-verify, re-review
   • If Warning findings: fix them if the fix is straightforward (Low/Med effort)
   • If Suggestion findings: apply only if clearly beneficial and low-risk
3. After fixing any review findings, re-run verification (tests, lint, build)

Step 5: Commit the Batch

1. Update the Task Status Tracker in plan/{prefix}-plan.md:
   • Mark all batch tasks as [x]
   • Update the progress count
   • Update the eligible tasks list for the next batch
2. Stage specific files — never use git add . or git add -A
   • Include all implementation files created/modified by the agents
   • Include plan/{prefix}-plan.md
   • Exclude: review documents, .claude/ directory, secrets, credentials
3. Create a descriptive commit:

   Implement Batch N: {Batch Title}
   
   {Brief description of what this batch adds}
   - Task X.Y: {description}
   - Task X.Z: {description}
   ...
   
   Requirements covered: FR-x.x.x, FR-y.y.y, ...
   
   Co-Authored-By: Claude Opus 4.6 <[e-mail]>
   

4. Verify the commit succeeded — git log --oneline -1

Step 6: Report Batch Progress

After each batch commit, report to the user:

• Batch N of M completed
• Tasks completed in this batch
• Test results summary
• Review findings summary (Critical/Warning/Suggestion counts)
• Any issues encountered and how they were resolved
• Next batch preview (what's coming)

Step 7: Continue to Next Batch

• Move to the next batch and repeat from Step 1
• If this was the last batch, proceed to Phase 5

Phase 5: Final Verification

After all batches are complete:

1. Run the full test suite one final time
2. Run all quality checks (lint, vet, format, build)
3. Verify the Task Status Tracker shows all tasks as [x]
4. Show final summary:
   • Total tasks completed
   • Total test count and coverage
   • Total commits made
   • Any warnings or issues to be aware of

Phase 6: Create Pull Request

1. Push the branch to remote if not already pushed:
   • git push -u origin {branch-name}
2. Create a PR using gh pr create:
   • Title: concise description of the implementation (under 70 chars)
   • Body structure:

     ## Summary
     
     {Overview of what was implemented}
     - Bullet points of key features/components
     
     ### Architecture highlights
     {2-3 sentences on key design decisions}
     
     ### Quality
     - X tasks across Y batches
     - Z% test coverage
     - All code reviews passed (0 critical findings)
     
     ## Test plan
     
     - [x] Unit tests: {count} tests across {N} packages
     - [x] Integration tests: {description}
     - [x] E2E tests: {description if applicable}
     - [x] Quality gates: {list what passed — linting, formatting, etc.}
     
     Generated with [Claude Code](https://claude.com/claude-code)
     

3. Report the PR URL to the user

---

Error Handling

If a task agent fails:

• Log which task failed and why
• Check if the failure blocks other tasks in the batch
• If it does, skip blocked tasks and report to the user
• If it doesn't, continue with remaining tasks
• Ask the user how to proceed with the failed task

If review finds Critical issues:

• Fix them immediately
• Re-run affected tests
• Re-review the fix (just the fix, not the full batch)

If tests fail after all agents complete:

• Read the failure output
• Attempt to diagnose and fix (formatting, import issues, test flakiness)
• If the fix requires understanding an agent's implementation, read the relevant files
• If stuck after 2 fix attempts, ask the user

If pre-commit hooks block a commit:

• Read the hook output
• Fix formatting/linting issues
• Re-run the commit
• Never use --no-verify without explicit user consent

If git push fails:

• Check if branch exists remotely
• Check for authentication issues
• Report to user if not resolvable

---

Key Principles

1. Never implement tasks directly — always delegate to task-implementation-agent subagents
2. Maximize parallelism — launch all independent tasks in a batch simultaneously
3. Review every batch — no code ships without a structured review
4. Fix before committing — address Critical and Warning findings before the commit
5. Commit per batch, not per task — each batch is an atomic unit
6. Track progress in plan/{prefix}-plan.md — this is the single source of truth
7. Report progress after each batch — the user should see what happened even if unattended
8. Ask when stuck, not when progressing — minimize interruptions, but don't silently fail

Output

When complete:

• All tasks implemented and committed on a feature branch
• Each batch reviewed and verified
• Task Status Tracker fully updated
• PR created and URL reported to the user
• Summary of the full run: tasks, tests, coverage, commits, review findings