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

package/README.md

@@ -1,153 +1,160 @@
-# <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+# {{data: project.name("")}}sdd-forge{{/data}}
 
 [![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. The API, command structure, and configuration format may change without notice. Please avoid using it in production environments.
 
-**ソースコード解析 + 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/`.
+The Spec-Driven Development (SDD) workflow also automates 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 package dependencies.
+- **Automatic source code 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** — Four-layer inheritance (base → arch → preset → project-local) for flexible customization.
+- **SDD workflow** — Manage the development cycle of spec → gate → implementation → forge → review with simple commands.
+- **Multilingual support** — Automatically generate documentation in multiple languages via translate / generate modes.
+- **AI agent integration** — Compatible with Claude Code (skills) and Codex CLI.
+- **Multi-preset** — Supports Node.js CLI / CakePHP2 / Laravel / Symfony.
 
-## クイックスタート
+## Quick Start
 
-### インストール
+### Installation
 
 <pre>
 # npm
-npm install -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+npm install -g {{data: project.name("")}}sdd-forge{{/data}}
 
 # yarn
-yarn global add <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+yarn global add {{data: project.name("")}}sdd-forge{{/data}}
 
 # pnpm
-pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+pnpm add -g {{data: project.name("")}}sdd-forge{{/data}}
 </pre>
 
-### セットアップ & ドキュメント生成
+### Setup & Document Generation
 
 <pre>
-# 1. プロジェクトを登録（インタラクティブウィザード）
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
+# 1. Register your project (interactive wizard)
+{{data: project.name("")}}sdd-forge{{/data}} setup
 
-# 2. ドキュメントを一括生成（scan → init → data → text → readme）
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
+# 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 is all it takes to generate `docs/` and `README.md`.
 
-## コマンド一覧
+## Command Reference
 
-### ドキュメント生成
+### 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 analyzed 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` | Multilingual translation (default language → others) |
+| `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 the 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 flow for adding features or making changes:
 
 ```
-  spec          仕様書を作成（feature ブランチ + spec.md）
+  spec          Create a spec (feature branch + spec.md)
     ↓
-  gate          仕様ゲートチェック（未解決事項がなければ PASS）
+  gate          Spec gate check (PASS when no unresolved items)
     ↓
-  実装          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 a prompt:
 
 ```
-$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) | This chapter provides a high-level view of `sdd-forge`, a Node.js CLI tool that automates documentation generation th… |
+| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | This chapter documents all 17 subcommands available in `sdd-forge`, organized across three dispatcher layers (`docs.j… |
+| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) | This chapter covers the configuration files and customization options available in sdd-forge, including project setti… |
+| [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,90 @@
-# 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）ワークフローに沿って仕様策定から実装・レビューまでを一貫してサポートします。
+This chapter provides a high-level view of `sdd-forge`, a Node.js CLI tool that automates documentation generation through source code analysis and drives feature development via a Spec-Driven Development (SDD) workflow. The tool integrates with externally configured AI agents (such as Claude CLI) to produce and refine project documentation, while relying solely on Node.js built-in modules for all other operations.
 
-## 内容
+## Content
 
-### ツールの目的
+### Architecture Diagram
 
-<!-- {{text: このCLIツールが解決する課題と、ターゲットユーザーを説明してください。}} -->
-
-ソフトウェア開発において「ドキュメントが陳腐化する」「仕様と実装が乖離する」という課題を解決するために作られたツールです。ソースコードを静的解析して docs/ 配下のドキュメントを自動生成・更新することで、常にコードと同期されたドキュメントを維持できます。また、機能追加・改修の際には SDD フローに従って spec（仕様書）を作成し、ゲートチェックをパスしてから実装に進む規律ある開発プロセスを提供します。
-
-主なターゲットユーザーは、レガシーコードベースを抱えるチームや、ドキュメント管理コストを削減したい開発チームです。CakePHP 2.x・Laravel・Symfony・Node.js CLI などのプリセットが用意されており、対象フレームワークにあわせてすぐに利用を開始できます。
-
-### アーキテクチャ概要
-
-<!-- {{text: ツール全体のアーキテクチャを mermaid flowchart で生成してください。入力・処理・出力の流れ、主要モジュールの関係を含めること。出力は mermaid コードブロックのみ。}} -->
+<!-- {{text: Generate a mermaid flowchart showing the project architecture. Include data flows between major components. Output only the mermaid code block.}} -->
 
 ```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
+    User([User / CI]) -->|CLI invocation| Entry[sdd-forge.js\nEntry Point]
+
+    Entry -->|docs subcommands| DocsDispatcher[docs.js\nDispatcher]
+    Entry -->|spec / gate| SpecDispatcher[spec.js\nDispatcher]
+    Entry -->|flow| Flow[flow.js\nSDD Flow Runner]
+    Entry -->|presets| Presets[presets-cmd.js]
+    Entry -->|help| Help[help.js]
+
+    DocsDispatcher --> Scan[scan\nSource Analysis]
+    DocsDispatcher --> Data[data\nDirective Resolver]
+    DocsDispatcher --> Text[text\nAI Text Fill]
+    DocsDispatcher --> Forge[forge\nDocs Refinement]
+    DocsDispatcher --> Review[review\nQuality Check]
+    DocsDispatcher --> Readme[readme\nREADME Generator]
+
+    SpecDispatcher --> SpecInit[spec init\nSpec Creation]
+    SpecDispatcher --> Gate[gate\nGate Check]
+
+    Scan -->|analysis.json\nsummary.json| OutputDir[.sdd-forge/output/]
+    Data -->|reads| OutputDir
+    Text -->|reads| OutputDir
+    Forge -->|reads| OutputDir
+
+    Text -->|prompt| AgentLib[lib/agent.js\nAI Agent Caller]
+    Forge -->|prompt| AgentLib
+    Review -->|prompt| AgentLib
+    AgentLib -->|configured command| ExternalAI([External AI Agent\ne.g. Claude CLI])
+
+    OutputDir -->|resolved directives| DocsDir[docs/\nGenerated Documentation]
 ```
 
-### 主要コンセプト
+### Component Responsibilities
 
-<!-- {{text: このツールを理解するうえで重要なコンセプト・用語を表形式で説明してください。}} -->
+<!-- {{text: Describe the major components with their location, responsibilities, and I/O in table format.}} -->
 
-| コンセプト・用語 | 説明 |
-|---|---|
-| 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` で定義する |
+| Component | Location | Responsibility | Input | Output |
+|---|---|---|---|---|
+| CLI Entry Point | `src/sdd-forge.js` | Parses top-level subcommand and resolves project context via environment variables | CLI arguments, `.sdd-forge/projects.json` | Routes to dispatcher with `SDD_SOURCE_ROOT` / `SDD_WORK_ROOT` set |
+| Docs Dispatcher | `src/docs.js` | Routes docs-related subcommands (`build`, `scan`, `data`, `text`, `forge`, `review`, etc.) | Subcommand string | Delegates to `src/docs/commands/*.js` |
+| Spec Dispatcher | `src/spec.js` | Routes spec-related subcommands (`spec`, `gate`) | Subcommand string | Delegates to `src/specs/commands/*.js` |
+| Scanner | `src/docs/lib/scanner.js` | Traverses source files and extracts structural information (PHP, JS, YAML) | Source root path, scan config | `.sdd-forge/output/analysis.json`, `summary.json` |
+| Directive Parser | `src/docs/lib/directive-parser.js` | Parses `{{data}}`, `{{text}}`, `@block`, and `@extends` directives in Markdown templates | Markdown template files | Parsed directive AST |
+| Data Resolver | `src/docs/lib/resolver-factory.js` | Resolves `{{data}}` directives by binding analysis data to named data sources | Parsed directives, `analysis.json` | Rendered Markdown sections |
+| AI Agent Caller | `src/lib/agent.js` | Executes configured external AI agent commands synchronously or asynchronously | Prompt string, agent config | AI-generated text streamed or returned as string |
+| Config Manager | `src/lib/config.js` | Loads and validates `.sdd-forge/config.json`; manages context and path resolution | `.sdd-forge/` directory | Typed config object, resolved paths |
+| Flow State Manager | `src/lib/flow-state.js` | Persists and retrieves SDD workflow state (current spec, branch, worktree info) | Work root path, state object | `.sdd-forge/current-spec` JSON file |
+| Preset System | `src/lib/presets.js` | Auto-discovers `preset.json` files under `src/presets/` and registers available project types | `src/presets/` directory tree | `PRESETS` constant used across all consumers |
+| SDD Flow Runner | `src/flow.js` | Orchestrates the full SDD cycle (spec → gate → implement → forge → review) automatically | `--request` argument, flow state | Sequential command execution with user interaction |
 
-### 典型的な利用フロー
+### External Integrations
 
-<!-- {{text: ユーザーがインストールしてから最初の成果物を得るまでの典型的な手順をステップ形式で説明してください。}} -->
+<!-- {{text: If there are external system integrations, describe their purpose and connection method in table format.}} -->
 
-**1. インストール**
+| System | Purpose | Connection Method | Configuration |
+|---|---|---|---|
+| AI Agent (e.g. Claude CLI) | Generates and refines documentation text, performs quality review, and evaluates spec gate checks | Spawned as a child process via `child_process.execFileSync` (sync) or `spawn` (async) | Defined in `.sdd-forge/config.json` under `providers` and `defaultAgent`; supports `command`, `args`, `timeoutMs`, and `systemPromptFlag` |
+| Git | Branch creation, worktree isolation, and repository root resolution for SDD workflows | Invoked via `child_process` shell commands (`git rev-parse`, `git worktree`, etc.) | Resolved automatically from the working directory; worktree support detected via `.git` file presence |
 
-```bash
-npm install -g sdd-forge
-```
-
-**2. プロジェクトのセットアップ**
-
-ドキュメント化したいプロジェクトのルートディレクトリで `setup` コマンドを実行します。プロジェクト種別（`type`）・言語（`lang`）・使用する AI エージェントなどの設定が対話形式で生成されます。
-
-```bash
-cd /path/to/your-project
-sdd-forge setup
-```
-
-**3. ソースコード解析**
+`sdd-forge` has no network-based external dependencies. All integrations are process-level and operate entirely within the local development environment.
 
-ソースコードを解析し、`.sdd-forge/output/analysis.json` と `summary.json` を生成します。
+### Environment Differences
 
-```bash
-sdd-forge scan
-```
-
-**4. docs の一括生成**
-
-テンプレート初期化・データ解決・AI によるテキスト生成・README 更新までを一括で実行します。
-
-```bash
-sdd-forge build
-```
+<!-- {{text: Describe the configuration differences across environments (local/staging/production).}} -->
 
-**5. 生成されたドキュメントを確認**
+`sdd-forge` is a local developer CLI tool and does not have traditional deployment environments (staging, production). Configuration is driven entirely by `.sdd-forge/config.json` in each project's working directory.
 
-`docs/` ディレクトリに `01_overview.md` などのドキュメントファイルが生成されています。内容を確認し、MANUAL ブロックに補足情報を追記することで、自動生成と手動記述を組み合わせた知識ベースを構築できます。
+| Aspect | Local Development | CI / Automated Pipeline |
+|---|---|---|
+| Agent invocation | Interactive; supports streaming output callbacks for live feedback | Non-interactive; `callAgentAsync()` with `stdin: "ignore"` to prevent hangs |
+| `CLAUDECODE` env var | May be set if running inside Claude Code | Must be unset before spawning AI agent subprocess (handled automatically by `agent.js`) |
+| Project context | Resolved via `.sdd-forge/projects.json` `default` entry or `--project` flag | Set explicitly via `SDD_SOURCE_ROOT` and `SDD_WORK_ROOT` environment variables |
+| AI agent timeout | Defaults: 120 s / 180 s / 300 s depending on command | Same defaults apply; increase via `config.limits.designTimeoutMs` if needed |
+| Concurrency | Default 5 parallel file processes; tunable via `config.limits.concurrency` | Same; reduce if CPU-constrained in CI runners |
+| Output language | Controlled by `config.output.default` and `config.lang` | Same; no environment-specific overrides exist |