Your Product Spec Here

<mental_model> GSD headless is a subprocess you launch and monitor. Think of it like a junior developer you hand a spec to:

1. You write the spec (what to build)
2. You launch the build (gsd headless ... new-milestone --context spec.md --auto)
3. You wait for it to finish (exit code tells you the outcome)
4. You check the result (query state, inspect files, verify deliverables)
5. If blocked, you intervene (steer, supply answers, or escalate)

The subprocess handles all planning, coding, testing, and git commits internally. You never write application code yourself — GSD does that. </mental_model>

<critical_rules>

• Flags before command. gsd headless [--flags] [command] [args]. Flags after the command are ignored.
• Redirect stderr. JSON output goes to stdout. Progress goes to stderr. Always 2>/dev/null when parsing JSON.
• Check exit codes. 0=success, 1=error, 10=blocked (needs you), 11=cancelled.
• Use query to poll. Instant (~50ms), no LLM cost. Use it between steps, not auto for status.
• Budget awareness. Track cost.total from query results. Set limits before launching long runs.
• One project directory per build. Each GSD project needs its own directory with a .gsd/ folder. </critical_rules>

Build something from scratch: Read workflows/build-from-spec.md — write spec, init directory, launch, monitor, verify.

Check on a running or completed build: Read workflows/monitor-and-poll.md — query state, interpret phases, handle blockers.

Execute with fine-grained control: Read workflows/step-by-step.md — run one unit at a time with decision points.