impl

name	impl
description	Execute the plan generated by /plan, one task at a time. Per-task — implement, verify acceptance criteria, optionally run simplify-review on large diffs, and mark complete. The final gate is /completion-audit → /subagent-review.
disable-model-invocation	true

Executes the plan produced by /plan, task by task. Sole source of truth for the per-task loop, deviation handling, simplify-review thresholds, final-gate orchestration, plan-adherence checking, and recovery after context compaction.

Quick Start

/impl              # Process every pending task in ID order

Preconditions

/impl executes the plan that /plan produced and that the user explicitly approved by typing /impl as a top-level prompt. There is no state file — approval is the user's keystroke, and the plan is resolved from context.

Plan resolution

1. Primary: the plan file path from the most recent /plan output in the conversation — the File: line of its ## Plan ready block.

2. Fallback (context lost to compaction): the newest non-log plan file under ~/.claude/plans/, resolved by mtime:

   stat -f '%m %N' ~/.claude/plans/*.md | grep -v '\.log\.md$' | sort -rn | head -1 | cut -d' ' -f2-
   

   stat is used instead of ls -t on purpose: this environment intermittently annotates ls output with a trailing size column, which breaks a \.log\.md$ line-anchored filter and can mis-select the .log.md sidecar. stat -f '%m %N' prints <mtime-epoch> <path> with the path last, so the anchor holds and the field is clean.

3. Fallback requires confirmation: the ~/.claude/plans/ directory is shared across sessions and repositories, so a mechanical newest-pick can select another session's plan. When resolving via the fallback, present the resolved path and the plan's title heading to the user and get explicit confirmation that it is the intended plan before starting any edits. Do not self-approve.

If no plan can be resolved, reject with Run /plan <request> first. No plan to execute.

Workflow

1. Resolve the plan file path per Preconditions → Plan resolution
2. Read the plan file in full so subsequent tasks can follow Files to Change and Patterns to Mirror faithfully
3. TaskList → process tasks in ascending ID order. Skip tasks with a non-empty blockedBy
4. For each task:
   1. TaskGet to retrieve the detailed description (target files / expected behavior / verification method)
   2. TaskUpdate to set in_progress and record metadata.baseline_sha (current git rev-parse HEAD)
   3. Implement — follow the plan's "Files to Change" and "Patterns to Mirror" exactly. Match the naming, error handling, and conventions captured by Phase 2 EXPLORE
   4. Run the acceptance-criteria verification commands. Capture the raw output verbatim into metadata.evidence (summarizing or paraphrasing is forbidden). The final gate (/completion-audit + /subagent-review) consumes this evidence
   5. Diff size check via git diff --stat. If the diff is ≥ 20 files or ≥ 500 lines, dispatch Agent({subagent_type: "code-simplifier", ...}) — the agent is defined in ~/.claude/agents/code-simplifier.md. Inline the changed files + git diff <baseline_sha>..HEAD + the project's CLAUDE.md path into the prompt. Apply HIGH-confidence simplifications; present MEDIUM/LOW to the user
   6. Once all acceptance-criteria verifications succeed, TaskUpdate to completed. There is no per-task review gate — quality and security are judged at the final gate
5. After all implementation tasks complete, the final Run /completion-audit and /subagent-review task unblocks automatically. Execute in this order:
   1. Invoke /completion-audit. Its default mode is a self-audit (main session cross-checks Completion Criteria × evidence and emits the table); a fresh completion-auditor subagent is dispatched only when an escalation condition fires (large/xl plan, evidence gaps, or explicit user request — see its SKILL.md). If the verdict is VERIFIED FAIL, address the surfaced gaps and re-run. On 3 consecutive FAILs on the escalated subagent path, leave the gate task in_progress, append [BLOCKED: completion-audit escalated] to the task description, and present the unresolved gap analysis to the user
   2. On VERIFIED PASS (self-audit or subagent), invoke /subagent-review against the aggregated diff (git diff <first-task baseline_sha>..HEAD). /subagent-review runs a unified Spec & Quality review → parallel orthogonal Domain specialists → Security heuristic internally. The Security step replaces the previous standalone Security Sweep. It must return PASS (no open MUST_FIX) to close the gate
   3. If /subagent-review returns PASS → mark the gate task complete and emit the final report
   4. If /subagent-review returns FAIL after internal retry exhaustion (3 tries per stage) → leave the task in_progress, append [BLOCKED: subagent-review escalated] to the description, and present the unresolved MUST_FIX issues to the user
6. Emit the final report: changed files / added tests / deviations / subagent-review verdict / verbatim transcription of /subagent-review's ## Mandatory Final Output block (no paraphrasing or summarization, regardless of PASS or FAIL) / suggested next steps. /santa-loop is NOT part of the default flow — run it manually if additional dual-reviewer (Claude + Codex) convergence is wanted before opening a PR

Three-element rule (enforced per task description)

Every task description must contain:

1. Target file(s) — the exact absolute path(s) to create or modify
2. Expected behavior after change — concrete observable outcome
3. Verification method — command + expected output

If any of the three is missing, stop and report. No improvisation — re-run /plan to fix the decomposition.

Deviation handling

If a task cannot be implemented as described (the plan is wrong, the environment differs, a missing dependency surfaces, etc.):

1. Stop before applying any deviation
2. Tell the user: (a) that the plan cannot be followed as-is, (b) why, (c) the alternative
3. Wait for explicit user approval (or correction)
4. No implicit plan changes — do not silently switch approach "because it's better"
5. After approval, proceed with the corrected approach. Record the deviation in the task's metadata.evidence for an audit trail

Re-planning (revising the plan mid-execution)

If the user wants to revise the plan during /impl:

1. Confirm: "Re-plan? (re-run /plan) — completed tasks will be preserved"
2. On approval:
   • Preserve all completed tasks (including metadata.evidence)
   • Delete all pending and in_progress tasks
   • Re-run /plan. The main session uses a summary list of existing completed tasks as context so the new decomposition does not duplicate finished work
3. After new tasks are created, resume /impl

Recovery after compaction

If context compaction occurs mid-/impl:

1. Re-resolve the plan path per Preconditions → Plan resolution (the fallback + confirmation rule applies whenever conversation context no longer carries the ## Plan ready File line)
2. TaskList → find tasks not yet completed
3. Re-Read the plan file
4. Resume from the lowest-ID pending (or stalled in_progress) task
5. For an in_progress task with partial work, inspect the diff to decide whether to continue or roll back and restart

Plan-adherence check at completion

The plan-vs-implementation comparison is /completion-audit's Step 1 (Evidence Collection) responsibility — /impl does not run a separate adherence check. Adherence gaps (items present in the plan but not implemented, items implemented but not in the plan, misinterpreted items) surface from the auditor's verdict.

When to dispatch the code-simplifier subagent

Condition	Action
Current task diff is ≥ 20 files or ≥ 500 lines	Spawn code-simplifier via the Agent tool
Diff is small	Skip — /subagent-review covers basic simplification
User explicitly said "skip simplify"	Skip with a note

Apply HIGH-confidence simplifications automatically (subtractive only, behavior-preserving). Present MEDIUM/LOW before changing.

When to invoke /subagent-review

/subagent-review is the second (quality/security) step of the final gate — it runs automatically once /completion-audit returns VERIFIED PASS. The user can also invoke it manually as a standalone review pass. There is no per-task review gate. The per-task cost stays bounded to acceptance-criteria verification only.

For /codex-review requests, follow the codex-review special rule in ~/.claude/CLAUDE.md — no partial execution allowed.

Final gate: /completion-audit → /subagent-review

The "Run /completion-audit and /subagent-review" task that /plan's Phase 5 (pass 2) creates lists all implementation tasks in its blockedBy. It unblocks automatically once they all complete.

Execution order is mandatory:

1. /completion-audit first — evidence-sufficiency audit (no re-execution; it reads per-task metadata.evidence against the plan's Completion Criteria). Default mode is a main-session self-audit table; a fresh completion-auditor subagent runs only on escalation (large/xl plan, evidence gaps, explicit user request). Must return VERIFIED PASS (self-audit or subagent) before continuing. On 3 consecutive FAILs on the escalated path, append [BLOCKED: completion-audit escalated] and present to the user
2. /subagent-review second — runs against the aggregated diff (git diff <first-task baseline_sha>..HEAD). Internally runs a unified Spec & Quality review → parallel orthogonal Domain specialists (all matching triggers dispatched in the same turn) → Security heuristic. The Security step uses ~/.claude/skills/subagent-review/references/security-trigger-heuristic.md and dispatches security-auditor only when a trigger fires. Must return PASS (no open MUST_FIX) to close the gate. On internal retry exhaustion (3 tries per stage), append [BLOCKED: subagent-review escalated] and present to the user

Mandatory user-facing transcription: regardless of overall verdict (PASS or FAIL), the final report MUST include /subagent-review's ## Mandatory Final Output block transcribed verbatim. Do NOT paraphrase, summarize, re-rank, or omit it on a clean PASS — SHOULD_FIX / NIT / Spec Notes / Security MEDIUM/LOW items live in that block and must reach the user unfiltered. When the block is the zero-finding shortcut (Non-blocker findings: none across all stages), emit that single line as-is.

/santa-loop is not part of the default final gate. Invoke it manually when additional dual-reviewer (Claude + Codex) convergence is wanted for higher-risk changes, e.g. before opening a PR. /santa-loop requires /completion-audit to have already returned VERIFIED PASS (see its SKILL.md preconditions).

/verification-loop is opt-in and invoked manually outside /impl (e.g. /verify before opening a PR). Use it when deterministic re-execution is genuinely needed. It is not part of the /impl flow because per-task acceptance verification already covers re-execution.