execute-spec

What this skill does

# 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