Gsd-2 gsd-orchestrator

<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

Check on a running or completed build: Read

workflows/monitor-and-poll.md

Execute with fine-grained control: Read

workflows/step-by-step.md

Understand the JSON output: Read

references/json-result.md

Pre-supply answers or secrets: Read

references/answer-injection.md

Look up a specific command: Read

references/commands.md

<quick_reference>

Launch a full build (spec to working code):

mkdir -p /tmp/my-project && cd /tmp/my-project && git init
cat > spec.md << 'EOF'
# Your Product Spec Here
Build a ...
EOF
gsd headless --output-format json --context spec.md new-milestone --auto 2>/dev/null

Check project state (instant, free):

cd /path/to/project
gsd headless query | jq '{phase: .state.phase, progress: .state.progress, cost: .cost.total}'

Resume work on an existing project:

cd /path/to/project
gsd headless --output-format json auto 2>/dev/null

Run one step at a time:

RESULT=$(gsd headless --output-format json next 2>/dev/null)
echo "$RESULT" | jq '{status: .status, phase: .phase, cost: .cost.total}'

</quick_reference>

<exit_codes>

0

1

.gsd/STATE.md

10

11

--resume <sessionId>

<project_structure> GSD creates and manages all state in

.gsd/

.gsd/
  PROJECT.md          # What this project is
  REQUIREMENTS.md     # Capability contract
  DECISIONS.md        # Architectural decisions (append-only)
  KNOWLEDGE.md        # Persistent project knowledge (patterns, rules, lessons)
  STATE.md            # Current phase and next action
  milestones/
    M001-xxxxx/
      M001-xxxxx-CONTEXT.md    # Scope, constraints, assumptions
      M001-xxxxx-ROADMAP.md    # Slices with checkboxes
      M001-xxxxx-SUMMARY.md    # Completion summary
      slices/S01/
        S01-PLAN.md            # Tasks
        S01-SUMMARY.md         # Slice summary
        tasks/
          T01-PLAN.md          # Individual task spec
          T01-SUMMARY.md       # Task completion summary

State is derived from files on disk — checkboxes in ROADMAP.md and PLAN.md are the source of truth for completion. You never need to edit these files. GSD manages them. But you can read them to understand progress. </project_structure>

<answer_injection> Pre-supply answers and secrets for fully autonomous runs:

gsd headless --answers answers.json --output-format json auto 2>/dev/null

{
  "questions": { "question_id": "selected_option" },
  "secrets": { "API_KEY": "sk-..." },
  "defaults": { "strategy": "first_option" }
}

• questions — question ID to answer (string for single-select, string[] for multi-select)
• secrets — env var to value, injected into child process environment
• defaults.strategy —

  "first_option"

  (default) or

  "cancel"

  for unmatched questions

See

references/answer-injection.md

<event_streaming> For real-time monitoring, use JSONL event streaming:

gsd headless --json auto 2>/dev/null | while read -r line; do
  TYPE=$(echo "$line" | jq -r '.type')
  case "$TYPE" in
    tool_execution_start) echo "Tool: $(echo "$line" | jq -r '.toolName')" ;;
    extension_ui_request) echo "GSD: $(echo "$line" | jq -r '.message // .title // empty')" ;;
    agent_end) echo "Session ended" ;;
  esac
done

Filter to specific events:

--events agent_end,execution_complete,extension_ui_request

Available types:

agent_start

agent_end

tool_execution_start

tool_execution_end

tool_execution_update

extension_ui_request

message_start

message_end

message_update

turn_start

turn_end

cost_update

execution_complete

<all_commands>

auto

next

query

new-milestone

dispatch <phase>

stop

pause

steer <desc>

skip

undo

queue

history

doctor

knowledge <rule>

See

references/commands.md