execute-spec

name	execute-spec
description	Execute an implementation spec generated by ideation. Invokes Scout for codebase exploration, builds components with feedback loops, then runs a Verify-Review-Fix cycle with the Reviewer agent before committing.
disable-model-invocation	true
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","TaskCreate","TaskUpdate","TaskList","TaskGet","Agent","AskUserQuestion"]

Execute Ideation Specification

Arguments: $ARGUMENTS

Execute a spec file generated by the ideation skill.

Flags:

• --parallel — dispatch subagents for independent components.
• --headless — auto-proceed through every confirmation (no AskUserQuestion). Used by /ideation:autopilot. Headless resolutions, by decision point: spec selection → first unblocked; scout HOLD → proceed anyway; review cycle 3 FAIL → report failure and stop (do not commit).
• --strict — modifies --headless to fail closed at the two decision points that otherwise fail open: scout HOLD → report the gap analysis and stop (do not build); reviewer failure/empty/no verdict → do not fall back to validation-only — report FAIL and stop without committing. Set by autopilot for express-approved contracts (approvalMode: "express" in contract-data.json), whose artifacts no human reviewed — the auto-proceed defaults are calibrated for reviewed artifacts and don't apply.
• Remaining argument: spec file path (optional).

Example: /ideation:execute-spec --parallel or /ideation:execute-spec --headless docs/ideation/foo/spec-phase-1.md

Pre-Execution

1. Load Specification

Resolve the spec in this order:

1. Argument given — read it directly.
2. No argument — auto-detect from TaskList: a task with status: pending, empty blockedBy, and a subject starting with "Phase" or metadata containing specFile. Read its specFile (via TaskGet).
3. No tasks — glob ./docs/ideation/*/spec-phase-*.md and ./docs/ideation/*/spec.md (single-spec projects emit a bare spec.md). Multiple matches → AskUserQuestion to pick (headless: first unblocked).

2. Scout Codebase

Invoke the read-only Scout to map the codebase and assess readiness across 5 evidence gates — it replaces manual exploration and persists its findings.

The project directory is the spec's parent (spec docs/ideation/my-project/spec-phase-1.md → docs/ideation/my-project/).

Invoke Agent with subagent_type: ideation:scout. The prompt carries per-invocation inputs only: spec path, project directory, phase number, whether a prior context-map.md exists. Workflow, output format, and read-only tools come from the registered definition (the platform enforces tools; the scout cannot edit). It runs up to 2 internal rounds before a verdict — wait for the final output, do not re-invoke.

The scout returns the context map as text; Write it to {project-directory}/context-map.md (it cannot write files itself).

• GO (Scope clarity ready AND ≥ 4/5 gates ready): the map is ready — use its Key Patterns (avoid redundant reads), Dependencies, Conventions, and Risks during build. Proceed.
• HOLD (Scope clarity not-ready, or < 4/5 gates ready): present the gap analysis via AskUserQuestion (headless: auto-select "Proceed anyway"; headless + --strict: report the gap analysis and stop — an under-specified spec that no human reviewed is a stop condition, not a proceed condition):

Question: "Scout reports {n}/5 readiness gates passed ({not-ready gates}). How to proceed?"
Options:
- "Proceed anyway" — Build with known gaps. May require more iteration.
- "Update spec" — The spec may be underspecified. Pause to revise.
- "Abort" — Stop execution for this phase.

After "Proceed anyway", treat missing context-map sections as unavailable (read those files directly) and watch the Risks section closely.

If ideation:scout is unregistered (older Claude Code, or plugin not installed): log a warning and explore inline — read the spec's "Pattern to follow" paths and all "Modified Files"; read analogues for new files; Grep the blast radius of modified files; read CLAUDE.md/README for conventions.

3. Parse Spec Structure

Extract: Technical Approach, Decisions Considered and Rejected (the decision log — alternatives the contract rejected and why, if present), File Changes, Implementation Details (per-component instructions + code patterns), Testing Requirements, Validation Commands, Feedback Strategy (inner-loop command + playground type, if present), per-component feedback loops (playground/experiment/check, if present).

