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