GSD 2

npm install -g gsd-pi && gsd — ひとつのコマンドで歩き去る、自律型コーディングエージェント。

1 — 概要

GSD 2 とは

GSD 2 は Pi SDK 上に構築された TypeScript CLI。プロンプトフレームワークだった v1 とは根本的に異なる：LLM に「やって」と頼むのではなく、TypeScript からエージェントセッションを直接制御する。コンテキストウィンドウのクリア、ファイルの注入タイミング、Git ブランチ管理、コスト追跡、スタック検知——すべてコードで制御される。

v2.52最新バージョン

20+LLM プロバイダ

19バンドル拡張

Pi SDK基盤

一言で：「ひとつのコマンド。歩き去る。帰ってきたらビルド済みのプロジェクトとクリーンな Git 履歴」。

v1 vs v2

項目	v1 (プロンプトフレームワーク)	v2 (エージェントアプリケーション)
ランタイム	Claude Code スラッシュコマンド	Pi SDK 上のスタンドアロン CLI
コンテキスト管理	LLM が溜まらないことを願う	タスクごとに Fresh セッション、プログラム制御
オートモード	LLM セルフループ	`.gsd/` ファイル駆動のステートマシン
クラッシュ復旧	なし	ロックファイル + セッションフォレンジクス
Git 戦略	LLM が git コマンドを書く	ワークツリー分離、シーケンシャルコミット、スカッシュマージ
コスト追跡	なし	ユニット・スライス・モデル別の token / コスト台帳
スタック検知	なし	再試行 → 診断 → 停止
検証	手動	自動検証コマンド + 自動修正リトライ
スキル発見	なし	研究フェーズ中に自動検出・適用
並列実行	なし	マルチワーカー並列マイルストーンオーケストレーション

2 — オートモード

ループ

オートモードは ディスク上のファイルで駆動するステートマシン。.gsd/STATE.md を読み、次の作業単位を判断し、新しいエージェントセッションを作成し、関連するコンテキストをすべてインライン注入し、LLM に実行させる。完了したら再度ディスク状態を読んで次のユニットをディスパッチする。

Plan → Execute → Complete → Reassess → Next Slice ↓ 全スライス完了 Validate Milestone

Plan — コードベースをスカウト、関連ドキュメントをリサーチ、must-have（検証可能な成果物）付きタスクに分解。
Execute — 各タスクを Fresh コンテキストウィンドウで実行。lint / test を自動実行して失敗したら自動修正リトライ。
Complete — サマリー、UAT スクリプトを書き、ロードマップにチェックを入れ、コミット。
Reassess — 判明した情報をもとにロードマップの見直し。スライスの追加・削除・並び替え。
Validate Milestone — 全スライス完了後のゲート。ロードマップの成功基準と実際の成果を照合してから封印。

主要特性

特性	説明
Fresh セッション	タスク・研究・計画のたびにクリーンな 200k トークンウィンドウ。コンテキスト蓄積による品質劣化なし。
コンテキスト事前ロード	ディスパッチプロンプトにタスクプラン・スライスプラン・先行タスクサマリー・依存関係・ロードマップ・決定レジスタをインライン注入。LLM が最初から方向付け済みで始まる。
Git 分離	`worktree` / `branch` / `none` から選択。デフォルト `none`（現在のブランチで作業）。`worktree` 時はマイルストーンごとに独立したワークツリーを作り、完了時にスカッシュマージ。
クラッシュ復旧	ロックファイルが現在のユニットを追跡。セッションが死んでも次回起動時にサバイバーファイルから完全コンテキストを合成して再開。
スタック検知	スライディングウィンドウで繰り返しパターンを検知。1 度リトライして再失敗したら停止・診断。
タイムアウト監督	ソフト（警告）→ アイドル（停止検知）→ ハード（一時停止）の 3 段階。リカバリーステアリングで LLM に持続的アウトプットを促す。
適応的再計画	各スライス完了後にロードマップを自動アセスメント。新情報で計画を改訂。
並列実行	独立したマイルストーンを複数ワーカーで同時実行。`.gsd/parallel/` にオーケストレーター状態を永続化。

Escape ハッチ: Escape キーで一時停止。会話を保持したままエージェントと対話し、/gsd auto で再開できる。2 ターミナル構成（1: 自動実行、2: /gsd discuss でステアリング）が推奨ワークフロー。

3 — ワーク構造

Milestone → Slice → Task

Milestone

リリース可能なバージョン（4–10 スライス）

