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

package/README.md

@@ -2,26 +2,27 @@
 
 [![npm version](https://img.shields.io/npm/v/sdd-forge.svg)](https://www.npmjs.com/package/sdd-forge)
 
-> **Alpha版:** このツールは現在アルファ版です。API・コマンド体系・設定フォーマットは予告なく変更される可能性があります。本番環境での利用はお控えください。
+> **Alpha:** This tool is currently in alpha. APIs, command structures, and configuration formats may change without notice. Not recommended for production use.
 
-**ソースコード解析 + AI で、プロジェクトドキュメントを自動生成・維持する CLI ツール。**
+**A CLI tool that automatically generates and maintains project documentation using source code analysis + AI.**
 
-コードベースを静的解析し、テンプレートと AI を組み合わせて `docs/` を自動生成します。
-さらに Spec-Driven Development（SDD）ワークフローにより、機能追加・修正時のドキュメント更新も自動化します。
+Statically analyzes your codebase and combines templates with AI to auto-generate `docs/`.
+Spec-Driven Development (SDD) workflows further automate documentation updates when adding features or making changes.
 
 ## 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 に対応
+- **Zero dependencies** — Runs on Node.js 18+ only. No npm packages required
+- **Automatic source analysis** — Statically analyzes controllers, models, routes, and config files to extract structural data
+- **AI document generation** — AI automatically expands `{{text}}` directives in templates
+- **Template inheritance** — Customizable via 4-layer inheritance: base → arch → preset → project-local
+- **SDD workflow** — Manage the spec → gate → implement → forge → review cycle with commands
+- **Multi-language support** — Auto-generate documentation in multiple languages via translate / generate modes
+- **AI agent integration** — Supports Claude Code (skills) and Codex CLI
+- **Multi-preset** — Supports Node.js CLI / CakePHP2 / Laravel / Symfony
 
-## クイックスタート
+## Quick Start
 
-### インストール
+### Installation
 
 <pre>
 # npm
@@ -34,120 +35,126 @@ yarn global add <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 </pre>
 
-### セットアップ & ドキュメント生成
+### Setup & Document Generation
 
 <pre>
-# 1. プロジェクトを登録（インタラクティブウィザード）
+# 1. Register your project (interactive wizard)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
 
-# 2. ドキュメントを一括生成（scan → init → data → text → readme）
+# 2. Generate all documentation at once (scan → init → data → text → readme → agents → translate)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
 </pre>
 
-これだけで `docs/` と `README.md` が生成されます。
+This alone generates `docs/` and `README.md`.
 
-## コマンド一覧
+## Commands
 
-### ドキュメント生成
+### Document Generation
 
-| コマンド | 説明 |
+| Command | Description |
 |---|---|
-| `setup` | プロジェクト登録 + 設定ファイル生成 |
-| `build` | ドキュメント生成パイプラインを一括実行 |
-| `scan` | ソースコード解析 → `analysis.json` |
-| `init` | テンプレートから `docs/` を初期化 |
-| `data` | `{{data}}` ディレクティブを解析データで解決 |
-| `text` | `{{text}}` ディレクティブを AI で解決 |
-| `readme` | `docs/` から `README.md` を自動生成 |
-| `forge` | AI によるドキュメント反復改善 |
-| `review` | ドキュメント品質チェック |
-
-### SDD ワークフロー
-
-| コマンド | 説明 |
+| `setup` | Register project + generate config file |
+| `build` | Run the full document generation pipeline |
+| `scan` | Analyze source code → `analysis.json` |
+| `init` | Initialize `docs/` from templates |
+| `data` | Resolve `{{data}}` directives with analysis data |
+| `text` | Resolve `{{text}}` directives with AI |
+| `readme` | Auto-generate `README.md` from `docs/` |
+| `forge` | Iteratively improve documentation with AI |
+| `review` | Check documentation quality |
+| `translate` | Multi-language translation (default language → other languages) |
+| `upgrade` | Update preset templates to the latest version |
+
+### SDD Workflow
+
+| Command | Description |
 |---|---|
-| `spec` | 仕様書 + feature ブランチを作成 |
-| `gate` | 仕様書の実装前チェック |
-| `flow` | SDD ワークフローを自動実行 |
-| `changelog` | specs/ から変更履歴を生成 |
-| `agents` | AGENTS.md を更新 |
+| `spec` | Create a spec document + feature branch |
+| `gate` | Pre-implementation check for spec |
+| `flow` | Automatically run the SDD workflow |
+| `changelog` | Generate change history from specs/ |
+| `agents` | Update AGENTS.md |
 
-## SDD ワークフロー
+### Project Management
 
-機能追加・修正の流れ:
+| Command | Description |
+|---|---|
+| `default` | Set the default project |
+| `presets` | List available presets |
+| `help` | Show command list |
+
+## SDD Workflow
+
+The feature addition / change flow:
 
 ```
-  spec          仕様書を作成（feature ブランチ + spec.md）
+  spec          Create a spec (feature branch + spec.md)
     ↓
-  gate          仕様ゲートチェック（未解決事項がなければ PASS）
+  gate          Spec gate check (PASS when no open issues)
     ↓
-  実装          gate PASS 後にコーディング
+  implement     Write code after gate PASS
     ↓
-  forge         ドキュメントを自動更新
+  forge         Auto-update documentation
     ↓
-  review        品質チェック（PASS するまで繰り返し）
+  review        Quality check (repeat until PASS)
 ```
 
-### AI エージェントとの連携
+### AI Agent Integration
 
 #### Claude Code
 
-スキルで SDD ワークフローを実行できます:
+Run the SDD workflow with skills:
 
 ```
-/sdd-flow-start   — spec 作成 → gate → 実装を開始
-/sdd-flow-close   — forge → review → commit → merge で終了
+/sdd-flow-start   — Start spec creation → gate → implementation
+/sdd-flow-close   — Finish with forge → review → commit → merge
 ```
 
 #### Codex CLI
 
-`$` プロンプトからワークフローを実行できます:
+Run the workflow from prompts:
 
 ```
-$sdd-flow-start   — spec 作成 → gate → 実装を開始
-$sdd-flow-close   — forge → review → commit → merge で終了
+$sdd-flow-start   — Start spec creation → gate → implementation
+$sdd-flow-close   — Finish with forge → review → commit → merge
 ```
 
-## 設定
+## Configuration
 
-`sdd-forge setup` で `.sdd-forge/config.json` が生成されます。
+Running `sdd-forge setup` generates `.sdd-forge/config.json`.
 
 ```jsonc
 {
-  "type": "cli/node-cli",     // プロジェクトタイプ（プリセット選択）
-  "lang": "ja",               // ドキュメント言語
-  "defaultAgent": "claude",   // AI エージェント
-  "providers": { ... }        // エージェント設定
+  "type": "cli/node-cli",     // Project type (preset selection)
+  "lang": "en",               // Documentation language
+  "defaultAgent": "claude",   // AI agent
+  "providers": { ... }        // Agent configuration
 }
 ```
 
-### カスタマイズ
+### Customization
 
-プロジェクト固有のテンプレートやデータソースを追加できます:
+You can add project-specific templates and data sources:
 
 ```
 .sdd-forge/
 ├── templates/{lang}/
-│   ├── docs/      ← 章テンプレート・README のオーバーライド
-│   └── specs/     ← spec.md / qa.md テンプレート
-└── data/          ← カスタムデータソースモジュール
+│   ├── docs/      ← Chapter templates / README overrides
+│   └── specs/     ← spec.md / qa.md templates
+└── data/          ← Custom data source modules
 ```
 
-## ドキュメント
+## Documentation
 
-<!-- {{data: docs.chapters("章|概要")}} -->
-| 章 | 概要 |
+<!-- {{data: docs.chapters("Chapter|Overview")}} -->
+| Chapter | Overview |
 | --- | --- |
-| [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 レジストリへのリリースまでの一連の開発サイクルを説明します。 |
+| [01. System Overview](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) |  |
+| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) |  |
+| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) |  |
+| [04. Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/04_internal_design.md) |  |
 <!-- {{/data}} -->
 
 ## License
 
 MIT
-
-<!-- MANUAL:START -->
-<!-- MANUAL:END -->

package/docs/01_overview.md

@@ -1,110 +1,23 @@
-# 01. ツール概要とアーキテクチャ
+# 01. System Overview
 
-## 説明
+## Description
 
-<!-- {{text: この章の概要を1〜2文で記述してください。ツールの目的・解決する課題・主要なユースケースを踏まえること。}} -->
+<!-- {{text: Write a 1-2 sentence overview of this chapter. Include the project's architecture and whether it integrates with external systems.}} -->
 
-sdd-forge は、ソースコードを解析してプロジェクトドキュメントを自動生成する Node.js CLI ツールです。また、機能追加・改修時に Spec-Driven Development（SDD）ワークフローに沿って仕様策定から実装・レビューまでを一貫してサポートします。
+## Content
 
-## 内容
+### Architecture Diagram
 
-### ツールの目的
+<!-- {{text: Generate a mermaid flowchart showing the project architecture. Include data flows between major components. Output only the mermaid code block.}} -->
 
-<!-- {{text: このCLIツールが解決する課題と、ターゲットユーザーを説明してください。}} -->
+### Component Responsibilities
 
-ソフトウェア開発において「ドキュメントが陳腐化する」「仕様と実装が乖離する」という課題を解決するために作られたツールです。ソースコードを静的解析して docs/ 配下のドキュメントを自動生成・更新することで、常にコードと同期されたドキュメントを維持できます。また、機能追加・改修の際には SDD フローに従って spec（仕様書）を作成し、ゲートチェックをパスしてから実装に進む規律ある開発プロセスを提供します。
+<!-- {{text: Describe the major components with their location, responsibilities, and I/O in table format.}} -->
 
-主なターゲットユーザーは、レガシーコードベースを抱えるチームや、ドキュメント管理コストを削減したい開発チームです。CakePHP 2.x・Laravel・Symfony・Node.js CLI などのプリセットが用意されており、対象フレームワークにあわせてすぐに利用を開始できます。
+### External Integrations
 
-### アーキテクチャ概要
+<!-- {{text: If there are external system integrations, describe their purpose and connection method in table format.}} -->
 
-<!-- {{text: ツール全体のアーキテクチャを mermaid flowchart で生成してください。入力・処理・出力の流れ、主要モジュールの関係を含めること。出力は mermaid コードブロックのみ。}} -->
+### Environment Differences
 
-```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 ブロックに補足情報を追記することで、自動生成と手動記述を組み合わせた知識ベースを構築できます。
+<!-- {{text: Describe the configuration differences across environments (local/staging/production).}} -->

package/docs/02_cli_commands.md

@@ -1,279 +1,23 @@
-# 02. CLI コマンドリファレンス
+# 02. CLI Command Reference
 
-## 説明
+## Description
 
-<!-- {{text: この章の概要を1〜2文で記述してください。コマンド総数・グローバルオプションの有無・サブコマンド体系を踏まえること。}} -->
+<!-- {{text: Write a 1–2 sentence overview of this chapter. Cover the total number of commands, whether global options exist, and the subcommand structure.}} -->
 
-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 系統にサブコマンドが分類されます。
+## Contents
 
-## 内容
+### Command List
 
-### コマンド一覧
+<!-- {{text: List all commands in a table, including command name, description, and main options. Commands can be identified from the modules list in the analysis data. Include both commands routed through dispatchers (docs.js, spec.js) and directly executed commands (flow, presets). Note that build is a composite command (scan → init → data → text → readme → agents → translate pipeline). Be sure to include translate (multi-language translation), upgrade (template update), and default (default project configuration).}} -->
 
-<!-- {{text: 全コマンドの一覧を表形式で記述してください。コマンド名・説明・主なオプションを含めること。}} -->
+### Global Options
 
-| コマンド | カテゴリ | 説明 | 主なオプション |
-|---|---|---|---|
-| `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: Describe the global options common to all commands in a table. Include --project, --help/-h, and --version/-v/-V. Also note that setup, default, help, and presets skip project context resolution.}} -->
 
-### グローバルオプション
+### Command Details
 
-<!-- {{text: 全コマンドに共通するグローバルオプションを表形式で記述してください。}} -->
+<!-- {{text: Describe the usage, options, and examples for each command in detail. Create a #### subsection for each command. For the build pipeline, list all steps: scan → init → data → text → readme → agents → translate. The translate command has --lang, --force, and --dry-run options.}} -->
 
-| オプション | 説明 |
-|---|---|
-| `--project <name>` | マルチプロジェクト環境で操作対象プロジェクトを指定します。`projects.json` に登録済みのプロジェクト名を渡すと、対応するソースルートと作業ルートが環境変数 `SDD_SOURCE_ROOT` / `SDD_WORK_ROOT` に自動設定されます。省略時はデフォルトプロジェクトを使用します。`default`・`help`・`setup`・`presets` ではプロジェクトコンテキストの解決がスキップされるため、このオプションは無効です。 |
-| `-h`, `--help` | 各コマンドの使用方法とオプション一覧を表示して終了します。 |
-| `-v`, `--version`, `-V` | sdd-forge のバージョン番号を表示して終了します。 |
+### Exit Codes and Output
 
-### 各コマンドの詳細
-
-<!-- {{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` に出力されます。
+<!-- {{text: Describe exit code definitions (0=success, 1=general error, etc.) and the rules for stdout/stderr usage in a table. Include the point that gate and review PASS/FAIL results are printed to stdout.}} -->