Execute Spec

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.
• --strict — modifies --headless to fail closed where plain headless fails open. Set by autopilot for express-approved contracts (approvalMode: "express" in contract-data.json), whose artifacts no human reviewed — the fail-open defaults are calibrated for reviewed artifacts.
• Remaining argument: spec file path (optional).

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

Headless/strict gate semantics — owned by workflows/README.md's gate-behavior table; when prose and engine disagree, the tests are right. Do not restate the matrix here — the original defect (strict specified to fail closed, actually improvising) shipped exactly because divergent prose copies drifted from the engine.

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

Under the autopilot Workflow engine, this step is superseded: the engine runs the scout as a sibling workflow stage and hands its map to the build stage under an explicit ENGINE OVERRIDES block (skip scout, stop after Verify, never commit, git add -N every new file) — see ${CLAUDE_PLUGIN_ROOT}/workflows/README.md. This section governs direct runs.

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. Agent names differ by harness — see ${CLAUDE_PLUGIN_ROOT}/references/harness-compat.md § 2: in pi, dispatch one task with the body of ${CLAUDE_PLUGIN_ROOT}/agents/scout.md as systemPrompt and the default read-only tools. The same translation applies to ideation:reviewer (below) and general-purpose (wave dispatch).

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/strict: per the gate-behavior table in workflows/README.md):

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): copy ${CLAUDE_PLUGIN_ROOT}/skills/execute-spec/references/implementation-notes.template.html verbatim, substitute {N}, {PROJECT}, {DATE}, and {PHASE DESCRIPTION}, and delete the marked example entry. The template is the single owner of the file shell and the note-entry format (a note-entry section with Context / Decision / Alternative — its example entry shows exactly the shape). Append subsequent entries inside <main class="doc-content">. 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. 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; in pi, one dispatch call per wave, one task per component — mutating tools require allowTreeMutation: true and serialize after the read-only batch — see ${CLAUDE_PLUGIN_ROOT}/references/harness-compat.md § 2), 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 — and they cannot spawn agents at all (a subagent has no Agent tool), so never instruct one to invoke the scout or reviewer. 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

Under the autopilot Workflow engine, Review, Fix, and Commit run as sibling workflow stages — the build stage stops after Verify per its ENGINE OVERRIDES (see ${CLAUDE_PLUGIN_ROOT}/workflows/README.md); this section governs direct runs, and the two must not drift.

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. (In pi, a dispatch task with the body of ${CLAUDE_PLUGIN_ROOT}/agents/reviewer.md as systemPrompt and tools: ['read', 'grep', 'bash'] — bash means the task also needs allowTreeMutation: true and runs after the read-only batch; see ${CLAUDE_PLUGIN_ROOT}/references/harness-compat.md § 2.)

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 and continue to commit — but the degradation must be loud and structural, never a log line. (A "review was skipped" warning in a headless log is how this plugin once shipped 6 phases of unreviewed code.) Concretely: record reviewStatus: validation-only in the phase result; make WARNING — UNREVIEWED CODE COMMITTED (validation-only) the first line of the Completion Report; and write Review: NOT RUN in the Review Summary, never a bare PASS. Whatever consumes the result (autopilot's completion report, the engine's run summary) must re-surface that warning, not swallow it. With --strict: do not fall back — report FAIL (reviewer unavailable) with the validation results and stop without committing (per the gate-behavior table in workflows/README.md); unreviewed code from an unreviewed spec never lands at all.

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. The commit body MUST contain the phase's slug-qualified specPath verbatim (e.g. docs/ideation/my-project/spec-phase-1.md) — autopilot's resume pre-pass and scripts/verify.mjs both grep commit bodies for exactly that string, so a commit that omits it makes the phase silently re-execute on resume and read as never-committed at verification. 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

- Review status: passed / validation-only (Review: NOT RUN) / accepted-with-issues
- 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

- {one row per Validation Command in the spec}: 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, run the Learning Capture step — bounded to the just-finished project's implementation-notes-phase-*.html and this run's noted gap-decisions — per ${CLAUDE_PLUGIN_ROOT}/references/learning-filter.md, the single owner of the procedure and the learnings.md lifecycle.

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.