ロードマップ、コンテキスト、リサーチを持つ。完了後にスカッシュマージされ、HTML レポートが自動生成される。

Slice

デモ可能な縦断的機能（1–7 タスク）

S01-PLAN.md にタスク分解。完了後に UAT スクリプト生成。ロードマップ上のチェックボックスで追跡。

Task

コンテキストウィンドウ 1 つ分の作業単位（鉄則）

T01-PLAN.md（must-have 付き）と T01-SUMMARY.md（YAML フロントマター + ナラティブ）を持つ。タスクが 1 ウィンドウに収まらなければ 2 タスクに分割。

Git 戦略（worktree モード）

main:
  docs(M001/S04): workflow documentation and examples
  fix(M001/S03): bug fixes and doc corrections
  feat(M001/S02): API endpoints and middleware
  feat(M001/S01): data model and type system

gsd/M001/S01 (マージ後に削除):
  feat(S01/T03): file writer with round-trip fidelity
  feat(S01/T02): markdown parser for plan files
  feat(S01/T01): core types and interfaces

main への 1 スカッシュコミット/マイルストーン。git bisect が機能し、個別マイルストーンのリバートも可能。コミットメッセージはタスクサマリーから自動生成。

4 — コンテキスト管理

.gsd/ アーティファクト

ファイル	役割
`PROJECT.md`	リビングドキュメント — 今プロジェクトが何であるか
`DECISIONS.md`	アーキテクチャ上の意思決定の追記専用レジスタ
`KNOWLEDGE.md`	セッション横断のルール・パターン・学習
`RUNTIME.md`	API エンドポイント・環境変数・サービスなどランタイムコンテキスト
`STATE.md`	クイックグランス用ダッシュボード — 常に最初に読まれる
`M001-ROADMAP.md`	スライスチェックボックス・リスク・依存関係付きマイルストーンプラン
`M001-CONTEXT.md`	ディスカッションフェーズでのユーザー決定
`S01-PLAN.md`	must-have 付きスライスタスク分解
`T01-PLAN.md`	検証基準付き個別タスクプラン
`T01-SUMMARY.md`	実行結果 — YAML フロントマター + ナラティブ
`S01-UAT.md`	スライス成果物から導出される人間テストスクリプト

状態はディスクに生きる： .gsd/ が唯一の真実の源。セッションをまたいでメモリは残らない。これがクラッシュ復旧・マルチターミナルステアリング・セッション再開を可能にする設計上の核心。

5 — コマンド一覧

スラッシュコマンド（gsd セッション内）

コマンド	説明
`/gsd`	ステップモード — 1 ユニットずつ実行、各ステップ後に一時停止
`/gsd auto`	自律モード — リサーチ・計画・実行・コミット・繰り返し
`/gsd quick`	計画オーバーヘッドなしのクイックタスク実行
`/gsd stop`	オートモードをグレースフルに停止
`/gsd steer`	実行中にプランドキュメントをハードステアリング
`/gsd discuss`	アーキテクチャや決定についてディスカッション（オートモード並行可）
`/gsd rethink`	プロジェクトの会話的再編成
`/gsd status`	進捗ダッシュボード
`/gsd queue`	将来のマイルストーンをキュー（オートモード中も安全）
`/gsd prefs`	モデル選択・タイムアウト・予算上限
`/gsd forensics`	オートモード失敗調査用フルアクセスデバッガ
`/gsd doctor`	ランタイムヘルスチェック（ダッシュボード・ビジュアライザ・レポートに表示）
`/gsd keys`	API キー管理 — 一覧・追加・削除・テスト・ローテーション
`/gsd export --html`	現在または完了済みマイルストーンの HTML レポート生成
`/worktree`	Git ワークツリーライフサイクル — 作成・切替・マージ・削除
`/gsd migrate`	v1 `.planning` ディレクトリを `.gsd` 形式にマイグレーション

CLI コマンド（ターミナルから）

コマンド	説明
`gsd`	インタラクティブ TUI セッションを起動
`gsd --web`	ブラウザベース Web UI を起動（`gsd --web`）
`gsd headless [cmd]`	TUI なしで `/gsd` コマンドを実行（CI / cron / スクリプト）
`gsd headless query`	即時 JSON スナップショット — 状態・次のディスパッチ・コスト（LLM 不要）
`gsd config`	セットアップウィザードを再実行（LLM プロバイダ + ツールキー）
`gsd update`	GSD を最新バージョンに更新
`gsd sessions`	保存済みセッションを一覧・再開
`gsd --continue (-c)`	現在のディレクトリの最新セッションを再開

