sdd-forge 0.1.0-alpha.27 → 0.1.0-alpha.28

package/README.md

@@ -1,23 +1,27 @@
 # <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 
+<!-- {{data: docs.langSwitcher("absolute")}} -->
+**English** | [日本語](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/ja/README.md)
+<!-- {{/data}} -->
+
 [![npm version](https://img.shields.io/npm/v/sdd-forge.svg)](https://www.npmjs.com/package/sdd-forge)
 
-> **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.
+> **Alpha:** This tool is currently in alpha. APIs, command structure, and configuration formats may change without notice. Not recommended for production use.
 
 **A CLI tool that automatically generates and maintains project documentation using source code analysis + AI.**
 
-It statically analyzes your codebase and combines templates with AI to auto-generate `docs/`.
+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
 
-- **Zero dependencies** — Runs on Node.js 18+ only. No npm dependencies
-- **Automatic source code analysis** — Statically analyzes controllers, models, routes, and config files to extract structural data
+- **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
-- **Multilingual support** — Auto-generate documentation in multiple languages via translate / generate modes
-- **AI agent integration** — Compatible with Claude Code (skills) and Codex CLI
+- **Template inheritance** — Four-layer inheritance (base → arch → preset → project-local) for full customization
+- **SDD workflow** — Manage the development cycle of spec → gate → implement → forge → review via commands
+- **Multi-language support** — Auto-generate documentation in multiple languages using translate/generate modes
+- **AI agent integration** — Supports Claude Code (skills) and Codex CLI
 - **Multi-preset** — Supports Node.js CLI / CakePHP2 / Laravel / Symfony
 
 ## Quick Start
@@ -41,11 +45,11 @@ pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 # 1. Register your project (interactive wizard)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
 
-# 2. Generate all documentation at once (scan → init → data → text → readme → agents → translate)
+# 2. Generate all documentation (scan → init → data → text → readme → agents → translate)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
 </pre>
 
-This generates `docs/` and `README.md` in one step.
+This will generate `docs/` and `README.md` in one step.
 
 ## Commands
 
@@ -57,12 +61,12 @@ This generates `docs/` and `README.md` in one step.
 | `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 |
+| `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) |
+| `translate` | Translate to other languages (from default language) |
 | `upgrade` | Update preset templates to the latest version |
 
 ### SDD Workflow
@@ -70,8 +74,8 @@ This generates `docs/` and `README.md` in one step.
 | Command | Description |
 |---|---|
 | `spec` | Create a spec document + feature branch |
-| `gate` | Pre-implementation check for the spec |
-| `flow` | Automatically run the SDD workflow |
+| `gate` | Pre-implementation spec check |
+| `flow` | Run the SDD workflow automatically |
 | `changelog` | Generate change history from specs/ |
 | `agents` | Update AGENTS.md |
 
@@ -85,12 +89,12 @@ This generates `docs/` and `README.md` in one step.
 
 ## SDD Workflow
 
-The flow for adding features or making changes:
+Feature development and change flow:
 
 ```
   spec          Create a spec (feature branch + spec.md)
     ↓
-  gate          Spec gate check (PASS if no unresolved items)
+  gate          Spec gate check (PASS when no unresolved issues)
     ↓
   implement     Write code after gate PASS
     ↓
@@ -103,25 +107,25 @@ The flow for adding features or making changes:
 
 #### Claude Code
 
-Run the SDD workflow with skills:
+Run the SDD workflow using skills:
 
 ```
-/sdd-flow-start   — Start: create spec → gate → implement
-/sdd-flow-close   — Finish: 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:
+Run the workflow from prompts:
 
 ```
-$sdd-flow-start   — Start: create spec → gate → implement
-$sdd-flow-close   — Finish: 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` generates `.sdd-forge/config.json`.
+Running `sdd-forge setup` generates `.sdd-forge/config.json`.
 
 ```jsonc
 {
@@ -149,9 +153,9 @@ You can add project-specific templates and data sources:
 <!-- {{data: docs.chapters("Chapter|Overview")}} -->
 | Chapter | Overview |
 | --- | --- |
-| [01. System Overview](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) | This chapter provides a structural overview of sdd-forge, a Node.js CLI tool that automates documentation generation … |
-| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | This chapter covers all 18 subcommands available in `sdd-forge`, organized into documentation generation commands (ro… |
-| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) | This chapter covers all configuration files used by sdd-forge, the full range of options available in `.sdd-forge/con… |
+| [01. System Overview](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) | This chapter describes the overall architecture of sdd-forge — a Node.js CLI tool that automates documentation genera… |
+| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | This chapter covers all 19 subcommands available in `sdd-forge`, organized by their routing layer: documentation comm… |
+| [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}} -->
 

