docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions

View File

@@ -1,26 +1,36 @@
# GSD CLI ツールリファレンス
> `gsd-tools.cjs` のプログラマティック API リファレンスです。ワークフローやエージェントが内部的に使用します。ユーザー向けコマンドについては、[コマンドリファレンス](COMMANDS.md) を参照してください。
> `gsd-tools` CLI(`get-shit-done/bin/gsd-tools.cjs`)のリファレンスです。スラッシュコマンドとユーザーフローについては [コマンドリファレンス](COMMANDS.md) を参照してください。[docs インデックス](README.md) に戻る。
---
## 概要
`gsd-tools.cjs` は、GSD の約50個のコマンド、ワークフロー、エージェントファイル全体で繰り返し使われるインライン bash パターンを置き換える Node.js CLI ユーティリティです。設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を一元化しています。
`gsd-tools.cjs` は、設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を GSD コマンド・ワークフロー・エージェント全体で一元化します。
**配置場所:** `get-shit-done/bin/gsd-tools.cjs`
**モジュール:** `get-shit-done/bin/lib/` 内の15個のドメインモジュール
**使い方:**
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **配置パス** | `get-shit-done/bin/gsd-tools.cjs` |
| **実装** | `get-shit-done/bin/lib/` 配下の 20 個のドメインモジュール(ディレクトリが正式) |
| **ステータス** | オーケストレーション・ワークフロー・自動化処理のための主要ランタイムコマンドサーフェス。 |
**使い方(CJS):**
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**グローバルフラグ:**
| フラグ | 説明 |
|--------|------|
| `--raw` | 機械可読な出力(JSON またはプレーンテキスト、フォーマットなし) |
| `--cwd <path>` | 作業ディレクトリの上書き(サンドボックス化されたサブエージェント向け) |
**グローバルフラグ(CJS):**
| フラグ | 説明 |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw` | 機械可読な出力(JSON またはプレーンテキスト、フォーマットなし) |
| `--cwd <path>` | 作業ディレクトリの上書き(サンドボックス化されたサブエージェント向け) |
| `--ws <name>` | `.planning/workstreams/<name>` パス用のワークストリームコンテキスト |
---
@@ -64,6 +74,13 @@ node gsd-tools.cjs state resolve-blocker --text "..."
# セッション継続性を記録
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# フェーズ開始 — 新しいフェーズの STATE.md Status/Last activity を更新
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# エージェント検出可能なブロッカーシグナル送信(discuss-phase / UI フローで使用)
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
```
### State スナップショット
@@ -152,7 +169,9 @@ node gsd-tools.cjs config-set-model-profile <profile>
```bash
# 現在のプロファイルに基づいてエージェント用モデルを取得
node gsd-tools.cjs resolve-model <agent-name>
# 戻り値: opus | sonnet | haiku | inherit
# --raw 出力では選択されたモデル ID/ティアを返します。
# JSON 出力ではプロファイルも含み、アクティブなランタイムがサポートしている場合は
# reasoning_effort も含まれます。
```
エージェント名: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
@@ -198,8 +217,17 @@ node gsd-tools.cjs validate consistency
# .planning/ の整合性チェック、任意で修復
node gsd-tools.cjs validate health [--repair]
# ステータスライン / フック呼び出し元向けのコンテキストウィンドウ使用率をプローブ(v1.40.0)
node gsd-tools.cjs validate context
# 型付き JSON サーフェスとしてのコンテキスト使用率(#455)
node gsd-tools.cjs validate context --json
```
`validate context` は `utilization`、`status`(60% / 70% の閾値で `ok` / `warn` / `critical`)、および `suggestion` 文字列を含む構造化エンベロープを出力します。同じデータが `/gsd-health --context` を支えます。
型付き IR を直接受け取るには `--json` を渡してください(スクリプトやテストアサーションで有用)。
---
## Template コマンド
@@ -275,9 +303,13 @@ node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
# ワークストリームスコープ付き init(`--ws` フラグ)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
```
**大容量ペイロードの処理:** 出力が約50KBを超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます:
**大容量ペイロードの処理:** 出力が約 50KB を超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
@@ -299,6 +331,38 @@ node gsd-tools.cjs requirements mark-complete <ids>
---
## エージェントスキル
指定されたエージェントタイプのスキルブロックを出力します。
```bash
# 生の XML スキルブロックを出力(デフォルト — シェル展開に安全)
node gsd-tools.cjs agent-skills <agent-type>
# 型付き JSON サーフェス(#455)を出力 — { agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --json
```
`--json` フラグは構造化消費やテストアサーションに適した型付き IR オブジェクトを返します。デフォルト(フラグなし)はワークフローのシェル展開が依存する生の XML 出力を維持します。
---
## スキルマニフェスト
コマンド読み込みを高速化するためのスキル検出の事前計算とキャッシュ。
```bash
# スキルマニフェストを生成(.claude/skill-manifest.json に書き込む)
node gsd-tools.cjs skill-manifest
# カスタム出力パスで生成
node gsd-tools.cjs skill-manifest --output <path>
```
利用可能なすべての GSD スキルとそのメタデータ(名前、説明、ファイルパス、引数ヒント)の JSON マッピングを返します。インストーラとセッション開始フックが繰り返しのファイルシステムスキャンを避けるために使用します。
---
## ユーティリティコマンド
```bash
@@ -324,35 +388,70 @@ node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
# プロジェクト統計
node gsd-tools.cjs stats [json|table]
# 進捗表示
# 進捗表示(人間が読める形式)
node gsd-tools.cjs progress [json|table|bar]
# 型付き JSON サーフェスとしての進捗(#455)
node gsd-tools.cjs progress --json
# TODO を完了にする
node gsd-tools.cjs todo complete <filename>
# UAT 監査 — 全フェーズの未解決項目をスキャン
node gsd-tools.cjs audit-uat
# クロスアーティファクト監査キュー — `.planning/` の未解決監査項目をスキャン
node gsd-tools.cjs audit-open [--json]
# GSD-2 プロジェクトを現在の構造にリバースマイグレーション(`/gsd-import --from-gsd2` のバックエンド)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# 設定チェック付き git コミット
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> **`--no-verify`**: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントが使用し、ビルドロックの競合(例: Rust プロジェクトでの cargo ロック競合)を回避します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。
> `--no-verify`: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントがビルドロックの競合(例: Rust プロジェクトでの cargo ロック競合)を避けるために使用します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。
> `--files <paths>` **ステージング動作**: デフォルトでは、`--files` はコミット前に各指定ファイルに対して `git add -- <path>` を実行します。これにより `git add -p` で設定したハンク単位のステージングが上書きされます。`git add` ステップをスキップして指定パス内のステージング済みファイルのみをコミットするには `--respect-staged` を渡してください。そのスコープ内でステージングされたファイルがない場合、コマンドはエラーなしで `{ committed: false, reason: 'nothing staged' }` を返します。コミット時の末尾 `-- <paths>` パス指定は両モードで適用されるため、`--files` スコープ外でステージングされたファイルは決して含まれません(#3061 不変条件)。
```bash
# Web 検索(Brave API キーが必要)
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
## Graphify
`.planning/graphs/` 内のプロジェクトナレッジグラフをビルド、クエリ、検査します。`config.json` で `graphify.enabled: true` が必要です([設定リファレンス](CONFIGURATION.md#graphify-settings) を参照)。
```bash
# ナレッジグラフをビルドまたは再ビルド
node gsd-tools.cjs graphify build
# グラフで用語を検索
node gsd-tools.cjs graphify query <term>
# グラフの鮮度と統計を表示
node gsd-tools.cjs graphify status
# 前回のビルドからの変更を表示
node gsd-tools.cjs graphify diff
# 現在のグラフの名前付きスナップショットを書き込む
node gsd-tools.cjs graphify snapshot [name]
```
ユーザー向けエントリーポイント: `/gsd-graphify`([コマンドリファレンス](COMMANDS.md#gsd-graphify) を参照)。
---
## モジュールアーキテクチャ
| モジュール | ファイル | エクスポート |
|------------|----------|--------------|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 共通ユーティリティ |
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`、共通ユーティリティ、互換性再エクスポート |
| State | `lib/state.cjs` | すべての `state` サブコマンド、`state-snapshot` |
| Phase | `lib/phase.cjs` | フェーズ CRUD、`find-phase`、`phase-plan-index`、`phases list` |
| Planning Workspace | `lib/planning-workspace.cjs` | プランニングシーム: `planningDir`、`planningPaths`、アクティブワークストリームルーティング、`.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | ロードマップ解析、フェーズ抽出、進捗更新 |
| Config | `lib/config.cjs` | 設定の読み書き、セクション初期化 |
| Verify | `lib/verify.cjs` | すべての検証・バリデーションコマンド |
@@ -365,3 +464,36 @@ node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
| UAT | `lib/uat.cjs` | 全フェーズ横断 UAT/検証監査 |
| Profile Output | `lib/profile-output.cjs` | 開発者プロファイルのフォーマット |
| Profile Pipeline | `lib/profile-pipeline.cjs` | セッション分析パイプライン |
| Graphify | `lib/graphify.cjs` | ナレッジグラフのビルド/クエリ/ステータス/差分/スナップショット(`/gsd-graphify` のバックエンド) |
| Learnings | `lib/learnings.cjs` | フェーズ/SUMMARY アーティファクトからの学習抽出(`/gsd-extract-learnings` のバックエンド) |
| Audit | `lib/audit.cjs` | フェーズ/マイルストーン監査キューハンドラ; `audit-open` ヘルパー |
| GSD2 Import | `lib/gsd2-import.cjs` | GSD-2 プロジェクトからのリバースマイグレーションインポーター(`/gsd-import --from-gsd2` のバックエンド) |
| Intel | `lib/intel.cjs` | クエリ可能なコードベースインテリジェンスインデックス(`/gsd-map-codebase --query` のバックエンド) |
---
## レビュアー CLI ルーティング
`review.models.<cli>` はレビュアーフレーバーをコードレビューワークフローが呼び出すシェルコマンドにマッピングします。[`/gsd-config --integrations`](COMMANDS.md#gsd-config) または直接設定できます:
```bash
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-tools.cjs config-set review.models.claude "" # クリア — セッションモデルにフォールバック
```
スラッグは `[a-zA-Z0-9_-]+` に対してバリデーションされます。空またはパスを含むスラッグは拒否されます。完全なフィールドリファレンスは [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) を参照してください。
## シークレット処理
`/gsd-settings` で設定された API キー(`brave_search`、`firecrawl`、`exa_search`)は `.planning/config.json` に平文で書き込まれますが、`config-set` / `config-get` のすべての出力、確認テーブル、インタラクティブプロンプトでは(`****<last-4>` として)マスクされます。マスキングの実装は `get-shit-done/bin/lib/secrets.cjs` を参照してください。`config.json` ファイル自体がセキュリティ境界です — ファイルシステムのパーミッションで保護し、git には含めないようにしてください(`.planning/` はデフォルトで gitignore されます)。
---
## Related
- [Commands](COMMANDS.md)
- [Configuration](CONFIGURATION.md)
- [Architecture](ARCHITECTURE.md)
- [docs index](README.md)