6 — 設定

PREFERENCES.md

グローバル設定は ~/.gsd/PREFERENCES.md、プロジェクト設定は .gsd/PREFERENCES.md。/gsd prefs で管理。

---
version: 1
models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
token_profile: balanced       # budget | balanced | quality
skill_discovery: suggest       # auto | suggest | off
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 50.00
git:
  isolation: none              # none | worktree | branch
verification_commands:
  - npm run lint
  - npm run test
auto_report: true
---

トークン最適化プロファイル

プロファイル	節約	内容
`budget`	40–60%	安価なモデル、研究・再評価フェーズのスキップ、コンテキストインライン最小化
`balanced`	10–20%	デフォルトモデル、スライスリサーチをスキップ、標準コンテキスト
`quality`	0%	全フェーズ、全コンテキスト、フルモデルパワー

複雑度ベースルーティング： タスクを simple / standard / complex に自動分類し、適切なモデルへルーティング。シンプルな Docs タスクは Haiku、複雑なアーキテクチャ作業は Opus。予算に対する消費割合（50% / 75% / 90%）でモデルを段階的にダウングレード。

7 — アーキテクチャ

システム構造

gsd (CLI バイナリ)
  └─ loader.ts          PI_PACKAGE_DIR・GSD 環境変数をセット、cli.ts を動的インポート
      └─ cli.ts         SDK マネージャーを配線、拡張をロード、InteractiveMode を起動
          ├─ headless.ts      ヘッドレスオーケストレータ（RPC 子プロセスをスポーン）
          ├─ onboarding.ts    初回セットアップウィザード
          ├─ wizard.ts        auth.json からの環境変数ハイドレーション
          ├─ app-paths.ts     ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
          ├─ resource-loader.ts  バンドル拡張 + エージェントを ~/.gsd/agent/ に同期
          └─ src/resources/
              ├─ extensions/gsd/    コア GSD 拡張（自律モード・ステート・コマンド…）
              ├─ extensions/...     18 サポート拡張
              ├─ agents/            scout, researcher, worker
              └─ AGENTS.md          エージェントルーティング指示

主要設計決定

決定	理由
状態はディスクに生きる	クラッシュ復旧・マルチターミナルステアリング・セッション再開を可能にする
2 ファイルローダーパターン	`loader.ts` がゼロ SDK インポートで環境変数をセット → `cli.ts` が静的インポートを実行。`PI_PACKAGE_DIR` を SDK コードより先にセットするため。
`pkg/` シムディレクトリ	`PI_PACKAGE_DIR` を `pkg/`（プロジェクトルートでなく）に向け、Pi のテーマ解決と GSD の `src/` の衝突を防ぐ。
常に上書き同期	起動のたびにバンドル拡張・エージェントを `~/.gsd/agent/` に同期。`npm update -g` が即時反映される。
遅延プロバイダロード	LLM プロバイダ SDK を初回使用時にレイジーロード。コールドスタートタイムを大幅短縮。

バンドルエージェント

エージェント	役割
Scout	高速コードベース偵察 — ハンドオフ用の圧縮コンテキストを返す
Researcher	Web リサーチ — 現在の情報を取得・合成
Worker	汎用実行 — 独立したコンテキストウィンドウで作業

8 — はじめる

インストール

# Node.js ≥ 22.0.0 (Node 24 LTS 推奨) が必要
npm install -g gsd-pi@latest

プロバイダにログイン

gsd
/login

20+ プロバイダから選択 — Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot など。Claude Max または Copilot サブスクリプションがあれば OAuth フローで完結。それ以外は API キーを貼り付けるだけ。

2 ターミナル構成（推奨ワークフロー）

# ターミナル 1 — ビルドさせる
gsd
/gsd auto

# ターミナル 2 — 動いている間にステアリング
gsd
/gsd discuss    # アーキテクチャ決定を議論
/gsd status     # 進捗確認
/gsd queue      # 次のマイルストーンをキュー

両ターミナルは同じ .gsd/ ファイルを読み書き。ターミナル 2 での決定は次のフェーズ境界で自動的に取り込まれる — オートモードを止める必要なし。

ヘッドレスモード（CI / スクリプト）

# CI でオートモード実行
gsd headless --timeout 600000

# マイルストーンを作成して end-to-end 実行
gsd headless new-milestone --context spec.md --auto

# 即時 JSON スナップショット（LLM なし、約 50ms）
gsd headless query

参照: GitHub: gsd-build/GSD-2 | ドキュメント gsd.build | npm: gsd-pi