package/docs/01_overview.md

@@ -4,7 +4,9 @@
 
 <!-- {{text: Write a 1-2 sentence overview of this chapter. Include the project's architecture and whether it integrates with external systems.}} -->
 
-This chapter provides a structural overview 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 follows a three-layer command dispatch architecture and integrates with external AI agents (such as Claude CLI) to generate and refine documentation text.
+This chapter provides a high-level view of `sdd-forge`, a Node.js CLI tool built on a three-layer dispatch architecture that automates documentation generation and Spec-Driven Development workflows. The tool integrates with external AI agents (such as Claude CLI) to resolve natural-language directives, and interacts with Git for branch and worktree management during the SDD flow.
+
+<!-- {{/text}} -->
 
 ## Content
 
@@ -14,102 +16,86 @@ This chapter provides a structural overview of sdd-forge, a Node.js CLI tool tha
 
 ```mermaid
 flowchart TD
-    User["User (CLI)"]
-
-    subgraph Entry["Entry Layer"]
-        SDF["sdd-forge.js\n(Entry Point)"]
-    end
-
-    subgraph Dispatch["Dispatcher Layer"]
-        DOCS["docs.js"]
-        SPEC["spec.js"]
-        FLOW["flow.js"]
-        HELP["help.js"]
-    end
-
-    subgraph Commands["Command Layer"]
-        SCAN["scan"]
-        DATA["data"]
-        TEXT["text"]
-        FORGE["forge"]
-        REVIEW["review"]
-        SPEC_INIT["spec init"]
-        GATE["gate"]
-        OTHER["readme / agents / changelog / …"]
-    end
-
-    subgraph Lib["Core Libraries"]
-        AGENT["agent.js\n(AI Agent Caller)"]
-        CONFIG["config.js\n(Config & Paths)"]
-        SCANNER["scanner.js\n(Source Analyzer)"]
-        PARSER["directive-parser.js"]
-    end
-
-    subgraph Storage["File System"]
-        SRC["Source Code\n(project root)"]
-        ANALYSIS[".sdd-forge/output/\nanalysis.json / summary.json"]
-        DOCFILES["docs/*.md\n(generated docs)"]
-        SPECS["specs/NNN-xxx/spec.md"]
-        CFGFILE[".sdd-forge/config.json"]
-    end
-
-    AI["External AI Agent\n(e.g. Claude CLI)"]
-
-    User --> SDF
-    SDF --> DOCS & SPEC & FLOW & HELP
-    DOCS --> SCAN & DATA & TEXT & FORGE & REVIEW & OTHER
-    SPEC --> SPEC_INIT & GATE
-    SCAN --> SCANNER --> SRC
-    SCANNER --> ANALYSIS
-    DATA --> PARSER --> DOCFILES
-    TEXT --> AGENT --> AI
+    CLI["sdd-forge.js\n(CLI Entry Point)"]
+
+    CLI --> DOCS["docs.js\n(Docs Dispatcher)"]
+    CLI --> SPEC["spec.js\n(Spec Dispatcher)"]
+    CLI --> FLOW["flow.js\n(SDD Flow)"]
+    CLI --> HELP["help.js"]
+
+    DOCS --> SCAN["scan\n→ analysis.json"]
+    DOCS --> INIT["init\n(template → docs/)"]
+    DOCS --> DATA["data\n(resolve {{data}} directives)"]
+    DOCS --> TEXT["text\n(resolve {{text}} directives)"]
+    DOCS --> FORGE["forge / review\n(iterative doc improvement)"]
+
+    SPEC --> SPECINIT["spec init\n(spec.md + branch)"]
+    SPEC --> GATE["gate\n(pre/post gate check)"]
+
+    SCAN --> AJ[".sdd-forge/output/\nanalysis.json\nsummary.json"]
+    AJ --> DATA
+    AJ --> TEXT
+
+    TEXT --> AGENT["AI Agent\n(Claude CLI / configurable)"]
     FORGE --> AGENT
-    REVIEW --> AGENT
-    AGENT --> DOCFILES
-    CONFIG --> CFGFILE
-    SPEC_INIT --> SPECS
-    GATE --> SPECS
+
+    DATA --> DOCS2["docs/*.md\n(rendered output)"]
+    TEXT --> DOCS2
+
+    GIT["Git\n(branch / worktree)"]
+    FLOW --> GIT
+    SPECINIT --> GIT
 ```
 
+<!-- {{/text}} -->
+
 ### Component Responsibilities
 
 <!-- {{text: Describe the major components with their location, responsibilities, and I/O in table format.}} -->
 
 | Component | Location | Responsibility | Input | Output |
 |---|---|---|---|---|
-| CLI Entry Point | `src/sdd-forge.js` | Resolves project context; routes subcommands to the appropriate dispatcher | CLI arguments, env vars (`SDD_SOURCE_ROOT`, `SDD_WORK_ROOT`) | Dispatched command execution |
-| Docs Dispatcher | `src/docs.js` | Routes `build`, `scan`, `init`, `data`, `text`, `forge`, `review`, and related subcommands | Subcommand name + flags | Delegates to `docs/commands/*.js` |
-| Spec Dispatcher | `src/spec.js` | Routes `spec` and `gate` subcommands | Subcommand name + flags | Delegates to `specs/commands/*.js` |
-| SDD Flow Runner | `src/flow.js` | Automates the full SDD cycle end-to-end | `--request` prompt string | Orchestrated spec → gate → implement → forge → review sequence |
-| Source Scanner | `src/docs/lib/scanner.js` | Parses project source files; extracts modules, routes, and structure | Source root directory | `.sdd-forge/output/analysis.json`, `summary.json` |
-| Directive Parser | `src/docs/lib/directive-parser.js` | Parses `{{data}}` and `{{text}}` directives in Markdown templates | `.md` template files | Directive AST for resolvers |
-| Data Resolver | `src/docs/lib/resolver-factory.js` | Injects structured analysis data into `{{data}}` directives | `analysis.json`, directive AST | Resolved Markdown sections |
-| AI Agent Caller | `src/lib/agent.js` | Invokes external AI agent processes synchronously or asynchronously | Prompt string, agent config | AI-generated text (stdout) |
-| Config Manager | `src/lib/config.js` | Loads and validates `.sdd-forge/config.json`; resolves standard paths | `.sdd-forge/` directory | Typed config object, file paths |
-| Spec Gate | `src/specs/commands/gate.js` | Validates a spec against pre/post implementation checklists | `spec.md` path, `--phase` flag | PASS / FAIL report |
-| Forge Engine | `src/docs/commands/forge.js` | Iteratively improves `docs/` by prompting the AI agent | Change summary prompt, `spec.md` path | Updated `docs/*.md` files |
+| CLI Entry Point | `src/sdd-forge.js` | Parses top-level subcommands, resolves project context via env vars, routes to dispatchers | CLI args, `.sdd-forge/projects.json` | Dispatched command execution |
+| Docs Dispatcher | `src/docs.js` | Routes docs-related subcommands (`build`, `scan`, `init`, `data`, `text`, `forge`, `review`, etc.) | Subcommand + flags | Delegates to `docs/commands/*.js` |
+| Spec Dispatcher | `src/spec.js` | Routes spec-related subcommands (`spec`, `gate`) | Subcommand + flags | Delegates to `specs/commands/*.js` |
+| SDD Flow | `src/flow.js` | Automates the full SDD workflow (spec → gate → implement → forge → review) | `--request` string | Orchestrated workflow execution |
+| Scanner | `src/docs/lib/scanner.js` | Crawls source files, parses PHP/JS/YAML, extracts module structure | Source root path, preset scan config | `analysis.json`, `summary.json` |
+| Directive Parser | `src/docs/lib/directive-parser.js` | Parses `{{data}}`, `{{text}}`, `@block`, `@extends` directives from Markdown files | Markdown file content | Parsed directive AST |
+| Resolver Factory | `src/docs/lib/resolver-factory.js` | Creates data resolvers per preset for resolving `{{data}}` directives | `analysis.json`, preset type | Resolved Markdown tables/values |
+| AI Agent Caller | `src/lib/agent.js` | Calls external AI agents synchronously or asynchronously with prompt injection | Prompt string, agent config | AI-generated text |
+| Config Loader | `src/lib/config.js` | Reads and validates `.sdd-forge/config.json`, manages context and path utilities | `.sdd-forge/` directory | Validated config object, resolved paths |
+| Preset System | `src/presets/` | Provides architecture- and framework-specific scan rules and doc templates | Preset key or type string | Scan config, template files, DataSource classes |
+| Flow State Manager | `src/lib/flow-state.js` | Persists and retrieves SDD flow progress (branch, spec path, worktree info) | `.sdd-forge/current-spec` JSON | Flow state object |
+
+<!-- {{/text}} -->
 
 ### External Integrations
 
 <!-- {{text: If there are external system integrations, describe their purpose and connection method in table format.}} -->
 
-| System | Purpose | Connection Method | Configuration |
+| External System | Purpose | Connection Method | Configuration |
 |---|---|---|---|
-| AI Agent (e.g. Claude CLI) | Generates and refines documentation text for `{{text}}` directives; drives `forge`, `review`, `agents`, and `text` commands | Spawned as a child process via `execFileSync` (sync) or `spawn` (async streaming) in `src/lib/agent.js` | Defined under `providers` in `.sdd-forge/config.json`; selected by `defaultAgent` key |
+| AI Agent (e.g., Claude CLI) | Resolves `{{text}}` directives and iteratively improves docs via `forge` and `review` commands | Spawned as a child process via `execFileSync` (sync) or `spawn` (async) with `stdin: "ignore"` | Defined under `providers` in `.sdd-forge/config.json`; selected via `defaultAgent` |
+| Git | Creates feature branches and worktrees during the SDD flow; used for branch strategy selection | Invoked via `child_process` (`execFileSync`) | Automatic; branch strategy chosen interactively during `sdd-forge spec` or `sdd-forge flow` |
+| npm Registry | Distributes the `sdd-forge` package to end users | `npm publish` CLI (manual, operator-initiated only) | `package.json` `files` field controls published artifacts |
 
-The AI agent is the only external integration. All other operations — file scanning, directive parsing, template merging, spec management — rely exclusively on Node.js built-in modules (`fs`, `path`, `child_process`, `os`). The agent command, arguments, timeout, and system-prompt delivery method (`--system-prompt` or `--system-prompt-file`) are all configurable per project.
+<!-- {{/text}} -->
 
 ### Environment Differences
 
 <!-- {{text: Describe the configuration differences across environments (local/staging/production).}} -->
 
-As a local CLI tool, sdd-forge does not have distinct deployment environments in the traditional sense. Configuration differences are instead expressed through per-project `.sdd-forge/config.json` settings and environment variables.
+`sdd-forge` is a developer CLI tool and does not have traditional application deployment environments (local/staging/production). Instead, configuration differences arise from how the tool is installed and how each project's `.sdd-forge/config.json` is set up.
 
-| Aspect | Local Development | CI / Automated Pipeline | Multi-Project Setup |
-|---|---|---|---|
-| Project resolution | Interactive; `--project` flag or `.sdd-forge/projects.json` `default` key | `SDD_SOURCE_ROOT` and `SDD_WORK_ROOT` env vars set explicitly per job | `.sdd-forge/projects.json` registers named projects; `--project <name>` selects the target |
-| AI agent | Configured via `providers` + `defaultAgent` in `config.json`; runs interactively | Same config; `stdin: "ignore"` prevents CLI hang in non-TTY environments (`callAgentAsync`) | Each project carries its own `config.json` with independent agent settings |
-| Language / output | `lang` and `output.languages` control CLI language and doc output locale | Same config values apply; no separate override mechanism | Per-project `config.json` allows different languages per project |
-| Concurrency | `limits.concurrency` (default: 5) controls parallel file processing | Can be raised for faster execution on high-core machines | Independently tunable per project |
-| Timeouts | `limits.designTimeoutMs` / per-provider `timeoutMs` | Should be increased for slow CI agents; default constants: 120 s / 180 s / 300 s | Configurable per project |
-```
+| Aspect | Development (source checkout) | Published Package (npm install) |
+|---|---|---|
+| Binary entry | `node src/sdd-forge.js` or `npm link` | `sdd-forge` via PATH (npm global or npx) |
+| Package version | `0.1.0-alpha.x` (alpha tag on npm) | `latest` tag after explicit `npm dist-tag` promotion |
+| `PKG_DIR` resolution | Points to local `src/` directory | Points to installed package `src/` directory |
+| Test execution | `npm run test` against local `tests/` | Not applicable (tests are not published) |
+| AI agent config | Defined per-project in `.sdd-forge/config.json` | Same — no environment-level override |
+| Concurrency / timeout | Configurable via `limits.concurrency` and `limits.designTimeoutMs` in `config.json` | Same |
+
+Projects analyzed by `sdd-forge` may themselves have environment-specific concerns, but the tool treats the source directory uniformly regardless of the target project's deployment environment.
+
+<!-- {{/text}} -->