autopilot

Run Ideation Project

Arguments: $ARGUMENTS

Orchestrate the execution of all phases in an ideation project.

Parse arguments:

• Optional: path to contract.md (e.g., docs/ideation/my-project/contract.md)
• If omitted, auto-detect by globbing ./docs/ideation/*/contract.md
• If multiple contracts found, use AskUserQuestion to select one

Phase 1: Parse the Contract

Read contract.md and extract the Execution Plan:

1. Find the ## Execution Plan section
2. Parse the Dependency Graph — extract phase numbers, titles, and blocking relationships from the ASCII tree. Build an adjacency list:

{ 1: [], 2: [1], 3: [1], 4: [3] }

Where values are the phases that block each key.

1. Parse Execution Steps — extract spec file paths from the fenced bash blocks. Each /ideation:execute-spec path/to/spec.md line maps a phase number to its spec file.

2. Derive the project directory from the contract path. If the contract is at docs/ideation/my-project/contract.md, the project directory is docs/ideation/my-project/.

3. Validate — confirm each spec file exists. If any are missing, report which and ask the user whether to continue without them or abort.

4. Detect already-completed phases — run git log --oneline --grep="spec-phase" (or similar) to find commits that reference spec files. For each phase whose spec path appears in a commit message, mark it as already completed and exclude it from execution. Report which phases are being skipped:

   Skipping Phase 1 (already committed: abc1234)
   

Phase 2: Plan Execution Order

From the dependency graph, compute execution waves — groups of phases that can run in parallel because all their blockers are satisfied.

Algorithm:

completed = {already-committed phases from Phase 1, step 6}
waves = []
while uncompleted phases remain:
  ready = phases where all blockedBy are in completed
  waves.append(ready)
  completed = completed ∪ ready

Example:

Dependencies: { 1: [], 2: [1], 3: [1], 4: [3] }

Wave 1: [Phase 1]           — no blockers
Wave 2: [Phase 2, Phase 3]  — both blocked only by Phase 1
Wave 3: [Phase 4]           — blocked by Phase 3

Present the execution plan to the user before starting:

Execution plan for {project-name}:
  Wave 1: Phase 1 ({title})
  Wave 2: Phase 2 ({title}) + Phase 3 ({title})  [parallel]
  Wave 3: Phase 4 ({title})

{N} phases across {M} waves. Parallel phases in waves 2+.
Starting now — I'll pause only if a phase fails review.

Phase 3: Execute Waves

Process waves sequentially. Within each wave, dispatch phases in parallel if the wave has multiple phases.

Single-phase wave

Dispatch one subagent:

Agent({
  description: "Execute Phase {N}: {title}",
  subagent_type: "general-purpose",
  mode: "bypassPermissions",
  prompt: "<instructions>
You are executing Phase {N} of the {project-name} ideation project.

Run the execute-spec skill in headless mode:
/ideation:execute-spec --headless {spec-file-path}

Follow the skill's full workflow: Scout → Build → Verify-Review-Fix → Commit.
The --headless flag auto-proceeds through confirmation steps so execution
does not block.

When complete, report:
- RESULT: PASS or FAIL
- Summary of what was implemented
- Any findings from the review cycle
- The commit hash (if committed)

If the review cycle fails after 3 cycles, report RESULT: FAIL with the
remaining findings. Do not ask the user — the orchestrator handles failure gates.
</instructions>"
})

Multi-phase wave (parallel)

Dispatch all phases in the wave simultaneously using multiple Agent tool calls in a single message. Each subagent gets the same prompt structure above with its own phase number and spec path.

After each wave completes

Parse each subagent's result. Look for RESULT: PASS or RESULT: FAIL in the output.

If all phases PASS: Log completion, move to next wave.

If any phase FAIL:

This is the failure gate. Stop and present the situation:

AskUserQuestion:
  Question: "Phase {N} failed review after 3 cycles. {summary of findings}. How to proceed?"
  Options:
  - "Skip and continue" — Mark phase as failed, continue with remaining waves. Phases that depend on this one will also be skipped.
  - "Retry phase" — Re-dispatch the failed phase with a fresh subagent.
  - "Stop here" — Halt execution. Completed phases are already committed.

If "Skip and continue":

• Mark the phase as failed
• Remove it from completed set for dependency resolution
• Any phase whose blockedBy includes the failed phase is also skipped
• Log which phases were skipped and why

If "Retry phase":

• Re-dispatch the same phase with a new subagent
• If it fails again, re-present the gate (no retry limit, but each retry is explicit)

If "Stop here":

• Report what completed and what remains
• Exit

Progress Reporting

After each wave, print a brief status line:

Wave {M}/{total}: Phase(s) {list} — {PASS/FAIL}
  Completed: {list of all completed phases}
  Remaining: {list of remaining phases}

Phase 4: Completion Report

After all waves complete (or execution stops), present a summary:

## Execution Complete

### Completed Phases
- Phase 1: {title} — {commit hash}
- Phase 2: {title} — {commit hash}
- Phase 3: {title} — {commit hash}

### Skipped Phases
- Phase 4: {title} — blocked by failed Phase 3

### Failed Phases
- Phase 3: {title} — {summary of failure}

### Summary
{M} of {N} phases completed successfully.
{commits committed, files changed across all phases}

If all phases completed successfully:

All {N} phases complete. Run `git log --oneline -{N}` to see the commits.

Key Principles

1. Subagents get clean contexts — each phase runs in a fresh agent with no prior phase's context. This is why we use the Agent tool, not inline execution.
2. The contract is the source of truth — phase order, dependencies, and spec paths all come from the contract's Execution Plan.
3. Gate on failures, not successes — the happy path is fully hands-off. User intervention only when review fails.
4. Parallel when possible — independent phases run simultaneously. The dependency graph determines what's safe to parallelize.
5. Already-committed phases are durable — each phase commits independently. If execution stops at wave 3, waves 1 and 2 are already committed.
6. Don't re-execute completed phases — if a spec's changes are already committed (check git log for the spec name in commit messages), skip it.