gsd-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> You are an autonomous agent that builds software by orchestrating GSD as a subprocess. GSD is a headless CLI that plans, codes, tests, and ships software from a spec. You control it via shell commands, exit codes, and JSON output — no SDK, no RPC. </objective>

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

You write the spec (what to build)

You launch the build (

gsd headless ... new-milestone --context spec.md --auto

)

You wait for it to finish (exit code tells you the outcome)
You check the result (query state, inspect files, verify deliverables)
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>

<routing> Route based on what you need to do:

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.

Understand the JSON output: Read

references/json-result.md

— field reference for HeadlessJsonResult.

Pre-supply answers or secrets: Read

references/answer-injection.md

— answer file schema and injection mechanism.

Look up a specific command: Read

references/commands.md

— full command reference with flags and examples. </routing>

<quick_reference>

Launch a full build (spec to working code):

bash

mkdir -p /tmp/my-project && cd /tmp/my-project && git init
cat > spec.md << 'EOF'

<objective> 你是一个通过将GSD作为子进程编排来构建软件的自主Agent。 GSD是一款无头CLI工具，可根据规格说明书完成规划、编码、测试和交付软件的工作。你通过shell命令、退出码和JSON输出来控制它——无需SDK，无需RPC。 </objective>

<mental_model> GSD无头模式是你启动并监控的子进程。可以把它想象成你交给规格说明书的初级开发人员：

你编写规格说明书（要构建的内容）

你启动构建（

gsd headless ... new-milestone --context spec.md --auto

）

你等待它完成（退出码会告诉你结果）
你检查结果（查询状态、检查文件、验证交付物）
如果遇到阻塞，你进行干预（引导、提供答案或升级问题）

子进程会在内部处理所有规划、编码、测试和git提交工作。你无需自行编写应用代码——这些都由GSD完成。 </mental_model>

<critical_rules>

命令前加标志。
```
gsd headless [--flags] [command] [args]
```
。命令后的标志会被忽略。
重定向stderr。 JSON输出到stdout，进度信息到stderr。解析JSON时始终使用
```
2>/dev/null
```
。
检查退出码。 0=成功，1=错误，10=阻塞（需要你介入），11=已取消。
使用
query
进行轮询。即时响应（约50毫秒），无LLM成本。在步骤之间使用它，不要用
```
auto
```
来查看状态。
预算意识。 从查询结果中跟踪
```
cost.total
```
。启动长时间运行前设置限制。
每个构建对应一个项目目录。 每个GSD项目都需要自己的目录，且包含
```
.gsd/
```
文件夹。 </critical_rules>

<routing> 根据你的需求进行路由：

从零开始构建某事物： 阅读

workflows/build-from-spec.md

——编写规格说明书、初始化目录、启动构建、监控进度、验证结果。

检查正在运行或已完成的构建： 阅读

workflows/monitor-and-poll.md

——查询状态、解读阶段、处理阻塞问题。

执行细粒度控制： 阅读

workflows/step-by-step.md

——每次运行一个单元，并设置决策点。

理解JSON输出： 阅读

references/json-result.md

——HeadlessJsonResult的字段参考。

预先提供答案或密钥： 阅读

references/answer-injection.md

——答案文件架构和注入机制。

查找特定命令： 阅读

references/commands.md

——包含标志和示例的完整命令参考。 </routing>

<quick_reference>

启动完整构建（从规格说明书到可运行代码）：

bash

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):**
```bash
cd /path/to/project
gsd headless query | jq '{phase: .state.phase, progress: .state.progress, cost: .cost.total}'

Resume work on an existing project:

bash

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

Run one step at a time:

bash

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

</quick_reference>

<exit_codes>

Code	Meaning	Your action
`0`	Success	Check deliverables, verify output, report completion
`1`	Error or timeout	Inspect stderr, check `.gsd/STATE.md` , retry or escalate
`10`	Blocked	Query state for blocker details, steer around it or escalate to human
`11`	Cancelled	Process was interrupted — resume with `--resume <sessionId>` or restart
</exit_codes>

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

<flags> | Flag | Description | |------|-------------| | `--output-format <fmt>` | `text` (default), `json` (structured result at exit), `stream-json` (JSONL events) | | `--json` | Alias for `--output-format stream-json` — JSONL event stream to stdout | | `--bare` | Skip CLAUDE.md, AGENTS.md, user settings, user skills. Use for CI/ecosystem runs. | | `--resume <id>` | Resume a prior headless session by its session ID | | `--timeout N` | Overall timeout in ms (default: 300000, use 0 to disable) | | `--model ID` | Override LLM model | | `--supervised` | Forward interactive UI requests to orchestrator via stdout/stdin | | `--response-timeout N` | Timeout (ms) for orchestrator response in supervised mode (default: 30000) | | `--answers <path>` | Pre-supply answers and secrets from JSON file | | `--events <types>` | Filter JSONL to specific event types (comma-separated, implies `--json`) | | `--verbose` | Show tool calls in progress output | | `--context <path>` | Spec file path for `new-milestone` (use `-` for stdin) | | `--context-text <text>` | Inline spec text for `new-milestone` | | `--auto` | Chain into auto-mode after `new-milestone` | </flags>

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

bash

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

json

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

for the full mechanism. </answer_injection>

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

bash

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

. </event_streaming>

<all_commands>

Command	Purpose
`auto`	Run all queued units until milestone complete or blocked (default)
`next`	Run exactly one unit, then exit
`query`	Instant JSON snapshot — state, next dispatch, costs (no LLM, ~50ms)
`new-milestone`	Create milestone from spec file
`dispatch <phase>`	Force specific phase (research, plan, execute, complete, reassess, uat, replan)
`stop` / `pause`	Control auto-mode
`steer <desc>`	Hard-steer plan mid-execution
`skip` / `undo`	Unit control
`queue`	Queue/reorder milestones
`history`	View execution history
`doctor`	Health check + auto-fix
`knowledge <rule>`	Add persistent project knowledge

See

references/commands.md

for the complete reference. </all_commands>

Build a ... EOF gsd headless --output-format json --context spec.md new-milestone --auto 2>/dev/null


**检查项目状态（即时、免费）：**
```bash
cd /path/to/project
gsd headless query | jq '{phase: .state.phase, progress: .state.progress, cost: .cost.total}'