Collect the pattern file list: scan every component's Implementation Details for "Pattern to follow" entries into one list. Retain it through build and review — it is passed to the reviewer.

4. Tasks

Tasks already exist (from Step 1): skip creation; mark the phase task in_progress and proceed.

Fresh execution: TaskCreate one task per component (subject = component name, description = its Implementation Details, activeForm = "Implementing {name}"). Then wire dependencies with TaskUpdate addBlockedBy: components that share a file or that the spec orders are sequential; independent components have no blocker. Create two validation tasks blocked by all components: "Run validation commands" and "Verify acceptance criteria".

5. Set Up Feedback Environment

One-time setup before building. Read the spec's Feedback Strategy for the playground type and inner-loop command. Auto-detect infrastructure even when the spec omits it: package.json scripts (test/dev/start/storybook/typecheck), test-runner configs (jest/vitest/mocha/pytest/go.mod), dev-server configs (vite/next/webpack), .storybook/, and harnesses (scripts/, bin/, Makefile). Start whatever the playground needs (test runner, dev server, storybook) and run the inner-loop command once to confirm it works — this catches environment issues early. Fallback: no Feedback Strategy and no infrastructure detected → use Validation Commands as the post-implementation check.

6. Initialize Implementation Notes

Maintain {project-directory}/implementation-notes-phase-{n}.html — a running log of decisions not covered by the spec, for the human to review. Create the file lazily, on the first logged entry (not upfront): write the shell using Section 1 (Base Styles only) of ${CLAUDE_PLUGIN_ROOT}/skills/ideation/references/html-guide.md — title "Implementation Notes — Phase {N}" and a <main> holding the entry — then append subsequent entries. A clean phase with zero entries means no file ever exists, which avoids create-then-delete churn.

