gsd-headless
Orchestrate GSD (Git Ship Done) projects programmatically via headless CLI. Use when an agent needs to create milestones from specs, execute dev workflows, monitor progress, check status, or control execution (pause/stop/skip/steer). Triggers on "run gsd", "create milestone", "execute project", "check gsd status", "orchestrate development", "run headless workflow", or building orchestrators that coordinate multiple GSD workers.
- License 许可
- MIT
- 所属仓库
- open-gsd/gsd-pi
- 最近更新
- 2026-11-15
- Stars
- ★ 1.4k
- Forks
- 118
01 前言 Front Matter
- name
- gsd-headless
- description
- Orchestrate GSD (Git Ship Done) projects programmatically via headless CLI. Use when an agent needs to create milestones from specs, execute dev workflows, monitor progress, check status, or control execution (pause/stop/skip/steer). Triggers on "run gsd", "create milestone", "execute project", "check gsd status", "orchestrate development", "run headless workflow", or building orchestrators that coordinate multiple GSD workers.
02 资源文件 3
- 参考文档references/answer-injection.md2.8 KB
- 参考文档references/commands.md6.2 KB
- 参考文档references/multi-session.md4.9 KB
03 SKILL.md 正文
GSD Headless Orchestration
Run GSD commands without TUI via gsd headless. Spawns an RPC child process, auto-responds to UI prompts, streams progress.
Command Syntax
gsd headless [flags] [command] [args...]
Flags:
--timeout N— overall timeout in ms;autohas no overall timeout unless this flag is set--json— JSONL event stream ending with the authoritativeheadless_result--model ID— override LLM model--thinking LEVEL— override thinking level (off,minimal,low,medium,high,xhigh,max)--resume <id>— resume a prior headless session by ID--bare— start with minimal context for CI/ecosystem use--verbose— show tool calls in progress output--supervised— forward interactive UI requests to orchestrator via stdout/stdin--response-timeout N— timeout for orchestrator response in supervised mode (default 30000)--max-restarts N— auto-restart on crash with backoff (default 3, 0 to disable)--answers <path>— pre-supply answers and secrets from JSON file--events <types>— filter JSONL output to specific event types (comma-separated, implies--json)
Exit codes: 0=complete, 1=error/timeout, 10=blocked, 11=cancelled
Core Workflows
1. Create + Execute a Milestone (end-to-end)
gsd headless new-milestone --context spec.md --auto
Reads spec, bootstraps .gsd/, creates milestone, then chains into auto-mode executing all phases (discuss → research → plan → execute → summarize → complete).
Extra flags for new-milestone: --context <path> (use - for stdin), --context-text <text>, --auto.
2. Run All Queued Work
gsd headless auto
Default command. Loops through all pending units until milestone complete or blocked.
3. Run One Unit
gsd headless next
Execute exactly one unit (task/slice/milestone step), then exit. Ideal for step-by-step orchestration with external decision logic between steps.
4. Instant State Snapshot (no LLM)
gsd headless query
Returns a single JSON object with the full project snapshot — no LLM session, instant (~50ms). This is the recommended way for orchestrators to inspect state.
{
"state": { "phase": "executing", "activeMilestone": {...}, "activeSlice": {...}, "progress": {...}, "registry": [...] },
"next": { "action": "dispatch", "unitType": "execute-task", "unitId": "M001/S01/T01" },
"cost": { "workers": [{ "milestoneId": "M001", "cost": 1.50, ... }], "total": 1.50 }
}
# What phase is the project in?
gsd headless query | jq '.state.phase'
# What would auto-mode do next?
gsd headless query | jq '.next'
# Total spend across parallel workers
gsd headless query | jq '.cost.total'
5. Dispatch Specific Phase
gsd headless dispatch research|plan|execute|complete|reassess|uat|replan
Force-route to a specific phase, bypassing normal state-machine routing.
Orchestrator Patterns
Poll-and-React Loop
# Instant state check — no LLM cost
PHASE=$(gsd headless query | jq -r '.state.phase')
NEXT_ACTION=$(gsd headless query | jq -r '.next.action')
case "$PHASE" in
complete) echo "Done" ;;
blocked) echo "Needs intervention" ;;
*) [ "$NEXT_ACTION" = "dispatch" ] && gsd headless next ;;
esac
Step-by-Step with Monitoring
while true; do
gsd headless next
EXIT=$?
[ $EXIT -ne 0 ] && break
# Instant progress check between steps
gsd headless query | jq '{phase: .state.phase, progress: .state.progress}'
done
Multi-Session Orchestration
GSD tracks concurrent workers via status files in .gsd/parallel/. See references/multi-session.md for the full architecture.
Quick overview:
Each worker spawns with GSD_MILESTONE_LOCK=M00X + its own git worktree. Workers write heartbeats to .gsd/parallel/<milestoneId>.status.json. The orchestrator enumerates all status files to get a dashboard of all workers.
# Spawn a worker for milestone M001 in its worktree
GSD_MILESTONE_LOCK=M001 GSD_PARALLEL_WORKER=1 \
gsd headless --json auto \
--cwd .gsd/worktrees/M001 2>worker-M001.log &
M001_PID=$!
# Monitor all workers: read .gsd/parallel/*.status.json
for f in .gsd/parallel/*.status.json; do
jq '{mid: .milestoneId, state: .state, unit: .currentUnit.id, cost: .cost}' "$f"
done
# Stop the M001 worker
kill -TERM "$M001_PID"
Status file fields: milestoneId, pid, state (running/paused/stopped/error), currentUnit, completedUnits, cost, lastHeartbeat, startedAt, worktreePath.
Worker commands: pause, resume and stop are command_queue rows in the project database. The coordinator writes them (/gsd parallel pause|resume|stop). An external orchestrator stops a worker with SIGTERM. A signal file .gsd/parallel/<milestoneId>.signal.json is still accepted for compatibility and is deprecated: the worker turns it into a command_queue row and removes the file.
Liveness detection: PID alive check (kill -0 $pid) + heartbeat freshness (30s timeout). Stale sessions are auto-cleaned.
For multiple projects: each project has its own .gsd/ directory. The orchestrator must track (projectPath, milestoneId) tuples externally.
JSONL Event Stream
Use --json to get real-time events on stdout for downstream processing:
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
Event types: agent_start, agent_end, tool_execution_start, tool_execution_end, extension_ui_request, message_update, error.
Filtered Event Stream
Use --events to receive only specific event types — reduces noise for orchestrators:
# Only phase-relevant events
gsd headless --events agent_end,extension_ui_request auto 2>/dev/null
# Only tool execution events
gsd headless --events tool_execution_start,tool_execution_end auto
The filter applies only to stdout output. Internal processing (completion detection, supervised mode, answer injection) is unaffected — all events are still processed internally.
Available event 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.
Answer Injection
Pre-supply answers and secrets for headless runs via --answers:
gsd headless --answers answers.json auto
Answer file schema:
{
"questions": { "question_id": "selected_option" },
"secrets": { "API_KEY": "sk-..." },
"defaults": { "strategy": "first_option" }
}
- questions — question ID → answer (string or string[])
- secrets — env var → value, injected into child process env
- defaults.strategy —
"first_option"(default) or"cancel"for unmatched
See references/answer-injection.md for full details.
GSD Project Structure
All state lives in .gsd/ as markdown files (version-controllable):
.gsd/
phases/01-foundation/
01-CONTEXT.md # Requirements, scope, decisions
01-ROADMAP.md # Slices with tasks, dependencies, checkboxes
01-SUMMARY.md # Completion summary
01-01-PLAN.md # First slice task list
01-01-SUMMARY.md # First slice summary with frontmatter
Runtime state is stored in the project-root database; markdown files are reviewable projections written under .gsd/phases/. Legacy projects may still resolve to .gsd/milestones/<MID>/ until migrated.
All Headless Commands
Quick reference — see references/commands.md for the complete list.
| Command | Purpose |
|---|---|
auto |
Run all queued units (default) |
next |
Run one unit |
query |
Instant JSON snapshot — state, next dispatch, costs (no LLM) |
new-milestone |
Create milestone from spec |
queue |
Queue/reorder milestones |
history |
View execution history |
stop / pause |
Control auto-mode |
dispatch <phase> |
Force specific phase |
skip / undo |
Unit control |
doctor |
Health check + auto-fix |
steer <desc> |
Hard-steer plan mid-execution |
explore / spike / sketch |
Prompt-driven ideation and experiment workflows |
map-codebase / docs-update / graphify |
Codebase documentation and knowledge workflows |
code-review / review / audit-* / verify-work |
Review, audit, and UAT workflows |
04 同仓库更多 Skills
write-milestone-brief
Synthesize the current conversation into a milestone brief (PRD). Saves it as the milestone CONTEXT (`gsd_summary_save`) by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.
write-docs
Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.
web-quality-audit
Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
verify-before-complete
Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
userinterface-wiki
UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.