AGENT SKILL

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

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; auto has no overall timeout unless this flag is set
  • --json — JSONL event stream ending with the authoritative headless_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

open-gsd
open-gsd/gsd-pi

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.

★ 1.4k
open-gsd
open-gsd/gsd-pi

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.

★ 1.4k
open-gsd
open-gsd/gsd-pi

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".

★ 1.4k
open-gsd
open-gsd/gsd-pi

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".

★ 1.4k
open-gsd
open-gsd/gsd-pi

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.

★ 1.4k
open-gsd
open-gsd/gsd-pi

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.

★ 1.4k