Before deciding anywhere the spec is silent, consult the decision log (the spec's Decisions Considered and Rejected section): if the approach you're about to take matches a rejected entry, treat it as a spec conflict — escalate rather than proceed, citing the log entry.

Log an entry for a spec gap (had to make a judgment call), spec deviation (and why), tradeoff (multiple valid approaches), codebase surprise, or dependency mismatch. Format:

<section class="note-entry">
  <h3>{Component Name} — {short decision title}</h3>
  <dl>
    <dt>Context</dt>
    <dd>{what the spec said, or didn't say}</dd>
    <dt>Decision</dt>
    <dd>{what you chose and why}</dd>
    <dt>Alternative</dt>
    <dd>{what you considered but rejected}</dd>
  </dl>
</section>

Don't log routine implementation.

Build Phase

TaskList for current state; work tasks with status: pending and empty blockedBy, skip completed ones. Before reading pattern files, consult the scout's context map (key patterns, dependencies, conventions, risks) to avoid redundant exploration.

For Each Component

1. Claim it (TaskUpdate status: in_progress).
2. Read its Implementation Details.
3. Read before writing — read files you'll modify; read analogues for new files.
4. Set up its feedback loop (if any): create the playground artifact (test file, harness, isolated component), then run the check command once to confirm the loop runs (a trivial pass or "not implemented" failure is fine).
5. Build incrementally: follow any "Pattern to follow"; implement a chunk; run the check command (or the spec's inner-loop command); on failure, read output, fix, re-run until passing; repeat per chunk.
6. Run the experiment (if specified) — the parameterized check for edge cases.
7. Complete (TaskUpdate status: completed), then TaskList for the next unblocked task. Report any issues before proceeding.

No feedback loop → implement fully, then run validation commands. If validation fails: keep the task in_progress, report the error, fix, re-run; if still failing, pause and ask the user.

Parallel Execution (--parallel)

Default is sequential. With --parallel, dispatch subagents wave by wave, with waves planned by the tested wave-planner CLI — not ad-hoc rules. Pattern: skills/autopilot/SKILL.md Step 3 (same { title, prereqs, files } manifest; skill prepares the manifest, tested code plans the waves).

1. Build a component manifest, one entry per component: title (matches the task subject), prereqs (titles it's blocked by), files (every path it touches from its File Changes rows). Unattributable files → give that component ALL declared files (serializes it against everything).

2. Plan the waves:

   node ${CLAUDE_PLUGIN_ROOT}/workflows/wave-planner.mjs plan '<manifest-json>'
   

   Payload { "phases": [ ...entries... ] }. The CLI prints a prereq-ordered string[][] of waves, with any file-sharing wave already split into sequential sub-waves. These waves are authoritative — no separate file-conflict rule.

3. Dispatch each wave as subagents (subagent_type: general-purpose, mode: default), prompt carrying the task ID, spec path, and technical-approach summary. Each subagent claims its task, implements following the per-component flow, and completes it. Wait for the whole wave before the next (wave barrier). On failure/stall: check TaskList, read the task, retry or ask the user.

4. CLI fails (node missing, malformed manifest, dependency cycle) → fall back to fully sequential execution and warn. Never fall back to unchecked parallelism — it could race two components on one file.

Subagents only build; they do not run review cycles. After all complete, the main session runs one verify-review-fix loop on the combined diff (git diff HEAD).

Post-Execution: Verify-Review-Fix Loop

Code is not committed until review passes or the user accepts remaining issues. Do not stage files until after review passes — the reviewer reads git diff HEAD, so keep changes unstaged for a clean, complete diff. One exception: git diff HEAD is blind to untracked files, so first register every net-new file with git add -N <path> (intent-to-add — the file appears in the diff without its content being staged). Without this, a phase whose only output is new files produces an empty diff: review gets wrongly skipped and the work never commits.

Verify

Run all of the spec's Validation Commands (type check, lint, tests, build). Fix any failure before review — validation failures are mechanical errors, not review findings, and do not consume a review cycle.

Review (Cycle 1 of max 3)

Empty diff (after git add -N of new files) → skip review entirely; report the components as no-ops and go to the completion report.

Invoke Agent with subagent_type: ideation:reviewer. Per-invocation inputs only (workflow/format/tools come from the registered definition; tools is platform-enforced — Bash for git diff HEAD/git log only, never edits): spec path, the pattern file list (from Section 3), the cycle number, and — if cycle > 1 — the prior cycle's findings, including any the builder refuted (marked [REFUTED: evidence]) so the reviewer re-examines them.

Cycle counter: increments only when the reviewer is invoked. Verify failures and their fixes never count.

Parse the output: find **Verdict**: PASS/FAIL; count findings by severity prefix (critical/, high/, medium/, low/). Zero critical AND zero high → PASS; any critical or high → FAIL.

If the reviewer fails, returns empty, or has no verdict line: fall back to validation-only mode (validation results are sufficient), warn that review was skipped, and continue to commit. With --strict: do not fall back — report FAIL (reviewer unavailable) with the validation results and stop without committing; unreviewed code from an unreviewed spec never lands silently.

On PASS

Proceed to commit. Report medium/low findings for awareness — they do not block.

On FAIL (Cycle < 3)

For each critical/high finding, verify before acting — read the target code, then:

• Finding correct (the default — most are): apply its suggested → action.
• Code demonstrably contradicts it: you may refute instead. A refutation requires file:line evidence proving the finding wrong. Log an implementation-notes entry (Context = finding verbatim, Decision = refutation + evidence, Alternative = the fix not applied), and carry the finding into the next cycle as [REFUTED: evidence] so the reviewer withdraws it or restates it as "Maintained despite refutation". Refute at most once per finding — a maintained refutation is real: fix it (or escalate at cycle 3). Never refute the same finding twice.

After fixes (and any refutations logged), re-run Verify; if it passes, Review again (increment cycle, passing refuted findings); if verify fails, fix those errors first, then re-review.

Headless: a refuted-then-maintained finding counts as unresolved — cycle-3 FAIL semantics apply (report FAIL, stop, no commit).

On FAIL (Cycle = 3, final)

The review has failed 3 times. Escalate via AskUserQuestion (headless: do not commit — report FAIL with findings and stop):

Question: "Review cycle 3 still has {N} critical/high findings. How to proceed?"
Options:
- "Fix manually" — You fix the remaining issues yourself. Re-run /ideation:execute-spec after fixing to re-enter the review cycle.
- "Accept with issues" — Commit with known issues. Findings included in completion report as acknowledged items.
- "Abort" — Do not commit. Leave changes unstaged for manual review.

• Fix manually: stop; user fixes and re-invokes.
• Accept with issues: commit; list unresolved findings under "Acknowledged Issues" in the report.
• Abort: stop, do not commit, report current state.

Commit

Only after PASS or user acceptance: stage the phase's changed files by name (never git add -A), commit following the project's conventions, and include the cycle count in the body if review took multiple cycles. Process artifacts (context-map.md, implementation-notes-*.html) are working files, not phase deliverables — leave them out of the phase commit unless the project's conventions track docs/ideation/.

Completion Report

## Phase {N} Implementation Complete

### Implemented

- {List of components implemented}

### Files Changed

- {List of files created/modified}

### Implementation Notes

- {count} decisions logged → `implementation-notes-phase-{N}.html`
- {brief summary of most significant decisions, if any}

### Review Summary

- Cycles: {N} of 3 max
- Findings addressed: {count} ({critical} critical, {high} high auto-fixed)
- Remaining (non-blocking): {count} ({medium} medium, {low} low)
- Acknowledged issues: {count, if user accepted with issues}

### Validation Results

- Type check: PASS/FAIL
- Lint: PASS/FAIL
- Tests: PASS/FAIL

### Acceptance Criteria

- [x] {Met criteria}
- [ ] {Unmet criteria with notes}

### Next Steps

- Review implementation notes: `open docs/ideation/{project}/implementation-notes-phase-{N}.html`
- Review changes: `git log -1 --stat`
- For next phase: `/ideation:execute-spec spec-phase-{N+1}.md`

After the report, if implementation notes exist, open them: open {project-directory}/implementation-notes-phase-{N}.html.

Learning Capture (interactive runs only)

--headless runs skip this step entirely — never prompt, never write docs/ideation/learnings.md unattended; their notes wait for the interview engine's unmined-notes surfacing at the next interactive intake.

On an interactive run, after the completion report, if this run produced implementation notes or note-worthy gap decisions, apply the learning filter in ${CLAUDE_PLUGIN_ROOT}/references/learning-filter.md to them — bounded to the just-finished project's implementation-notes-phase-*.html and this run's noted decisions, never a repo-wide scan. The filter yields up to 3 candidates.

• Zero candidates → silence. No prompt, no output, no "nothing to capture" message — proceed as if this step didn't exist.
• Otherwise, ask ONE AskUserQuestion offering accept/edit/dismiss per candidate: a single multiSelect question with each candidate's text inline (selected = accept; "Other" = edit the wording, then treat as accepted; nothing selected = dismiss all).
• Write accepted entries to docs/ideation/learnings.md per the lifecycle rules in the filter reference: bootstrap header if the file is absent, "Also seen in" dedupe amendments, verified retirement of stale entries, dated entry format.

Key Principles

1. Read before writing — understand existing code and patterns before creating or modifying files.
2. Feedback loops over post-hoc validation — set up the check cycle before building, not after.
3. Fast inner loop — the check command should run in seconds.
4. Follow spec literally — don't improvise beyond what's specified.
5. Match existing patterns — new code should look like it belongs.
6. Human in loop — pause when uncertain, don't guess.
7. One phase at a time — complete this phase fully before moving on.
8. Review before commit — code is not committed until the reviewer passes or the user explicitly accepts.
9. Fix by default; refute only with evidence — fix what the reviewer flags. The one exception: refute a finding the code demonstrably contradicts, citing file:line proof, logged in implementation notes, never repeated for the same finding.
10. Escalate, don't loop forever — 3 cycles max. If the same findings persist, the spec or approach needs human input.