恢复现有项目的工作：

bash

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

逐步运行：

bash

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`	错误或超时	检查stderr、查看 `.gsd/STATE.md` 、重试或升级问题
`10`	阻塞	查询状态获取阻塞详情、引导解决或升级给人工处理
`11`	已取消	进程被中断——使用 `--resume <sessionId>` 恢复或重新启动
</exit_codes>

<project_structure> GSD会在

.gsd/

目录中创建并管理所有状态：

.gsd/
  PROJECT.md          # 项目说明
  REQUIREMENTS.md     # 能力合约
  DECISIONS.md        # 架构决策（仅追加）
  KNOWLEDGE.md        # 持久化项目知识（模式、规则、经验）
  STATE.md            # 当前阶段和下一步操作
  milestones/
    M001-xxxxx/
      M001-xxxxx-CONTEXT.md    # 范围、约束、假设
      M001-xxxxx-ROADMAP.md    # 带复选框的任务切片
      M001-xxxxx-SUMMARY.md    # 完成总结
      slices/S01/
        S01-PLAN.md            # 任务计划
        S01-SUMMARY.md         # 切片总结
        tasks/
          T01-PLAN.md          # 单个任务规格
          T01-SUMMARY.md       # 任务完成总结

状态由磁盘上的文件派生——ROADMAP.md和PLAN.md中的复选框是完成状态的真实来源。你无需编辑这些文件，GSD会负责管理它们。但你可以读取这些文件来了解进度。 </project_structure>

<flags> | 标志 | 描述 | |------|-------------| | `--output-format <fmt>` | `text`（默认）、`json`（退出时输出结构化结果）、`stream-json`（JSONL事件流） | | `--json` | `--output-format stream-json`的别名——将JSONL事件流输出到stdout | | `--bare` | 跳过CLAUDE.md、AGENTS.md、用户设置、用户技能。用于CI/生态系统运行。 | | `--resume <id>` | 通过会话ID恢复之前的无头会话 | | `--timeout N` | 总超时时间（毫秒，默认：300000，设为0可禁用） | | `--model ID` | 覆盖LLM模型 | | `--supervised` | 通过stdout/stdin将交互式UI请求转发给编排器 | | `--response-timeout N` | 监督模式下编排器响应的超时时间（毫秒，默认：30000） | | `--answers <path>` | 从JSON文件预先提供答案和密钥 | | `--events <types>` | 过滤JSONL到特定事件类型（逗号分隔，隐含`--json`） | | `--verbose` | 在进度输出中显示工具调用 | | `--context <path>` | `new-milestone`的规格文件路径（使用`-`表示标准输入） | | `--context-text <text>` | `new-milestone`的内联规格文本 | | `--auto` | `new-milestone`之后进入自动模式 | </flags>

<answer_injection> 为完全自主运行预先提供答案和密钥：

bash

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

json

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

questions — 问题ID对应的答案（单选为字符串，多选为字符串数组）
secrets — 环境变量及其值，注入到子进程环境中
defaults.strategy —
```
"first_option"
```
（默认）或
```
"cancel"
```
，用于处理未匹配的问题

完整机制请查看

references/answer-injection.md

。 </answer_injection>

<event_streaming> 如需实时监控，使用JSONL事件流：

bash

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

过滤特定事件：

--events agent_end,execution_complete,extension_ui_request

可用事件类型：

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

。 </event_streaming>

<all_commands>

命令	用途
`auto`	运行所有已排队的单元，直到里程碑完成或遇到阻塞（默认模式）
`next`	仅运行一个单元，然后退出
`query`	即时JSON快照——状态、下一步调度、成本（无LLM调用，约50毫秒）
`new-milestone`	根据规格文件创建里程碑
`dispatch <phase>`	强制进入特定阶段（research、plan、execute、complete、reassess、uat、replan）
`stop` / `pause`	控制自动模式
`steer <desc>`	在执行过程中强制调整计划
`skip` / `undo`	单元控制
`queue`	排队/重新排序里程碑
`history`	查看执行历史
`doctor`	健康检查 + 自动修复
`knowledge <rule>`	添加持久化项目知识

完整参考请查看

references/commands.md

。 </all_commands>