sdd-forge 0.1.0-alpha.31 → 0.1.0-alpha.32

package/README.md

@@ -5,172 +5,121 @@
 <!-- {{/data}} -->
 
 [![npm version](https://img.shields.io/npm/v/sdd-forge.svg)](https://www.npmjs.com/package/sdd-forge)
+[![license](https://img.shields.io/npm/l/sdd-forge.svg)](https://opensource.org/licenses/MIT)
+[![downloads](https://img.shields.io/npm/dm/sdd-forge.svg)](https://www.npmjs.com/package/sdd-forge)
 
-> **Alpha:** This tool is currently in alpha. APIs, command structure, and configuration formats may change without notice. Not recommended for production use.
+> **Alpha:** APIs, command structure, and configuration formats may change without notice.
 
-**A CLI tool that generates documentation from programmatic source code analysis — based on facts, not AI guesswork.**
+## Spec-Driven Development — Design, implement, and document in a single flow
 
-Mechanical gate checks and structured templates guarantee the reproducibility and accuracy that AI alone cannot deliver.
-The Spec-Driven Development (SDD) workflow keeps your documentation in sync as features are added or changed.
+A spec-first development flow manager designed to work with AI coding agents.
 
-## Why sdd-forge?
+## The SDD Flow
 
-Most AI documentation tools let AI "read" your code and write docs.
-sdd-forge is different.
+Every feature goes through three phases, from spec to merge.
 
-- **Programmatic analysis** — A static analyzer parses controllers, models, routes, and configs instead of asking AI to read them. No hallucinations, no missed files
-- **Facts vs. generation** — `{{data}}` directives inject facts extracted mechanically from source code. `{{text}}` directives hold AI-generated explanations. What is trustworthy and what is inferred is structurally clear
-- **Mechanical gate checks** — Spec completeness is verified by program logic, not AI judgment. A quality gate you can rely on
-- **Structural stability** — Directives define what goes where. AI cannot rearrange paragraphs or alter the document structure
-
-## Features
-
-### Analyze
-
-`scan` statically analyzes source code and produces `analysis.json`. A program — not AI — reads the structure.
-
-- Parses controllers, models, routes, and config files to extract structural data
-- `enrich` lets AI survey the whole picture and annotate each entry with role, summary, and chapter classification
-- Preset system adapts to various frameworks and project structures
+```
+plan ─────── Specification
+│  ├─ draft      Refine requirements through dialogue
+│  ├─ spec       Create spec (feature branch + spec.md)
+│  ├─ gate       Spec validation + guardrail check
+│  └─ test       Review test plan → write test code
+│
+implement ── Implementation
+│  ├─ code       Write code after gate PASS
+│  └─ review     AI code review
+│
+merge ────── Wrap-up
+   ├─ docs       Auto-update documentation
+   ├─ commit     Commit changes
+   └─ merge      Merge to base branch → cleanup
+```
 
-### Generate
+### AI stays in its lane
 
-`{{data}}` injects facts, `{{text}}` injects AI explanations, both into templates. A single `build` command produces `docs/` and `README.md`.
+Source code analysis, spec gate checks, and flow orchestration are all handled by deterministic commands. AI is not in charge of the flow — it assists with spec drafting, code review, and prose generation within well-defined boundaries.
 
-- Template inheritance — 4-layer override: base → arch → preset → project-local
-- Multi-language — translate / generate modes for automatic localization
-- Zero dependencies — runs on Node.js 18+ only, no npm packages required
+- **Spec gate** — Programmatic validation of unresolved items and missing approvals. No PASS, no implementation
+- **Guardrails** — Project-specific design principles checked against each spec
+- **Compaction resilience** — Flow state and requirements are persisted, so you can resume after context compression
 
-### Enforce
+## Automatic Doc Sync
 
-`gate` mechanically validates specs, `review` checks document quality. The SDD workflow keeps documentation fresh.
+Source code is statically analyzed to extract file structure, classes, methods, configuration, and dependencies. The extracted data is injected into templates to produce structured documentation (`docs/`) and `README.md`.
 
-- gate — detects unresolved items and missing approvals programmatically. Implementation blocked until PASS
-- review — AI checks alignment between docs and source code
-- AI agent integration — Claude Code (skills) and Codex CLI supported
+Documentation is automatically refreshed during the merge phase, so docs and code never drift apart. With always-current docs, both humans and AI agents can understand the system without reading every source file.
 
 ## Quick Start
 
-### Installation
+### Install
 
 <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>
 
-### Setup & Generate
+### Setup
 
 <pre>
-# 1. Register your project (interactive wizard)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
-
-# 2. Generate all documentation (scan → enrich → init → data → text → readme → agents → translate)
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
 </pre>
 
-That's it — `docs/` and `README.md` are generated.
+An interactive wizard configures your project type (preset) and AI agent.
 
-## Commands
+### Generate docs for an existing project
 
-### Documentation Generation
+If you already have source code, generate documentation to get a complete picture of the system. Especially useful for onboarding onto legacy codebases.
 
-| Command | Description |
-|---|---|
-| `setup` | Register project + generate config |
-| `build` | Run the full documentation 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` | Generate `README.md` from `docs/` |
-| `forge` | Iteratively improve docs with AI |
-| `review` | Check document quality |
-| `translate` | Translate docs (default language → others) |
-| `upgrade` | Update preset templates to latest version |
-
-### SDD Workflow
+<pre>
+<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> docs build
+</pre>
 
-| Command | Description |
-|---|---|
-| `spec` | Create spec + feature branch |
-| `gate` | Pre-implementation spec check |
-| `flow` | Run the SDD workflow automatically |
-| `changelog` | Generate change log from specs/ |
-| `agents` | Update AGENTS.md |
+### Develop with the SDD flow
 
-### Other
+**[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — run each phase via skills:
 
-| Command | Description |
+| Skill | Phase |
 |---|---|
-| `presets` | List available presets |
-| `help` | Show command list |
-
-## SDD Workflow
+| `/sdd-forge.flow-plan` | plan (specification) |
+| `/sdd-forge.flow-impl` | implement (coding + review) |
+| `/sdd-forge.flow-merge` | merge (wrap-up) |
 
-Feature development flow:
+**[Codex CLI](https://github.com/openai/codex)** — invoke via `$` prefix:
 
-```
-  spec          Create spec (feature branch + spec.md)
-    ↓
-  gate          Spec gate check ← verified by program (not AI)
-    ↓
-  implement     Code after gate PASS
-    ↓
-  forge         AI updates documentation
-    ↓
-  review        AI quality check (repeat until PASS)
-```
-
-### AI Agent Integration
-
-#### Claude Code
-
-Run SDD workflows via skills:
-
-```
-/sdd-flow-start   — create spec → gate → start implementation
-/sdd-flow-close   — forge → review → commit → merge
-```
+| Command | Phase |
+|---|---|
+| `$sdd-forge flow start` | plan (start specification) |
+| `$sdd-forge flow review` | implement (AI code review) |
+| `$sdd-forge flow merge` | merge (wrap-up) |
 
-#### Codex CLI
+## Commands
 
-Run workflows from the `$` prompt:
+| Command | Description |
+|---|---|
+| `setup` | Register project and generate config |
+| `docs build` | Run the full documentation pipeline |
+| `docs readme` | Generate `README.md` from `docs/` |
+| `docs review` | Check documentation quality |
+| `flow start` | Start the SDD flow |
+| `flow status` | Show flow progress |
+| `presets` | List available presets |
+| `help` | Show all commands |
 
-```
-$sdd-flow-start   — create spec → gate → start implementation
-$sdd-flow-close   — forge → review → commit → merge
-```
+See `sdd-forge help` or the [command reference](docs/cli_commands.md) for the full list.
 
 ## Configuration
 
-`sdd-forge setup` generates `.sdd-forge/config.json`:
+`setup` generates `.sdd-forge/config.json`:
 
 ```jsonc
 {
   "type": "cli/node-cli",     // project type (preset selection)
-  "lang": "en",               // documentation language
+  "lang": "en",               // operating language
   "defaultAgent": "claude",   // AI agent
   "providers": { ... }        // agent settings
 }
 ```
 
-### Customization
-
-Add project-specific templates and data sources:
-
-```
-.sdd-forge/
-├── templates/{lang}/
-│   ├── docs/      ← chapter template & README overrides
-│   └── specs/     ← spec.md / qa.md templates
-└── data/          ← custom data source modules
-```
+See the [configuration reference](docs/configuration.md) for details.
 
 ## Documentation
 
@@ -178,9 +127,9 @@ Add project-specific templates and data sources:
 | Chapter | Summary |
 | --- | --- |
 | [01. Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter introduces sdd-forge, a CLI tool for Spec-Driven Development that automates technical documentation gene… |
-| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | sdd-forge provides 20+ commands organized into four namespaces (`docs`, `spec`, `flow`, and standalone commands) thro… |
-| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge is configured primarily through `.sdd-forge/config.json`, which controls output language, project type, doc… |
-| [04. Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | This chapter describes the internal architecture of sdd-forge, covering its three-layer directory structure (`src/` →… |
+| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | sdd-forge provides over 20 CLI commands organized into four namespaces (`docs`, `spec`, `flow`, and standalone comman… |
+| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge uses a layered configuration system centered on `.sdd-forge/config.json`, supplemented by preset manifests … |
+| [04. Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | This chapter describes sdd-forge's internal architecture: the three-layer directory structure under `src/`, the depen… |
 <!-- {{/data}} -->
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.31",
+  "version": "0.1.0-alpha.32",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",
@@ -11,8 +11,7 @@
     "sdd-forge": "./src/sdd-forge.js"
   },
   "files": [
-    "src/",
-    "docs/"
+    "src/"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/docs/commands/changelog.js

@@ -132,7 +132,7 @@ function main() {
   let lang = DEFAULT_LANG;
   try {
     const cfgData = loadConfig(root);
-    lang = cfgData.output?.default || cfgData.lang || DEFAULT_LANG;
+    lang = cfgData.docs?.defaultLanguage || cfgData.lang || DEFAULT_LANG;
   } catch (_) {}
   const t = translate();
 

package/src/docs/commands/enrich.js

@@ -361,12 +361,12 @@ async function main(ctx) {
   }
 
   // Split into batches (lines-based with item count fallback)
-  const maxItems = Number(config.limits?.enrichBatchSize || 0) || DEFAULT_BATCH_SIZE;
-  const maxLines = Number(config.limits?.enrichBatchLines || 0) || DEFAULT_BATCH_LINES;
+  const maxItems = Number(config.docs?.enrichBatchSize || 0) || DEFAULT_BATCH_SIZE;
+  const maxLines = Number(config.docs?.enrichBatchLines || 0) || DEFAULT_BATCH_LINES;
   const hasLines = pending.some((e) => e.lines > 0);
   const batches = splitIntoBatches(pending, hasLines ? maxLines : 0, maxItems);
 
-  const timeoutMs = config.limits?.agentTimeout ? Number(config.limits.agentTimeout) * 1000 : DEFAULT_AGENT_TIMEOUT * 1000;
+  const timeoutMs = config.agent?.timeout ? Number(config.agent.timeout) * 1000 : DEFAULT_AGENT_TIMEOUT * 1000;
   let totalEnriched = 0;
 
   for (let b = 0; b < batches.length; b++) {

package/src/docs/commands/forge.js

@@ -32,12 +32,8 @@ import {
   buildForgePrompt,
 } from "../lib/forge-prompts.js";
 import {
-  FALLBACK_PATCH_ORDER,
   summarizeReview,
-  parseReviewMisses,
   parseFileResults,
-  patchGeneratedForMisses,
-  summarizeNeedsInput,
 } from "../lib/review-parser.js";
 
 const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT * 1000;
@@ -220,11 +216,11 @@ async function main() {
   const root = repoRoot(import.meta.url);
   const config = loadConfig(root);
   const type = resolveType(config.type || "");
-  const lang = config.output.default;
+  const lang = config.docs.defaultLanguage;
   const t = translate();
   const agent = resolveAgent(config, "docs.forge");
   const mode = cli.mode || DEFAULT_MODE;
-  const timeoutMs = config.limits?.agentTimeout ? Number(config.limits.agentTimeout) * 1000 : undefined;
+  const timeoutMs = config.agent?.timeout ? Number(config.agent.timeout) * 1000 : undefined;
 
   if (mode === "agent" && !agent) {
     throw new Error(
@@ -441,27 +437,14 @@ async function main() {
       currentTargetFiles = fileResults.failedFiles;
     }
 
-    const misses = parseReviewMisses(reviewOut);
-    console.log(
-      `[forge] parsed misses: ${FALLBACK_PATCH_ORDER.map((k) => `${k}=${(misses[k] || []).length}`).join(", ")}`,
-    );
-    const patchResult = patchGeneratedForMisses(root, misses, analysisData);
-    if (patchResult.changed) {
-      console.log("[forge] local deterministic patch applied.");
-      for (const file of patchResult.touched) {
-        console.log(`- patched: ${file}`);
-      }
-    } else if (agentFailed) {
+    if (agentFailed) {
       console.log(
         "[forge] no local patch candidates found after agent failure."
       );
     } else if (mode === "local" && !usedAgent) {
       console.log(t("messages:forge.needsInput"));
       console.log(t("messages:forge.reviewFeedback"));
-      const lines = summarizeNeedsInput(reviewOut);
-      for (const line of lines) {
-        console.log(`- ${line}`);
-      }
+      console.log(reviewFeedback);
       process.exitCode = 2;
       return;
     }

package/src/docs/commands/init.js

@@ -154,8 +154,8 @@ function main(ctx) {
 
   // テンプレート解決（ボトムアップ方式）
   const projectLocalDir = path.join(root, ".sdd-forge", "templates", lang, "docs");
-  const outputConfig = config?.output;
-  const fallbackLangs = outputConfig?.languages?.filter((l) => l !== lang) || [];
+  const docsConfig = config?.docs;
+  const fallbackLangs = docsConfig?.languages?.filter((l) => l !== lang) || [];
   const configChapters = config?.chapters;
   const chaptersOrder = resolveChaptersOrder(type, configChapters);
 
@@ -201,7 +201,7 @@ function main(ctx) {
       summaryData,
       agent,
       root,
-      config?.documentStyle?.purpose || "",
+      config?.docs?.style?.purpose || "",
     );
   }
 

package/src/docs/commands/readme.js

@@ -53,7 +53,7 @@ async function main(ctx) {
       const t = tr();
       const h = t.raw("ui:help.cmdHelp.readme");
       const o = h.options;
-      console.log([h.usage, "", `  ${h.desc}`, "", "Options:", `  ${o.dryRun}`, `  ${o.help}`].join("\n"));
+      console.log([h.usage, "", `  ${h.desc}`, "", "Options:", `  ${o.lang}`, `  ${o.output}`, `  ${o.dryRun}`, `  ${o.help}`].join("\n"));
       return;
     }
 
@@ -70,8 +70,8 @@ async function main(ctx) {
   }
 
   const projectLocalDir = path.join(root, ".sdd-forge", "templates", lang, "docs");
-  const outputConfig = config?.output;
-  const fallbackLangs = outputConfig?.languages?.filter((l) => l !== lang) || [];
+  const docsConfig = config?.docs;
+  const fallbackLangs = docsConfig?.languages?.filter((l) => l !== lang) || [];
 
   // ボトムアップでテンプレート解決
   const configChapters = config?.chapters;
@@ -143,7 +143,7 @@ async function main(ctx) {
       const agent = loadAgentConfig(cfg, "docs.readme");
       ensureAgentWorkDir(agent, root);
       const analysis = loadFullAnalysis(root) || {};
-      const documentStyle = cfg.documentStyle;
+      const documentStyle = cfg.docs?.style;
       const systemPrompt = buildTextSystemPrompt(documentStyle, lang);
       const timeoutMs = DEFAULT_AGENT_TIMEOUT * 1000;