gsd-orchestrator

GSD をサブプロセスとしてオーケストレーションし、ソフトウェアを構築する自律型エージェントです。 GSD は、仕様に基づいてソフトウェアの計画、コーディング、テスト、リリースを行うヘッドレス CLI です。 シェルコマンド、終了コード、JSON 出力を介して操作します。SDK や RPC は使用しません。

<mental_model> GSD ヘッドレスは、起動して監視するサブプロセスです。仕様を渡す若手開発者のように考えてください。

1. 仕様を作成します（何を構築するか）
2. ビルドを起動します（gsd headless ... new-milestone --context spec.md --auto）
3. 完了するまで待ちます（終了コードで結果を確認します）
4. 結果を確認します（状態を照会し、ファイルを調べ、成果物を検証します）
5. ブロックされた場合は介入します（進行方向を調整する、回答を提供する、またはエスカレーションする）

サブプロセスは、計画、コーディング、テスト、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 ms）、LLM コストはかかりません。ステップの合間にはこれを使い、状態確認には auto を使わないでください。
• 予算を把握します。 query の結果から cost.total を追跡します。長時間の実行を開始する前に上限を設定してください。
• ビルドごとにプロジェクトディレクトリを用意します。 GSD プロジェクトごとに、.gsd/ フォルダーを含む専用ディレクトリが必要です。 </critical_rules>

必要な作業に応じて、参照先を選んでください。

ゼロから何かを構築する場合： workflows/build-from-spec.md を読みます。仕様の作成、ディレクトリの初期化、起動、監視、検証を行います。

実行中または完了済みのビルドを確認する場合： workflows/monitor-and-poll.md を読みます。状態の照会、フェーズの解釈、ブロッカーへの対処を行います。

細かく制御しながら実行する場合： workflows/step-by-step.md を読みます。判断ポイントを設けながら、一度に 1 単位ずつ実行します。

JSON 出力を理解する場合： references/json-result.md を読みます。HeadlessJsonResult のフィールドリファレンスです。

回答やシークレットを事前に提供する場合： references/answer-injection.md を読みます。回答ファイルのスキーマと注入の仕組みを確認できます。

特定のコマンドを調べる場合： references/commands.md を読みます。フラグや例を含む、コマンドの完全なリファレンスです。

<quick_reference>

フルビルドを起動する（仕様から動作するコードまで）：

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

プロジェクトの状態を確認する（即時、無料）：

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

既存プロジェクトで作業を再開する：

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

一度に 1 ステップずつ実行する：

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          # What this project is
  REQUIREMENTS.md     # Capability contract
  DECISIONS.md        # Architectural decisions (append-only)
  KNOWLEDGE.md        # Persistent project knowledge (manual rules, memory-projected patterns/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

状態はディスク上のファイルから導出されます。完了を示す情報源は、ROADMAP.md と PLAN.md のチェックボックスです。これらのファイルを編集する必要はありません。GSD が管理します。ただし、進捗状況を把握するために読むことはできます。 </project_structure>

フラグ	説明
--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	対話型 UI リクエストを stdout／stdin 経由でオーケストレーターに転送します
--response-timeout N	supervised モードでのオーケストレーター応答のタイムアウト（ミリ秒、デフォルト：30000）
--answers <path>	JSON ファイルから回答とシークレットを事前に指定します
--events <types>	JSONL を指定したイベントタイプに絞り込みます（カンマ区切り、--json を暗黙に指定）
--verbose	進行状況の出力にツール呼び出しを表示します
--context <path>	new-milestone の仕様ファイルパス（標準入力には - を使用）
--context-text <text>	new-milestone の仕様テキストをインラインで指定します
--auto	new-milestone の後に自動モードへ移行します

<answer_injection> 完全自律実行のために回答とシークレットを事前に指定します。

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 — 回答する質問 ID（単一選択の場合は文字列、複数選択の場合は文字列配列）
• secrets — 環境変数から値へのマッピング。子プロセスの環境に注入されます
• defaults.strategy — "first_option"（デフォルト）、または一致する質問がない場合に "cancel"

仕組みの詳細については、references/answer-injection.md を参照してください。 </answer_injection>

<event_streaming> リアルタイムで監視するには、JSONL イベントストリーミングを使用します。

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	ユニットを 1 つだけ実行して終了します
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|pattern|lesson>	永続的なプロジェクトナレッジを追加します

完全なリファレンスについては、references/commands.md を参照してください。 </all_commands>