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.

Parse arguments:

• --parallel flag: Enable parallel execution via subagents
• --headless flag: Auto-proceed through all confirmation steps (no AskUserQuestion calls). Used by /ideation:autopilot to run phases without blocking. In headless mode: scout HOLD → proceed anyway, review cycle 3 FAIL → report failure and stop (do not commit), spec selection → pick first unblocked.
• 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

If argument provided: Read the spec file directly.

If no argument: Auto-detect from task list:

1. Run TaskList to find existing phase tasks
2. Look for tasks with:
   • status: pending (not started)
   • Empty blockedBy (dependencies completed)
   • Subject starting with "Phase" or metadata containing specFile
3. If found, use TaskGet to read the task's specFile from metadata or description
4. Read that spec file

Fallback (no tasks found): Search for specs manually:

./docs/ideation/*/spec-phase-*.md

If multiple found, use AskUserQuestion to select one. Headless mode: pick the first unblocked spec.

2. Scout Codebase

Invoke the Scout agent to explore the codebase and produce a structured context map. The scout replaces manual codebase exploration — it runs as a read-only subagent, scores implementation readiness, and persists its findings.

Determine the project directory from the spec file path. If the spec is at docs/ideation/my-project/spec-phase-1.md, the project directory is docs/ideation/my-project/.

Invoke the Scout using the Agent tool:

1. Read ${CLAUDE_PLUGIN_ROOT}/agents/scout.md to get the scout's full workflow and output format
2. Use the Agent tool with:
   • subagent_type: general-purpose
   • prompt: Include the full content of scout.md as the agent's instructions, followed by the specific inputs: spec file path, project directory, phase number, and whether a prior context-map.md exists

Note on tool restrictions: The scout's frontmatter declares tools: ["Read", "Glob", "Grep"], but when invoked as a general-purpose subagent, these restrictions are policy-based (enforced by the prompt), not mechanism-based. The scout prompt instructs read-only behavior.

The scout may perform up to 2 internal exploration rounds before reaching a verdict. Execute-spec waits for the final output — it does not re-invoke the scout.

After the scout completes, parse the scout's text response for the context map and verdict. Write the context map to {project-directory}/context-map.md using the Write tool (the scout cannot write files itself — it returns the map as text).

If scout returns GO (confidence >= 70):

• The context map is ready. Use its sections during implementation:
  • Key Patterns: Already-identified patterns to follow (avoid redundant file reads)
  • Dependencies: Know what's affected by your changes
  • Conventions: Naming, imports, error handling to match
  • Risks: Watch for these during build
• Proceed to spec parsing

If scout returns HOLD (confidence < 70):

• The scout couldn't confidently map the codebase. Present the gap analysis to the user via AskUserQuestion (headless mode: auto-select "Proceed anyway"):

Question: "Scout confidence is {score}/100 (below 70 threshold). Gaps: {summary of lowest dimensions}. 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.

If the user chose "Proceed anyway" after HOLD: The context map (if produced) may have gaps. During build, treat missing context map sections as unavailable and read files directly for those areas. Pay extra attention to the Risks section of a partial context map.

If no scout agent is available (agent file missing or invocation fails): Fall back to inline exploration and log a warning. The inline fallback is:

1. Read all "Pattern to follow" file paths from the spec
2. Read all files in the spec's "Modified Files" section
3. If creating files alongside existing analogues, read the analogues
4. Use Grep to check what imports or references the modified files (blast radius)
5. Read CLAUDE.md or project README for conventions

3. Parse Spec Structure

Extract from the spec file (and template if applicable):

• Technical Approach - Overall implementation strategy
• File Changes - New files, modified files, deleted files
• Implementation Details - Per-component instructions with code patterns
• Testing Requirements - Unit tests, integration tests, manual testing
• Validation Commands - Commands to verify implementation
• Feedback Strategy - Top-level inner-loop command and playground type (if present)
• Per-component Feedback Loops - Playground, experiment, and check command for each component (if present)

Also extract and retain for the review cycle:

• Pattern file list — scan all components' Implementation Details for "Pattern to follow" entries. Collect every referenced file path into a single list. This list is passed to the reviewer agent during the post-execution review cycle. Keep it available throughout the build and review phases.

4. Check or Create Implementation Tasks

If tasks already exist (detected in Step 1 from TaskList):

• Skip task creation
• The phase task is the parent; component tasks may already exist
• Mark the phase task as in_progress and proceed to execution

If no tasks exist (fresh execution):

Use TaskCreate to create structured tasks from the spec's Implementation Details:

For each component, create a task with:

• subject: Component name from the spec
• description: Implementation steps, file changes, and validation criteria from the spec's Implementation Details section
• activeForm: "Implementing {component name}"

After creating all component tasks, add dependency relationships using TaskUpdate with addBlockedBy — if Component B depends on Component A, mark B as blocked by A's task ID.

Create validation tasks (blocked by all component tasks):

• "Run validation commands" — execute all validation commands from spec
• "Verify acceptance criteria" — review each acceptance criterion from spec

5. Establish Task Dependencies

Parse the spec's Implementation Details for component order:

1. Identify dependencies: Check "File Changes" for overlapping files
2. Create blocking relationships:
   • Sequential components: Component N blocked by Component N-1
   • Independent components: No blockers (can run in parallel)
3. Validation tasks: Blocked by ALL component tasks

6. Set Up Feedback Environment

Before implementing any component, establish the spec's feedback environment. This is a one-time setup.

1. Read the Feedback Strategy section from the spec. Identify the playground type and inner-loop command.

2. Auto-detect feedback infrastructure — even if the spec has no Feedback Strategy section, probe the codebase:

   • Read package.json (or equivalent manifest) for scripts: test, dev, start, storybook, typecheck
   • Check for test runner configs: jest.config.*, vitest.config.*, .mocharc.*, pytest.ini, go.mod (for go test)
   • Check for dev server configs: vite.config.*, next.config.*, webpack.config.*
   • Check for storybook: .storybook/ directory
   • Check for existing script harnesses: scripts/, bin/, Makefile

3. Set up the playground if it requires infrastructure:

   • Test runner: Verify the test command works (even with no tests yet — confirm the runner doesn't crash)
   • Dev server: Start it and verify it's running
   • Storybook/harness: Start it if the spec calls for one

4. Verify the inner-loop command runs (even if it does nothing yet). This catches environment issues before they block implementation.

5. Fallback: If no Feedback Strategy in the spec AND no feedback infrastructure detected, fall back to Validation Commands as the post-implementation check. Not all specs will have feedback loops.

7. Initialize Implementation Notes

Create {project-directory}/implementation-notes-phase-{n}.html — a running log of decisions made during implementation that weren't covered by the spec. This is for the human to review after execution.

Write the HTML shell once using the base styles from ${CLAUDE_PLUGIN_ROOT}/skills/ideation/references/html-guide.md (Section 1: Base Styles only — no tabs, sliders, or interactive components needed). The document should have:

• Title: "Implementation Notes — Phase {N}"
• Empty <main> element where entries will be appended

When to log an entry — append a <section> to the notes file whenever you encounter:

• Spec gap: The spec didn't address something and you had to make a judgment call
• Spec deviation: You intentionally diverged from the spec (and why)
• Tradeoff: Multiple valid approaches existed, you picked one
• Codebase surprise: Existing code was in an unexpected state that affected implementation
• Dependency decision: A dependency version, API, or behavior differed from what the spec assumed

Entry format — each entry is a simple card:

<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 — only decisions where the human would benefit from knowing what happened. If the spec was clear and you followed it, there's nothing to log.

If no entries are logged by the end of the phase, delete the empty HTML file rather than leaving an empty document.

Build Phase

Check Task Progress

Before starting, use TaskList to see current state:

• Find tasks with status: pending and empty blockedBy (ready to work)
• Skip tasks already completed by previous sessions

Consult the context map: Before reading pattern files or exploring the codebase during build, check the scout's context map for:

• Key patterns already identified (avoid redundant reads)
• Dependency information (know what's affected by your changes)
• Conventions to follow (naming, imports, error handling)
• Risks to watch for during implementation

For Each Component

1. Claim the task: TaskUpdate({ taskId, status: "in_progress" })
2. Read the component's implementation details from task description
3. Read before writing — If modifying existing files, read them first. If creating files alongside existing analogues, read the analogues to match patterns.
4. Set up component feedback loop (if the component has one): a. Create the playground artifact first (e.g., create the test file with a describe block, create the script harness, prepare the component in isolation) b. Run the check command once to verify the loop works (expect it to pass trivially or fail with "not implemented" — either is fine, as long as the command itself runs)
5. Build incrementally: a. Follow the pattern specified (if "Pattern to follow" is listed) b. Implement a meaningful chunk (one function, one handler, one subcomponent) c. Run the component's check command (or the spec's inner-loop command if no component-specific one) d. If the check fails: read the output, fix, re-run. Iterate until passing. e. Move to the next chunk. Repeat.
6. Run the component's experiment (if specified) — the parameterized check with specific inputs. This catches edge cases the basic check command might miss.
7. Complete: TaskUpdate({ taskId, status: "completed" })

If the component has no feedback loop: Fall back to the original flow — implement fully, then run validation commands.

Component Completion

After implementing a component:

1. Run the component's experiment if defined (edge cases, parameterized inputs)
2. Run the spec's inner-loop command (top-level quick check) to verify nothing regressed
3. Mark task as completed via TaskUpdate
4. Use TaskList to find next unblocked task
5. Report any issues before proceeding

Handling Issues

If validation fails:

1. Keep task as in_progress (don't mark completed)
2. Report the error clearly
3. Attempt to fix based on error message
4. Re-run validation
5. If still failing, pause and ask user

Parallel Execution (with --parallel flag)

Default (no flag): Sequential execution — work through unblocked tasks one at a time.

With --parallel flag: Spawn subagents for independent components:

1. Check TaskList for all tasks with status: pending and empty blockedBy
2. If only one unblocked task exists, execute it directly (no parallelism needed)
3. If multiple unblocked tasks exist:
   • Keep one task for the current session
   • For each additional unblocked task, spawn a subagent using the Agent tool with:
     • prompt: Include the task ID, the spec file path, and a summary of the technical approach so the subagent has full context
     • subagent_type: general-purpose
     • mode: default
   • Each subagent should: claim its task via TaskUpdate, read the spec file, implement the component following the same execution flow above, and mark the task completed
4. Coordination: Subagents share the TaskList. When a subagent completes its task, newly unblocked tasks become available. The parent session monitors TaskList for completion.
5. Error handling: If a subagent fails or a task stays in_progress for too long, the parent session should check TaskList, read the task description for context, and either retry or ask the user.
6. File conflicts: If two unblocked components modify the same file, do NOT parallelize them — execute sequentially to avoid merge conflicts. Check the spec's "File Changes" sections for overlap before spawning.

Review cycle in parallel mode: Subagents only build — they do not run their own review cycles. After all subagents complete their components, the main session runs a single verify-review-fix loop on the combined diff (git diff HEAD covers all changes from all sessions). This avoids the problem of interleaved diffs from multiple sessions writing to the same working tree.

Post-Execution: Verify-Review-Fix Loop

After all component tasks are completed, enter the review cycle. Code is not committed until the review passes or the user explicitly accepts remaining issues.

Do not stage files until after the review passes. The reviewer uses git diff HEAD to see all changes. Keep changes unstaged during the review cycle so the diff is clean and complete.

Verify

Run all commands from the spec's "Validation Commands" section:

• Type check
• Lint
• Tests
• Build

If any validation command fails, fix the issue before proceeding to review. Do not invoke the reviewer with failing validations — those are mechanical errors, not review findings. Validation failures do not consume a review cycle.

Review (Cycle 1 of max 3)

If git diff is empty (no changes to review): Skip the review cycle entirely. Report that all components were no-ops and proceed to the completion report.

Invoke the Reviewer agent using the Agent tool:

1. Read ${CLAUDE_PLUGIN_ROOT}/agents/reviewer.md to get the reviewer's full workflow and output format
2. Use the Agent tool with:
   • subagent_type: general-purpose
   • prompt: Include the full content of reviewer.md as the agent's instructions, followed by:
     • The spec file path
     • The pattern file list (collected during spec parsing in Section 3)
     • The cycle number (1, 2, or 3)
     • If cycle > 1: the prior cycle's findings so the reviewer can track what was fixed

Note on tool restrictions: The reviewer's frontmatter declares tools: ["Read", "Grep", "Bash"], but when invoked as a general-purpose subagent, these restrictions are policy-based. The reviewer prompt instructs it to only use Bash for git diff HEAD commands and to never edit files.

Cycle counter rule: The cycle number increments only when the reviewer is invoked. Verify failures and their fix iterations do not count as review cycles. Cycle N means the reviewer has been invoked N times.

Parse the reviewer's output:

1. Look for the verdict line: **Verdict**: PASS or **Verdict**: FAIL
2. Count findings by severity: lines starting with critical/, high/, medium/, low/
3. If zero critical AND zero high → PASS
4. If any critical or high → FAIL

If the reviewer fails, returns empty output, or returns output with no verdict line: Fall back to validation-only mode — treat validation command results as sufficient. Log a warning that the review cycle was skipped due to reviewer failure. Continue to commit.

On PASS

Review passed. Proceed to commit and completion report.

Report medium and low findings to the user for awareness, but they do not block the commit.

On FAIL (Cycle < 3)

1. Read each critical and high finding from the reviewer's output
2. For each finding, apply the suggested fix (the → action part of each finding)
3. After all fixes applied, re-run Verify (all validation commands)
4. If verify passes, invoke Review again (increment cycle number)
5. If verify fails after fixes, fix the validation errors first, then re-review

On FAIL (Cycle = 3, final)

Escalation. The review has failed 3 times. Present remaining findings to the user via AskUserQuestion (headless mode: 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.

If "Fix manually": Stop execution. User will fix and re-invoke.

If "Accept with issues": Proceed to commit. Include all unresolved findings in the completion report under "Acknowledged Issues."

If "Abort": Stop execution. Do not commit. Report the current state.

Commit

Only reached after PASS or user acceptance:

1. Stage all changed files relevant to this phase (use specific file names, not git add -A)
2. Commit with a descriptive message following the project's commit conventions
3. If review took multiple cycles, include the cycle count in the commit body

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 presenting the completion report, if implementation notes exist, open them in the browser: open {project-directory}/implementation-notes-phase-{N}.html

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, don't argue - When the reviewer flags an issue, fix it. Don't rationalize why the deviation is acceptable.
10. Escalate, don't loop forever - 3 cycles max. If the same findings persist, the spec or approach needs human input.