---
name: execute-spec
description: Execute an implementation spec generated by ideation. Invokes scout agent for codebase exploration, builds components with feedback loops, then runs a verify-review-fix cycle with the reviewer agent before committing.
---

# Execute Ideation Specification

## Arguments: $ARGUMENTS

Execute a spec file generated by the ideation skill.

**Parse arguments:**

- `--parallel` flag: Enable parallel execution via subagents
- Remaining argument: Spec file path (optional)

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

## Pre-Execution

### 1. Load Specification

**If argument provided:** Read the spec file directly.

**If no argument:** Search for specs:

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

If multiple found, ask the user to select one.

### 2. Scout Codebase

**Invoke the Scout agent** to explore the codebase and produce a structured context map. The scout 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 `subagent` tool:

- **agent**: `scout`
- **task**: Include the spec file path, project directory, phase number, and whether a prior `context-map.md` exists

The scout's agent definition (`agents/scout.md` in this package) instructs read-only behavior — it uses only `read`, `grep`, `find`, and `ls` tools.

The scout may perform up to 2 internal exploration rounds before reaching a verdict.

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

**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):

- Present the gap analysis to the user:

```
Scout confidence is {score}/100 (below 70 threshold).
Gaps: {summary of lowest dimensions}. How to proceed?

1. **Proceed anyway** — Build with known gaps. May require more iteration.
2. **Update spec** — The spec may be underspecified. Pause to revise.
3. **Abort** — Stop execution for this phase.
```

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

**If no scout agent is available** (subagent tool not installed or invocation fails): Fall back to inline exploration:

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 `AGENTS.md`, `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.

### 4. 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`
   - 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
   - **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.

## Build Phase

### For Each Component

Work through components in dependency order:

1. **Read** the component's implementation details
2. **Read before writing** — If modifying existing files, read them first. If creating files alongside existing analogues, read the analogues to match patterns.
3. **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)
   b. Run the check command once to verify the loop works
4. **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)
   d. If the check fails: read the output, fix, re-run. Iterate until passing.
   e. Move to the next chunk. Repeat.
5. **Run the component's experiment** (if specified) — the parameterized check with specific inputs.

### 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. Report any issues before proceeding to the next component

### Handling Issues

If validation fails:

1. Report the error clearly
2. Attempt to fix based on error message
3. Re-run validation
4. If still failing, pause and ask user

### Parallel Execution (with `--parallel` flag)

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

**With `--parallel` flag:** Use pi-subagents for independent components:

1. Identify components with no dependency on each other
2. If only one unblocked component, execute directly
3. If multiple unblocked components:
   - Use `/parallel worker "implement component A per spec" -> worker "implement component B per spec"`
   - Each subagent implements its component following the same build flow above
4. **File conflicts**: If two components modify the same file, do NOT parallelize them — execute sequentially to avoid conflicts.

**Review cycle in parallel mode**: Subagents only build — they do not run their own review cycles. After all components are complete, run a single verify-review-fix loop on the combined diff.

## Post-Execution: Verify-Review-Fix Loop

After all components 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.

### 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. 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 `subagent` tool:

- **agent**: `reviewer`
- **task**: Include the spec file path, the pattern file list (collected during spec parsing), the cycle number (1, 2, or 3), and if cycle > 1, the prior cycle's findings

The reviewer's agent definition (`agents/reviewer.md` in this package) instructs it to only use `bash` for `git diff HEAD` commands and to never edit files.

**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 or returns no verdict**: Fall back to validation-only mode — treat validation command results as sufficient. Log a warning. 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
2. Apply the suggested fix (the `→ action` part)
3. Re-run **Verify** (all validation commands)
4. If verify passes, invoke **Review** again (increment cycle number)

### On FAIL (Cycle = 3, final)

Escalation. Present remaining findings to the user:

```
Review cycle 3 still has {N} critical/high findings. How to proceed?

1. **Fix manually** — You fix the remaining issues yourself. Re-run /skill:execute-spec after fixing.
2. **Accept with issues** — Commit with known issues. Findings included in completion report.
3. **Abort** — Do not commit. Leave changes unstaged for manual review.
```

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

```markdown
## Phase {N} Implementation Complete

### Implemented
- {List of components implemented}

### Files Changed
- {List of files created/modified}

### 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 changes: `git log -1 --stat`
- For next phase: `/skill:execute-spec spec-phase-{N+1}.md`
```

## 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.
10. **Escalate, don't loop forever** - 3 cycles max. If the same findings persist, the spec or approach needs human input.