# Execute Spec

> 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. Invoke only when the user explicitly asks to execute an ideation spec, or when an autopilot Workflow builder directs /ideation:execute-spec.

- Skill: `nicknisi/execute-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nicknisi/execute-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nicknisi/execute-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nicknisi (https://skillmd.com/u/nicknisi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nicknisi/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:**

   ```bash
   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

```markdown
## 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.