# Implement Plan > Use when the user wants to execute an approved implementation plan and says any of "do it" (with a plan in scope), "lets do it" / "let's do it", "confirmed" (as approval to proceed on a plan), "implement the plan", "implement this", "execute the plan", "start implementing", "work through the plan", "implement the next phase", "build it out", "knock out the plan", or "/implement-plan PATH". Also use when a plan file (`./.plans/PLAN.md`, any `./.plans/*.md`, or legacy `./PLAN.md` / `./docs/plans/*.md`) is present and the user signals readiness to begin coding. Do NOT use when the user is still discussing, refining, or asking questions about the plan, nor when no plan exists — short imperatives like "do it" or "confirmed" alone are ambiguous; verify a plan is in scope before activating. - Skill: `paultyng/implement-plan` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add paultyng/implement-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/paultyng/implement-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: paultyng (https://skillmd.com/u/paultyng) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paultyng/implement-plan --- # Implement Plan Drive an approved implementation plan to completion: review-plan gate → per-task loop (implementer → verify → reviewer → triage → commit → tick) → end-of-plan review. Manual invocation only. Never auto-creates PRs. ## Workflow ### 1. Resolve the plan and check preconditions **Plan resolution** (priority order): 1. Explicit path argument (e.g. `/implement-plan .plans/auth-rewrite.md`). 2. `./.plans/PLAN.md` in cwd. 3. Latest by mtime in `./.plans/*.md`. 4. **Legacy fallback** (one-release transition): `./PLAN.md` in cwd, then latest by mtime in `./docs/plans/*.md`. If either resolves, warn once: `Plan resolved from legacy path ; consider moving under .plans/`. 5. None resolve → **stop, ask the user**. Do not guess. Do not assume "do it" meant something else; if no plan, this skill should not have activated — exit cleanly. **CLAUDE.md override**: if the project `CLAUDE.md` (or `CLAUDE.local.md`) contains a directive like `Plans live in `, use `` as the primary discovery dir instead of `.plans/`. Skip the gitignore bootstrap below in that case — the user has taken responsibility for the path. After resolving a path under `.plans/` (steps 2 or 3), call once per run: ```sh ~/.claude/scripts/ensure-gitignore.sh '.plans/' ``` This is idempotent. Skip for legacy paths (step 4) and for CLAUDE.md overrides. Read the plan file fully. Capture: total task count, unchecked task count, any **Branch policy** section (see [reference.md → Plan header conventions](reference.md#plan-header-conventions)), and any **Behavior delta** section (its `Acceptance:` criteria are verified at end-of-plan, step 5). **Precondition checks** (fail-fast — abort with a clear message if any fails): ```sh # In a git repo? git rev-parse --is-inside-work-tree >/dev/null 2>&1 || abort "not a git repo" # Working tree clean? Catches uncommitted + untracked (.plans/ is gitignored, so plan files are invisible to git — that is intentional). [ -z "$(git status --porcelain)" ] || abort "working tree not clean — commit, stash, or discard first" # origin remote exists? git remote get-url origin >/dev/null 2>&1 || abort "no 'origin' remote — see reference.md for fallback" ``` Plan files in `.plans/` are gitignored by design; they do not need to be committed and will not appear in `git status`. Legacy plans under `docs/plans/` (if also gitignored locally) behave the same. ### 2. Pre-flight gate: review-plan Invoke the `review-plan` skill as a subagent. Pass the resolved plan path. Branch on the returned verdict: | Verdict | Action | |---|---| | `READY` | Continue to step 3. | | `NEEDS_REVISION` | Surface findings. Ask the user: **revise the plan, proceed anyway, or abort?** Do not pick for them. | | `BLOCKED` | Halt. Surface findings. Exit. The user must edit the plan and re-invoke. | **Do not skip this gate.** "The plan looks fine" is not a substitute for the review-plan checklist. See [reference.md](reference.md) for the rationalization table. ### 3. Branch setup Determine the target branch and base, then switch (or resume). #### Determine policy Read the plan's **Branch policy** section if present (see [reference.md → Plan header conventions](reference.md#plan-header-conventions)). Resolve, in priority order: 1. **Plan declares `Chain: `** → chained-PR mode. Base = ``. Branch name = plan-derived default (or `Branch:` if also declared). Fetch the chain base if it's a remote ref. 2. **Plan declares `Base: `** → use that base. Branch name = `Branch:` if declared, else plan-derived default. 3. **Default** → base = `origin/`. Branch name = plan-derived default. **Plan-derived default branch name**: `impl/`, where `` is the plan filename without `.md`. Example: `.plans/2026-05-16-auth-rewrite.md` → `impl/2026-05-16-auth-rewrite`. **Default-branch detection**: ```sh DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||') [ -z "$DEFAULT_BRANCH" ] && abort "could not detect origin's default branch — set Base: in plan or run 'git remote set-head origin -a'" ``` #### Resume check Before creating a branch, detect resume mode: ```sh CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) TICKED_COUNT= if [ "$CURRENT_BRANCH" = "$TARGET_BRANCH" ] && [ "$TICKED_COUNT" -gt 0 ]; then # Resume mode: stay on this branch, skip branch creation. echo "Resuming on $CURRENT_BRANCH ($TICKED_COUNT tasks already done)" # Proceed to step 4. fi ``` #### Fresh branch creation If not resuming: ```sh git fetch origin "$BASE_BRANCH" # If the target branch already exists, ask the user: # - reuse it (e.g. you renamed and want to continue), # - delete and recreate fresh from BASE, # - or pick a different name. # Do NOT silently overwrite. git switch -c "$TARGET_BRANCH" "origin/$BASE_BRANCH" ``` Surface a one-liner to the user: `Branch: from (latest @ )`. ### 4. Per-task loop For each unchecked `- [ ]` task in plan order: #### (a) Implementer subagent Spawn a `general-purpose` subagent at `model: sonnet` (per `subagent-model-routing`) with Edit/Write/Bash. Build the prompt per [reference.md → Implementer prompt template](reference.md#implementer-prompt-template). **Critical**: the parent reads the task's named files **once** and injects content inline. The subagent must NOT re-read them — that defeats the delegation and risks reading a different version. The subagent returns one of: `DONE` / `DONE_WITH_CONCERNS` / `BLOCKED` / `NEEDS_CONTEXT`. Implementer must probe before claiming DONE — run the verification command, grep for the expected change, do not paraphrase "should work" as evidence. Per `~/.claude/rules/probe-not-assume.md`. #### (b) Verify in parent Run the `verify-when-complete` skill in the parent process (fmt → lint → build → test). This is not delegated — completion claims require fresh, parent-visible evidence (per Superpowers' verification-before-completion rule). On failure: loop back to (a) with the failure output appended to the implementer's context. Max **2 retries**. Then escalate per step 4. #### (c) Reviewer subagent dispatch Determine which reviewers apply based on what changed in this task. Use the table in [reference.md → Reviewer dispatch](reference.md#reviewer-dispatch). Run reviewers **serially**, not parallel — they all comment on the same diff and parallel runs produce duplicated findings. Use `model: opus` for reviewers. Deeper judgment than the implementer, and the model-mismatch partially defeats self-agreement bias when implementer and reviewer are otherwise the same family. #### (d) Triage findings In the parent: - **P0, P1, `bug`, `risk`** → loop back to (a) with the finding text. Max **2 retries**. Then escalate. - **P2, P3, `nit`** → append to `./.plans/nits.md` (a plan-scoped accumulator). Non-blocking. Create the parent dir if needed. #### (e) Commit One commit per task that leaves the tree buildable (per `commit-per-phase` rule). Conventional Commits subject. No `--amend` ever (per `git-no-amend` rule). If the task is intentionally mid-refactor and would leave the tree non-buildable, include `[skip-bisect]` in the commit message. #### (f) Tick the checkbox Edit the plan file in place: `- [ ]` → `- [x]`. **Do not** add the plan file to commit (e) — plans under `.plans/` are gitignored and progress is tracked on disk only. For legacy plans (under `docs/plans/` or root `PLAN.md`) that the user has explicitly committed, including the tickmark in the same commit is fine. #### (g) Next Move to the next unchecked task. Do not pause to ask "should I continue?" — that is one of the named red flags (see [reference.md → Red flags](reference.md#red-flags)). ### Halt conditions (during the task loop) Halt the loop and surface to the user when any of: - Implementer returns `BLOCKED` or `NEEDS_CONTEXT`. - The same error has appeared 3 iterations on the same task (kill criterion). - A reviewer P0 finding has not been resolved within 2 retries. - The implementer encounters an architectural decision that is not in the plan (per `escalation` rule — never invent). - A destructive operation appears at execution time (even if review-plan didn't block it — double-check at the moment of action per `defer-external-orchestration`). Surface: current task number, status line, last subagent return, and the specific decision needed. Do not auto-resume after escalation — wait for the user. ### 5. End-of-plan handoff When all `- [ ]` tasks are `- [x]`: 1. **Spawn `review-all`** across the full branch diff against the plan's base ref. Surface its findings as one final cross-cutting review. 2. **Verify the Behavior delta** (if the plan has one, captured in step 1). For each `ADDED` / `MODIFIED` entry, run its `Acceptance:` criterion against the built branch and confirm it holds. Per-task verification proved the mechanisms ran; acceptance criteria prove the behavior. Surface any unmet criterion as a blocker — do not declare the plan done with an unsatisfied acceptance criterion. 3. **Surface the nits file** (`./.plans/nits.md`). Ask: address now, defer, or discard? 4. **Do NOT auto-create the PR** (per `defer-external-orchestration`). Print the suggested command, e.g.: ``` gh pr create --draft --title "" --body "<...>" ``` Wait for the user to run it. --- ## Output (user-facing status updates) Per `terse-output`: one sentence per key moment. Not every step. Examples: - `Preconditions OK. Plan: .plans/2026-05-16-auth-rewrite.md (8 tasks).` — Step 1 done - `review-plan: READY (3 nits noted)` — Step 2 done - `Branch: impl/2026-05-16-auth-rewrite from origin/main (@a1b2c3d).` — Step 3 done (new branch) — or - `Resuming on impl/2026-05-16-auth-rewrite (3/8 tasks already done).` — Step 3 done (resume mode) - `Task 4/8: starting (touches internal/auth/jwt.go)` — task start - `Task 4/8: DONE; review-code clean; committed feat(auth): add JWT validator` — task end (single line) - `Task 5/8: implementer returned BLOCKED — needs cache library choice. Halting.` — escalation - `All 8 tasks complete. Running review-all.` — handoff to end-of-plan Silence between these is fine. Don't narrate deliberation. --- ## Plan path conventions - Plans live in `./.plans/` (working directory; typically a repo root). `./.plans/PLAN.md` is the ad-hoc single-plan path. - Filename convention: `YYYY-MM-DD-.md` (matches Superpowers' convention and most "writing-plans" skills). - `./.plans/` is gitignored on first use via `~/.claude/scripts/ensure-gitignore.sh '.plans/'`. Plans are **working artifacts**, not source — they are not committed and not pushed in PRs. - Legacy paths (`./PLAN.md`, `./docs/plans/*.md`) remain readable for one transition release; on resolve, the skill warns once. Move to `.plans/` at convenience. - This skill does not create plans. Use Claude Code's native Plan mode or a future writing-plans skill upstream. - Plans may declare branch policy in a `## Branch policy` section near the top — see [reference.md → Plan header conventions](reference.md#plan-header-conventions). Absence means: fresh branch off `origin/`. - Project `CLAUDE.md` / `CLAUDE.local.md` may override the plans dir with a `Plans live in ` directive. When overridden, the skill skips the gitignore bootstrap. --- ## Cross-references - Pre-flight: `review-plan` - Post-implementation gate: `verify-when-complete` - Reviewer dispatch: `review-code`, `review-infrastructure`, `review-ci`, `review-database`, `review-security`, `review-observability`, `review-api-compat` - End-of-plan: `review-all` - Rules consulted: `subagent-prompt-contract`, `subagent-model-routing`, `parallelize-subagents`, `commit-per-phase`, `escalation`, `defer-external-orchestration`, `minimal-changes`, `implementation-minimalism`, `confirm-before-implementing`, `git-no-amend`, `terse-output`, `auto-verify-after-rebase` (applies to the chained-PR case if a rebase is needed mid-loop), `probe-not-assume` For detailed subagent prompt templates, the reviewer dispatch table, and the red-flag rationalization table, see [reference.md](reference.md). --- ## Sources - [obra/superpowers: subagent-driven-development](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md), used under [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE), copyright Jesse Vincent. The orchestrator-with-personas pattern and "do not trust the report" reviewer framing are drawn from this skill. - [Addy Osmani: Code Agent Orchestra](https://addyosmani.com/blog/code-agent-orchestra/) — Ralph Loop, kill criteria, focused-context-per-agent. - [Karpathy: Sequoia Ascent 2026](https://karpathy.bearblog.dev/sequoia-ascent-2026/) — context-as-program, specs-in-files-not-prompts.