gsd-autopilot

Autonomous project runner powered by Claude Code SDK. Spawns one agent per phase — the agent drives the full GSD workflow (research → plan → execute → verify) without user intervention.

Install

cd tools/gsd-autopilot
npm install && npm run build
npm link

Usage

# Smart default — detects what to do based on project state
gsd-autopilot

# Full autonomy — no permission prompts, auto-continue between phases
gsd-autopilot --auto

# New project from scratch (discovery → milestone → run all phases)
gsd-autopilot new "CLI tool that converts markdown to HTML"
gsd-autopilot new --auto "CLI tool that converts markdown to HTML"

# Add milestone to existing project (blocked if phases incomplete)
gsd-autopilot milestone [name]

# Resume from where you left off
gsd-autopilot resume

# Run all incomplete phases
gsd-autopilot run [--from N] [--to N]

# Run a single phase
gsd-autopilot phase <N>

# Show project state
gsd-autopilot status

# Work in a different directory
gsd-autopilot --cwd /path/to/project status

--auto Mode

Enables full autonomy:

• bypassPermissions — no tool approval prompts
• Auto-continue between phases (no checkpoints)
• Agent makes all decisions without asking the user
• On failure after retries, auto-skips the phase instead of blocking on stdin

Without --auto, the agent runs in interactive mode: it can ask questions, and checkpoints pause between phases for user confirmation.

How It Works

1. Parses .planning/ROADMAP.md to find incomplete phases
2. For each phase, spawns a Claude Code agent with GSD workflow knowledge
3. The agent calls /gsd:plan-phase, /gsd:execute-phase, /gsd:verify-work on its own
4. Between phases, checkpoints pause for confirmation (or auto-continue in --auto)
5. Persists position to .planning/STATE.md so resume picks up after interruption
6. Error results from agents are caught and retried (up to 2 retries per phase)

The agent inherits the full ~/.claude/ config: all MCP servers, skills, and CLAUDE.md instructions.

Smart Default

Running gsd-autopilot with no arguments auto-detects:

| State | Action | |-------|--------| | No .planning/ directory | new — start discovery conversation | | Incomplete phases exist | resume — continue from last position | | All phases complete | milestone — create next roadmap |

Milestone Guardrail

gsd-autopilot milestone refuses to create a new milestone if phases are still incomplete. Complete or skip remaining phases first.

State Tracking

Autopilot tracks its position in .planning/STATE.md under an autopilot: frontmatter block:

autopilot:
  current_phase: 3
  total_cost_usd: 4.2100
  total_duration_ms: 180000
  phases_completed: 2

This is cleared on clean completion. On crash/interrupt, resume reads this to pick up where it left off with accumulated cost and duration.

Architecture

gsd-autopilot
├── src/index.ts    — CLI entry, arg parsing, command dispatch
├── src/runner.ts   — Claude Code SDK wrapper, streaming output
├── src/loop.ts     — Phase loop with retry, checkpoints, auto-continue
├── src/stages.ts   — Prompt templates (discovery, phase, milestone)
├── src/roadmap.ts  — ROADMAP.md parser (multiple format support)
├── src/state.ts    — STATE.md reader/writer
├── src/ui.ts       — Terminal output, status table, checkpoints
└── src/types.ts    — TypeScript interfaces

Test Results

• Discovery (new --auto): ~$24, 29min, zero user prompts, creates quality roadmaps
• Phase execution: TDD workflow (failing tests first), Go code generated correctly
• Multi-phase auto-continue: Phase 2→3 transition with zero prompts confirmed
• Smart default detection: correctly routes new/resume/milestone
• Milestone guardrail: blocks with clear error when phases incomplete