sdd-forge 0.1.0-alpha.2 → 0.1.0-alpha.22

package/README.md

@@ -1,45 +1,153 @@
-# {{PROJECT_NAME}}
+# <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 
-{{PROJECT_DESCRIPTION}}
+[![npm version](https://img.shields.io/npm/v/sdd-forge.svg)](https://www.npmjs.com/package/sdd-forge)
 
-## 技術スタック
+> **Alpha版:** このツールは現在アルファ版です。API・コマンド体系・設定フォーマットは予告なく変更される可能性があります。本番環境での利用はお控えください。
 
-| カテゴリ | 技術 |
-|----------|------|
-| 言語 | Node.js (ES Modules) |
-| 配布 | npm |
-| テスト | — |
+**ソースコード解析 + AI で、プロジェクトドキュメントを自動生成・維持する CLI ツール。**
+
+コードベースを静的解析し、テンプレートと AI を組み合わせて `docs/` を自動生成します。
+さらに Spec-Driven Development（SDD）ワークフローにより、機能追加・修正時のドキュメント更新も自動化します。
+
+## Features
+
+- **ゼロ依存** — Node.js 18+ のみで動作。npm 依存パッケージなし
+- **ソースコード自動解析** — コントローラ・モデル・ルート・設定ファイルを静的解析し、構造データを抽出
+- **AI ドキュメント生成** — テンプレートの `{{text}}` ディレクティブを AI が自動展開
+- **テンプレート継承** — base → arch → preset → project-local の 4 層継承でカスタマイズ可能
+- **SDD ワークフロー** — spec → gate → 実装 → forge → review の開発サイクルをコマンドで管理
+- **AI エージェント連携** — Claude Code（スキル）・Codex CLI に対応
+- **マルチプリセット** — Node.js CLI / CakePHP2 / Laravel / Symfony に対応
 
 ## クイックスタート
 
-```bash
-npm install -g {{PACKAGE_NAME}}
-{{PACKAGE_NAME}} help
+### インストール
+
+<pre>
+# npm
+npm install -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+
+# yarn
+yarn global add <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+
+# pnpm
+pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+</pre>
+
+### セットアップ & ドキュメント生成
+
+<pre>
+# 1. プロジェクトを登録（インタラクティブウィザード）
+<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
+
+# 2. ドキュメントを一括生成（scan → init → data → text → readme）
+<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
+</pre>
+
+これだけで `docs/` と `README.md` が生成されます。
+
+## コマンド一覧
+
+### ドキュメント生成
+
+| コマンド | 説明 |
+|---|---|
+| `setup` | プロジェクト登録 + 設定ファイル生成 |
+| `build` | ドキュメント生成パイプラインを一括実行 |
+| `scan` | ソースコード解析 → `analysis.json` |
+| `init` | テンプレートから `docs/` を初期化 |
+| `data` | `{{data}}` ディレクティブを解析データで解決 |
+| `text` | `{{text}}` ディレクティブを AI で解決 |
+| `readme` | `docs/` から `README.md` を自動生成 |
+| `forge` | AI によるドキュメント反復改善 |
+| `review` | ドキュメント品質チェック |
+
+### SDD ワークフロー
+
+| コマンド | 説明 |
+|---|---|
+| `spec` | 仕様書 + feature ブランチを作成 |
+| `gate` | 仕様書の実装前チェック |
+| `flow` | SDD ワークフローを自動実行 |
+| `changelog` | specs/ から変更履歴を生成 |
+| `agents` | AGENTS.md を更新 |
+
+## SDD ワークフロー
+
+機能追加・修正の流れ:
+
+```
+  spec          仕様書を作成（feature ブランチ + spec.md）
+    ↓
+  gate          仕様ゲートチェック（未解決事項がなければ PASS）
+    ↓
+  実装          gate PASS 後にコーディング
+    ↓
+  forge         ドキュメントを自動更新
+    ↓
+  review        品質チェック（PASS するまで繰り返し）
 ```
 
-## ドキュメント
+### AI エージェントとの連携
 
-| 章 | 概要 |
-|----|------|
-| [01. ツール概要とアーキテクチャ](docs/01_overview.md) | `sdd-forge` は、PHP-MVC プロジェクト（CakePHP 等）における「仕様と実装の乖離」および「技術ドキュメントの作成・維持コスト」という課題を解決するための Node.js CLI ツールである。ソースコード静的解析（`scan`）・テンプレート駆動のドキュメント生成（`init` / `populate` / `tfill`）・仕様ゲート管理（`spec` / `gate`）・反復改善ループ（`forge`）を単一パッケージに統合し、Spec-Driven Development（SDD）ワークフローをコマンドラインから一貫して実行できる。 |
-| [02. CLI コマンドリファレンス](docs/02_cli_commands.md) | `SCRIPTS` オブジェクトから `scan:all` を含めると 19 コマンド（エントリは 18 だが `scan:all` は別処理）が確認できます。正確な数を数えます。 |
-| [03. 設定とカスタマイズ](docs/03_configuration.md) | sdd-forge の動作は `.sdd-forge/config.json` を中心とした複数の JSON 設定ファイルによって制御され、言語・テンプレートタイプ・AIプロバイダー・タイムアウト・テキスト生成挙動など幅広い項目をカスタマイズできる。プロジェクトごとのテンプレート差し替えは `project-overrides.json`、解析結果の表現上書きは `overrides.json` で行い、関心ごとに設定を分離できる構成になっている。 |
-| [04. 内部設計](docs/04_internal_design.md) | `src/bin/sdd-forge.js` がサブコマンドを各モジュール（`analyzers/`・`engine/`・`spec/`・`forge/`・`flow/`）へディスパッチし、共通ユーティリティ `lib/` を底辺として解析→生成→改善の方向で一方向に依存が流れる設計になっている。PHPソースを `analyzers/` が `analysis.json` へ変換し、`engine/populate` と `engine/tfill` がそのデータをテンプレートと組み合わせて `docs/` へ展開するパイプラインが中心的な処理フローである。 |
-| [05. 開発・テスト・配布](docs/05_development.md) | `npm link` を使ったビルド不要のローカル開発環境、外部依存ゼロの Node.js 実装、および `npm version` と `npm publish` による npm レジストリへのリリースフローを中心に構成された章である。テストフレームワークは現時点では導入されておらず、動作確認はコマンド直接実行による手動テストで行う。 |
+#### Claude Code
+
+スキルで SDD ワークフローを実行できます:
+
+```
+/sdd-flow-start   — spec 作成 → gate → 実装を開始
+/sdd-flow-close   — forge → review → commit → merge で終了
+```
 
-## 開発ワークフロー（SDD）
+#### Codex CLI
 
-本プロジェクトは Spec-Driven Development（SDD）を採用しています。
+`$` プロンプトからワークフローを実行できます:
 
 ```
-1. sdd-forge spec --title "..."   — 仕様ファイル作成
-2. sdd-forge gate --spec ...      — 仕様ゲート（未解決事項がなければ PASS）
-3. 実装
-4. sdd-forge forge --prompt "..."  — ドキュメント自動更新
-5. sdd-forge review               — ドキュメントレビュー
+$sdd-flow-start   — spec 作成 → gate → 実装を開始
+$sdd-flow-close   — forge → review → commit → merge で終了
 ```
 
-詳細は [CLAUDE.md](CLAUDE.md) の「SDDフロー」セクションを参照してください。
+## 設定
+
+`sdd-forge setup` で `.sdd-forge/config.json` が生成されます。
+
+```jsonc
+{
+  "type": "cli/node-cli",     // プロジェクトタイプ（プリセット選択）
+  "lang": "ja",               // ドキュメント言語
+  "defaultAgent": "claude",   // AI エージェント
+  "providers": { ... }        // エージェント設定
+}
+```
+
+### カスタマイズ
+
+プロジェクト固有のテンプレートやデータソースを追加できます:
+
+```
+.sdd-forge/
+├── templates/{lang}/
+│   ├── docs/      ← 章テンプレート・README のオーバーライド
+│   └── specs/     ← spec.md / qa.md テンプレート
+└── data/          ← カスタムデータソースモジュール
+```
+
+## ドキュメント
+
+<!-- {{data: docs.chapters("章|概要")}} -->
+| 章 | 概要 |
+| --- | --- |
+| [01. ツール概要とアーキテクチャ](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) | sdd-forge は、ソースコードを解析してプロジェクトドキュメントを自動生成する Node.js CLI ツールです。 |
+| [02. CLI コマンドリファレンス](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | sdd-forge は `help`・`setup`・`build`・`scan`・`data`・`text`・`init`・`forge`・`review`・`changelog`・`agents`・`readme`・`spec`・… |
+| [03. 設定とカスタマイズ](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) | 本章では、sdd-forge が読み込む設定ファイルの構成と各設定項目の意味、AIプロバイダーやドキュメントスタイルといったカスタマイズポイントについて説明します。 |
+| [04. 内部設計](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/04_internal_design.md) | 本章では sdd-forge の内部設計として、ディレクトリ・モジュール構成、モジュール間の依存関係、および代表的なコマンド実行時の処理フローを説明します。 |
+| [05. 開発・テスト・配布](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/05_development.md) | 本章では、ローカル開発環境の構築方法からテストの実行手順、npm レジストリへのリリースまでの一連の開発サイクルを説明します。 |
+<!-- {{/data}} -->
+
+## License
+
+MIT
 
 <!-- MANUAL:START -->
 <!-- MANUAL:END -->

package/docs/01_overview.md

@@ -0,0 +1,110 @@
+# 01. ツール概要とアーキテクチャ
+
+## 説明
+
+<!-- {{text: この章の概要を1〜2文で記述してください。ツールの目的・解決する課題・主要なユースケースを踏まえること。}} -->
+
+sdd-forge は、ソースコードを解析してプロジェクトドキュメントを自動生成する Node.js CLI ツールです。また、機能追加・改修時に Spec-Driven Development（SDD）ワークフローに沿って仕様策定から実装・レビューまでを一貫してサポートします。
+
+## 内容
+
+### ツールの目的
+
+<!-- {{text: このCLIツールが解決する課題と、ターゲットユーザーを説明してください。}} -->
+
+ソフトウェア開発において「ドキュメントが陳腐化する」「仕様と実装が乖離する」という課題を解決するために作られたツールです。ソースコードを静的解析して docs/ 配下のドキュメントを自動生成・更新することで、常にコードと同期されたドキュメントを維持できます。また、機能追加・改修の際には SDD フローに従って spec（仕様書）を作成し、ゲートチェックをパスしてから実装に進む規律ある開発プロセスを提供します。
+
+主なターゲットユーザーは、レガシーコードベースを抱えるチームや、ドキュメント管理コストを削減したい開発チームです。CakePHP 2.x・Laravel・Symfony・Node.js CLI などのプリセットが用意されており、対象フレームワークにあわせてすぐに利用を開始できます。
+
+### アーキテクチャ概要
+
+<!-- {{text: ツール全体のアーキテクチャを mermaid flowchart で生成してください。入力・処理・出力の流れ、主要モジュールの関係を含めること。出力は mermaid コードブロックのみ。}} -->
+
+```mermaid
+flowchart TD
+    CLI["sdd-forge CLI\nsdd-forge.js"]
+
+    CLI --> DOCS["docs.js\nbuild / scan / init / data / text\nreadme / forge / review / changelog / agents / setup"]
+    CLI --> SPEC["spec.js\nspec / gate"]
+    CLI --> FLOW["flow.js\nSDD フロー自動実行"]
+
+    DOCS --> SCANNER["scanner.js\nソースコード解析"]
+    DOCS --> DP["directive-parser.js\n{{data}} / {{text}} 解決"]
+    DOCS --> TM["template-merger.js\nテンプレートマージ"]
+    DOCS --> AGENT["agent.js\nAI エージェント呼び出し"]
+
+    SCANNER --> ANALYSIS[".sdd-forge/output/analysis.json\nsummary.json"]
+    DP --> RESOLVER["resolver-factory.js\nプリセット固有データ解決"]
+    RESOLVER --> ANALYSIS
+
+    AGENT --> AI["外部 AI CLI\n（providers 設定）"]
+    AI --> DOCS_OUT["docs/\n自動生成ドキュメント"]
+
+    SPEC --> GATE["gate.js\nゲートチェック"]
+    SPEC --> SPECINIT["init.js\nspec.md 作成"]
+
+    FLOW --> SPEC
+    FLOW --> DOCS
+    FLOW --> AGENT
+
+    CONFIG[".sdd-forge/config.json\ncontext.json"] --> CLI
+    PRESETS["src/presets/\nFW 別プリセット"] --> RESOLVER
+    PRESETS --> SCANNER
+```
+
+### 主要コンセプト
+
+<!-- {{text: このツールを理解するうえで重要なコンセプト・用語を表形式で説明してください。}} -->
+
+| コンセプト・用語 | 説明 |
+|---|---|
+| SDD（Spec-Driven Development） | 仕様書（spec.md）を先に作成し、ゲートチェックをパスしてから実装に進む開発手法。仕様と実装の乖離を防ぐ |
+| spec | 機能追加・改修ごとに作成される仕様書ファイル（`specs/NNN-xxx/spec.md`）。`sdd-forge spec` コマンドで生成される |
+| gate | spec の品質チェック。未解決事項がある場合は FAIL となり、実装に進めない |
+| docs/ | プロジェクトの設計・構造・ビジネスロジックをまとめた知識ベース。sdd-forge により自動生成・維持される |
+| `{{data}}` ディレクティブ | docs テンプレート内に記述する、ソースコード解析結果を埋め込む指示子 |
+| `{{text}}` ディレクティブ | docs テンプレート内に記述する、AI が説明文を生成する指示子 |
+| MANUAL ブロック | `<!-- MANUAL:START -->〜<!-- MANUAL:END -->` で囲まれた手動記述領域。自動生成では上書きされない |
+| プリセット | フレームワーク別の解析設定・テンプレートセット（`src/presets/` 配下）。`type` 値で指定する |
+| forge | docs を反復改善するコマンド（`sdd-forge forge`）。AI がソース解析結果をもとにドキュメントを更新する |
+| analysis.json / summary.json | `sdd-forge scan` が出力するソースコード解析結果。summary.json は AI 入力用の軽量版 |
+| provider | AI エージェントの設定。使用する CLI コマンド・引数・systemPromptFlag などを `config.json` で定義する |
+
+### 典型的な利用フロー
+
+<!-- {{text: ユーザーがインストールしてから最初の成果物を得るまでの典型的な手順をステップ形式で説明してください。}} -->
+
+**1. インストール**
+
+```bash
+npm install -g sdd-forge
+```
+
+**2. プロジェクトのセットアップ**
+
+ドキュメント化したいプロジェクトのルートディレクトリで `setup` コマンドを実行します。プロジェクト種別（`type`）・言語（`lang`）・使用する AI エージェントなどの設定が対話形式で生成されます。
+
+```bash
+cd /path/to/your-project
+sdd-forge setup
+```
+
+**3. ソースコード解析**
+
+ソースコードを解析し、`.sdd-forge/output/analysis.json` と `summary.json` を生成します。
+
+```bash
+sdd-forge scan
+```
+
+**4. docs の一括生成**
+
+テンプレート初期化・データ解決・AI によるテキスト生成・README 更新までを一括で実行します。
+
+```bash
+sdd-forge build
+```
+
+**5. 生成されたドキュメントを確認**
+
+`docs/` ディレクトリに `01_overview.md` などのドキュメントファイルが生成されています。内容を確認し、MANUAL ブロックに補足情報を追記することで、自動生成と手動記述を組み合わせた知識ベースを構築できます。

package/docs/02_cli_commands.md

@@ -0,0 +1,279 @@
+# 02. CLI コマンドリファレンス
+
+## 説明
+
+<!-- {{text: この章の概要を1〜2文で記述してください。コマンド総数・グローバルオプションの有無・サブコマンド体系を踏まえること。}} -->
+
+sdd-forge は `help`・`setup`・`build`・`scan`・`data`・`text`・`init`・`forge`・`review`・`changelog`・`agents`・`readme`・`spec`・`gate`・`flow`・`upgrade`・`default`・`presets` の 18 コマンドを提供します。全コマンドに共通する `--project` グローバルオプションによりマルチプロジェクト対応を実現し、docs 系・scan 系・spec 系・flow 系の 4 系統にサブコマンドが分類されます。
+
+## 内容
+
+### コマンド一覧
+
+<!-- {{text: 全コマンドの一覧を表形式で記述してください。コマンド名・説明・主なオプションを含めること。}} -->
+
+| コマンド | カテゴリ | 説明 | 主なオプション |
+|---|---|---|---|
+| `help` | — | コマンド一覧を表示 | なし |
+| `setup` | Project | プロジェクト登録と `config.json` 生成ウィザード | `--name`, `--path`, `--type`, `--agent`, `--dry-run` |
+| `upgrade` | Project | プロジェクト設定をアップグレード | なし |
+| `default` | Project | デフォルトプロジェクトを設定 | なし |
+| `build` | Build | scan → init → data → text → readme を一括実行 | なし |
+| `init` | Docs | テンプレートから `docs/` を初期化 | `--force` |
+| `forge` | Docs | プロンプト起点で `docs/` を反復改善 | `--prompt`, `--spec`, `--agent`, `--mode`, `--max-runs`, `--dry-run` |
+| `review` | Docs | `docs/` 章ファイルの品質チェック | なし |
+| `changelog` | Docs | `specs/` から `change_log.md` を生成 | なし |
+| `agents` | Docs | `AGENTS.md` の PROJECT セクションを更新 | `--sdd`, `--project`, `--dry-run` |
+| `readme` | Docs | `README.md` を自動生成 | なし |
+| `scan` | Scan | ソースコードを解析し `analysis.json` を生成 | `--stdout`, `--dry-run` |
+| `data` | Scan | `{{data}}` ディレクティブを解析データで解決 | なし |
+| `text` | Scan | `{{text}}` ディレクティブを AI で解決 | `--agent`, `--dry-run`, `--timeout`, `--id`, `--per-directive` |
+| `spec` | Spec | feature ブランチと `spec.md` を作成 | `--title`, `--base`, `--no-branch`, `--worktree`, `--dry-run` |
+| `gate` | Spec | `spec.md` の未解決項目をチェック | `--spec` |
+| `flow` | Flow | spec 作成 → gate → forge の SDD フローを自動実行 | `--request`, `--spec`, `--agent`, `--forge-mode`, `--max-runs`, `--dry-run` |
+| `presets list` | Info | 利用可能なプリセット一覧を表示 | なし |
+
+### グローバルオプション
+
+<!-- {{text: 全コマンドに共通するグローバルオプションを表形式で記述してください。}} -->
+
+| オプション | 説明 |
+|---|---|
+| `--project <name>` | マルチプロジェクト環境で操作対象プロジェクトを指定します。`projects.json` に登録済みのプロジェクト名を渡すと、対応するソースルートと作業ルートが環境変数 `SDD_SOURCE_ROOT` / `SDD_WORK_ROOT` に自動設定されます。省略時はデフォルトプロジェクトを使用します。`default`・`help`・`setup`・`presets` ではプロジェクトコンテキストの解決がスキップされるため、このオプションは無効です。 |
+| `-h`, `--help` | 各コマンドの使用方法とオプション一覧を表示して終了します。 |
+| `-v`, `--version`, `-V` | sdd-forge のバージョン番号を表示して終了します。 |
+
+### 各コマンドの詳細
+
+<!-- {{text: 各コマンドの使用方法・オプション・実行例を詳しく記述してください。コマンドごとにサブセクションを立てること。}} -->
+
+#### setup
+
+プロジェクトを sdd-forge に登録し、`.sdd-forge/config.json` を生成するインタラクティブウィザードです。全オプションを CLI で指定した場合は非対話モードで動作します。実行後、`AGENTS.md` の生成・注入と `CLAUDE.md` シンボリックリンクの作成、スキル（`sdd-flow-start`・`sdd-flow-close`）のデプロイも行います。
+
+```
+sdd-forge setup [options]
+
+オプション:
+  --name <name>              プロジェクト名
+  --path <path>              ソースコードのパス（デフォルト: カレントディレクトリ）
+  --work-root <path>         ドキュメント出力先ディレクトリ
+  --type <type>              プロジェクト種別（例: webapp/cakephp2, cli/node-cli）
+  --purpose <purpose>        ドキュメント用途（developer-guide | user-guide | api-reference）
+  --tone <tone>              文体（polite | formal | casual）
+  --agent <agent>            デフォルト AI エージェント（claude | codex）
+  --project-context <text>   プロジェクト概要テキスト
+  --lang <lang>              出力言語（カンマ区切り、例: ja,en）
+  --ui-lang <lang>           UI 言語（en | ja）
+  --set-default              デフォルトプロジェクトに設定する
+  --no-default               デフォルトプロジェクトに設定しない
+  --dry-run                  ファイルを書き込まず内容を表示する
+```
+
+```bash
+# インタラクティブモード
+sdd-forge setup
+
+# 非対話モード
+sdd-forge setup --name myapp --path /path/to/src --type webapp/laravel \
+  --purpose developer-guide --tone polite --agent claude --lang ja
+```
+
+#### scan
+
+ソースコードを解析し、`.sdd-forge/output/analysis.json` と `.sdd-forge/output/summary.json` を生成します。`config.json` の `type` フィールドに対応するプリセットの DataSource を読み込み、プリセット固有のスキャンを実行します。
+
+```
+sdd-forge scan [options]
+
+オプション:
+  --stdout    結果を stdout に出力（ファイル書き込みしない）
+  --dry-run   --stdout と同じ（ファイル書き込みしない）
+```
+
+```bash
+sdd-forge scan
+sdd-forge scan --stdout | jq .controllers.summary
+```
+
+#### init
+
+テンプレート継承チェーンを解決し、`docs/` 配下に章ファイル（`NN_*.md`）を生成します。既存ファイルがある場合は `--force` を付与しないと上書きされません。
+
+```
+sdd-forge init [--force]
+```
+
+#### data
+
+`docs/` の章ファイルに含まれる `{{data: ...}}` ディレクティブを `analysis.json` の解析データで解決し、表やリストを自動挿入します。
+
+```
+sdd-forge data
+```
+
+#### text
+
+`docs/` の章ファイルに含まれる `{{text: ...}}` ディレクティブを AI エージェントで解決し、説明文を生成・挿入します。デフォルトはファイル単位バッチモード（1 ファイル = 1 呼び出し）で、`--per-directive` で 1 ディレクティブ = 1 呼び出しに切り替えられます。
+
+```
+sdd-forge text [options]
+
+オプション:
+  --agent <name>       AI エージェント名（必須。config.json の providers キー）
+  --id <id>            指定 ID の {{text}} ディレクティブのみ処理
+  --dry-run            変更内容を表示するだけでファイル書き込みしない
+  --per-directive      1 ディレクティブ = 1 呼び出しモード
+  --timeout <ms>       タイムアウト ms（デフォルト: 180000）
+```
+
+```bash
+sdd-forge text --agent claude
+sdd-forge text --agent claude --dry-run
+sdd-forge text --agent claude --id overview
+```
+
+#### forge
+
+`docs/` の反復改善を実行します。`--prompt` で変更内容を指定し、`--spec` で対応する spec.md を渡すことで SDD フロー内での利用も可能です。`review` が PASS するまで最大 `--max-runs` 回繰り返します。
+
+```
+sdd-forge forge [options]
+
+オプション:
+  --prompt <text>          開始プロンプト（必須）
+  --prompt-file <path>     プロンプトをファイルから読み込む
+  --spec <path>            入力仕様書（spec.md）へのパス
+  --max-runs <n>           反復回数（デフォルト: 3）
+  --review-cmd <cmd>       review コマンド（デフォルト: sdd-forge review）
+  --agent <name>           AI エージェント名
+  --mode <mode>            実行モード（local | assist | agent、デフォルト: local）
+  --dry-run                ファイル書き込み・review・agent 呼び出しをスキップ
+  --auto-update-context    review 成功後に context.json を自動更新
+  -v, --verbose            エージェントログを逐次表示
+```
+
+```bash
+sdd-forge forge --prompt "コントローラー一覧セクションを更新する"
+sdd-forge forge --prompt "API リファレンスを追加" --spec specs/005-api-ref/spec.md --agent claude --mode agent
+```
+
+#### review
+
+`docs/` 配下の章ファイル（`NN_*.md`）の品質チェックを実行します。各ファイルについて行数・H1 見出し・未解決の `{{data}}`/`{{text}}` ディレクティブ・MANUAL ブロックの整合性を検証します。`analysis.json` の鮮度も確認し、古い場合は警告を出します。
+
+```
+sdd-forge review [<docs-dir>]
+```
+
+```bash
+sdd-forge review
+sdd-forge review docs/
+```
+
+#### changelog
+
+`specs/` ディレクトリを走査し、各 `spec.md` のメタ情報から `change_log.md` を生成します。既存ファイルの `MANUAL` ブロックは保持されます。
+
+```
+sdd-forge changelog
+```
+
+#### agents
+
+`AGENTS.md` の `SDD` セクションをテンプレートで差し替え、`PROJECT` セクションを `analysis.json` から生成・AI で精査します。
+
+```
+sdd-forge agents [options]
+
+オプション:
+  --sdd       SDD セクションのみテンプレートで差し替え（AI なし）
+  --project   PROJECT セクションのみ生成・AI 精査
+  --dry-run   ファイルに書き込まず結果を標準出力に表示
+```
+
+#### readme
+
+`docs/` の内容をもとに `README.md` を自動生成します。
+
+```
+sdd-forge readme
+```
+
+#### spec
+
+連番の feature ブランチと `specs/NNN-<slug>/spec.md`・`qa.md` を作成します。worktree 内で実行された場合は自動的に `--no-branch` が適用されます。
+
+```
+sdd-forge spec [options]
+
+オプション:
+  --title <name>    連番の後ろに付与する短い名前（必須）
+  --base <branch>   ブランチ作成元（デフォルト: 現在のブランチ）
+  --no-branch       ブランチを作成せず spec のみ作成する
+  --worktree        git worktree を作成して spec を配置する
+  --dry-run         変更せず結果のみ表示
+  --allow-dirty     ワークツリーが dirty でも続行する
+```
+
+```bash
+sdd-forge spec --title "user-authentication"
+sdd-forge spec --title "export-csv" --no-branch
+```
+
+#### gate
+
+`spec.md` の未解決項目を検出します。TBD・TODO・未チェックタスク・必須セクション不足・ユーザー確認未承認をチェックし、問題があれば一覧を表示して終了コード 1 で終了します。
+
+```
+sdd-forge gate --spec <path>
+```
+
+```bash
+sdd-forge gate --spec specs/005-export-csv/spec.md
+```
+
+#### flow
+
+spec 作成 → gate → forge の SDD フローを自動実行します。gate が FAIL した場合は未解決事項を表示して終了コード 2 で停止し、実装を行いません。
+
+```
+sdd-forge flow [options]
+
+オプション:
+  --request <text>     実装要求（必須）
+  --title <text>       spec 用タイトル（省略時は request 先頭を利用）
+  --spec <path>        既存 spec.md を使う
+  --agent <name>       AI エージェント名
+  --max-runs <n>       forge 反復回数（デフォルト: 5）
+  --forge-mode <mode>  forge モード（local | assist | agent、デフォルト: local）
+  --no-branch          ブランチを作成せず spec のみ作成する
+  --worktree           git worktree を作成して spec を配置する
+  --dry-run            全サブコマンドを dry-run で実行する
+```
+
+```bash
+sdd-forge flow --request "ユーザー一覧画面に CSV エクスポート機能を追加する"
+sdd-forge flow --request "メール通知を実装" --agent claude --forge-mode agent
+```
+
+### 終了コードと出力
+
+<!-- {{text: 終了コードの定義（0=成功 等）と、stdout/stderr の使い分けルールを表形式で記述してください。}} -->
+
+#### 終了コード
+
+| コード | 意味 | 主な発生コマンド |
+|---|---|---|
+| `0` | 正常終了 | すべてのコマンド |
+| `1` | エラー終了（設定不正・ファイル未検出・レビュー FAIL 等） | 全コマンド共通 |
+| `2` | NEEDS_INPUT（gate FAIL または forge が情報不足で停止） | `gate`, `flow`, `forge` |
+
+#### stdout / stderr の使い分け
+
+| ストリーム | 出力内容 |
+|---|---|
+| `stdout` | 通常の進捗ログ・コマンド実行結果・生成されたファイルパス・AI 出力など |
+| `stderr` | エラーメッセージ・不明なコマンド通知（`sdd-forge: unknown command '...'`）・gate FAIL 理由の一覧 |
+
+`review` および `gate` は PASS/FAIL を `stdout` に出力し、エラー詳細（`-` で始まる項目一覧）は `stderr` に出力します。`scan` で `--stdout` を指定した場合、解析結果の JSON は `stdout` に出力されます。

package/docs/03_configuration.md

@@ -0,0 +1,85 @@
+# 03. 設定とカスタマイズ
+
+## 説明
+
+<!-- {{text: この章の概要を1〜2文で記述してください。設定ファイルの種類・設定可能な項目の範囲・カスタマイズポイントを踏まえること。}} -->
+
+本章では、sdd-forge が読み込む設定ファイルの構成と各設定項目の意味、AIプロバイダーやドキュメントスタイルといったカスタマイズポイントについて説明します。設定ファイルはすべてプロジェクトルート直下の `.sdd-forge/` ディレクトリに配置され、プロジェクト種別・出力言語・AI連携など幅広い動作をコントロールできます。
+
+## 内容
+
+### 設定ファイル
+
+<!-- {{text: このツールが読み込む設定ファイルの一覧と、それぞれの配置場所・役割を表形式で記述してください。}} -->
+
+| ファイル | 配置場所 | 役割 |
+|---|---|---|
+| `config.json` | `.sdd-forge/config.json` | プロジェクト全体の設定（種別・言語・AIプロバイダー・フロー動作など） |
+| `context.json` | `.sdd-forge/context.json` | AI に渡すプロジェクトコンテキスト文字列（`projectContext` フィールド） |
+| `projects.json` | `.sdd-forge/projects.json` | マルチプロジェクト登録情報（`--project` フラグで参照） |
+| `current-spec` | `.sdd-forge/current-spec` | 現在作業中の spec ファイルパス（SDD フロー終了時に削除） |
+| `analysis.json` | `.sdd-forge/output/analysis.json` | `sdd-forge scan` が出力するソースコード解析結果（コンパクト JSON） |
+| `summary.json` | `.sdd-forge/output/summary.json` | `analysis.json` の軽量版。AI 入力用に優先使用され、存在しない場合は `analysis.json` にフォールバックします |
+
+### 設定項目リファレンス
+
+<!-- {{text: 設定ファイルの全フィールドを表形式で記述してください。フィールド名・型・デフォルト値・説明を含めること。}} -->
+
+以下は `config.json` の主要フィールド一覧です。
+
+| フィールド | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `type` | `string` | — | プロジェクト種別。プリセットを特定するキーとして使用されます（例: `webapp/cakephp2`, `cli/node-cli`）。エイリアス（短縮形）も使用可能です |
+| `lang` | `string` | `"ja"` | ドキュメント出力言語（`ja` または `en`） |
+| `uiLang` | `string` | `"ja"` | CLI のメッセージ表示言語（`ja` または `en`） |
+| `defaultAgent` | `string` | — | `providers` に定義したエージェント名のうち、デフォルトで使用するもの |
+| `providers` | `object` | — | AI エージェント定義のマップ。各エントリに `command`・`args`・`systemPromptFlag` を指定します |
+| `providers.<name>.command` | `string` | — | AI CLI の実行コマンド |
+| `providers.<name>.args` | `string[]` | `[]` | AI CLI に渡す追加引数 |
+| `providers.<name>.systemPromptFlag` | `string` | — | システムプロンプトを渡すフラグ名（例: `--system-prompt`） |
+| `documentStyle.purpose` | `string` | — | ドキュメントの目的・用途を記述するフィールド |
+| `documentStyle.tone` | `string` | — | ドキュメントのトーン・文体指定 |
+| `documentStyle.customInstruction` | `string` | — | AI 生成時に追加するカスタム指示文 |
+| `flow.merge` | `string` | `"squash"` | SDD フローでのマージ戦略（`squash` / `ff-only` / `merge`） |
+
+### カスタマイズポイント
+
+<!-- {{text: ユーザーがカスタマイズできる項目（プロバイダー・テンプレート・コマンド等）を説明してください。カスタマイズ例を含めること。}} -->
+
+**AIプロバイダーの切り替え**
+
+`config.json` の `providers` に複数のエージェントを定義し、`defaultAgent` で使用するものを指定できます。`sdd-forge text --agent <name>` でコマンド単位に切り替えることも可能です。
+
+```json
+{
+  "defaultAgent": "claude",
+  "providers": {
+    "claude": {
+      "command": "claude",
+      "args": [],
+      "systemPromptFlag": "--system-prompt"
+    }
+  }
+}
+```
+
+**ドキュメントスタイルの調整**
+
+`documentStyle` フィールドを使うと、AI が生成するドキュメントのトーンや目的を統一できます。たとえば利用者向けの操作ガイドであれば `tone` に `"丁寧・です・ます調"` を指定し、`purpose` に `"エンドユーザー向け操作手順"` と記述することで、AI 生成テキスト全体に一貫したスタイルを適用できます。
+
+**テンプレートのカスタマイズ**
+
+`sdd-forge init` が参照するドキュメントテンプレートは `src/templates/` 以下にバンドルされています。プリセットごとのテンプレートを上書きしたい場合は、プロジェクトの `docs/` ディレクトリ内に対応するファイルを配置することで差し替えが可能です。手動で追記・変更したい箇所は必ず `<!-- MANUAL:START -->` 〜 `<!-- MANUAL:END -->` ブロック内に記述してください。ブロック外の内容は `sdd-forge forge` 実行時に上書きされます。
+
+**マージ戦略の変更**
+
+`flow.merge` を変更することで、SDD フロー完了時の git マージ動作を切り替えられます。チームのブランチ運用ポリシーに合わせて `squash`・`ff-only`・`merge` から選択してください。
+
+### 環境変数
+
+<!-- {{text: ツールが参照する環境変数の一覧と用途を表形式で記述してください。}} -->
+
+| 環境変数 | 用途 |
+|---|---|
+| `SDD_SOURCE_ROOT` | 解析対象プロジェクトのソースコードルートディレクトリパス。`--project` フラグ使用時にプロジェクトコンテキストとして伝播されます |
+| `SDD_WORK_ROOT` | sdd-forge の作業ディレクトリパス（`.sdd-forge/` の親）。マルチプロジェクト構成で複数プロジェクトを切り替える際に参照されます |