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

package/README.md

@@ -1,186 +1,136 @@
-# <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+# <!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} -->
 
-<!-- {{data: docs.langSwitcher("absolute")}} -->
+<!-- {{data("cli.docs.langSwitcher", {labels: "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)
+[![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}} -->
+npm install -g <!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} -->
+</pre>
 
-# yarn
-yarn global add <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+### Setup
 
-# pnpm
-pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+<pre>
+<!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} --> setup
 </pre>
 
-### Setup & Generate
+An interactive wizard configures your project type (preset) and AI agent.
 
-<pre>
-# 1. Register your project (interactive wizard)
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
+### Generate docs for an existing project
 
-# 2. Generate all documentation (scan → enrich → init → data → text → readme → agents → translate)
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
+If you already have source code, generate documentation to get a complete picture of the system. Especially useful for onboarding onto legacy codebases.
+
+<pre>
+<!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} --> docs build
 </pre>
 
-That's it — `docs/` and `README.md` are generated.
+### Develop with the SDD flow
 
-## Commands
+**[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — run each phase via skills:
 
-### Documentation Generation
-
-| Command | Description |
+| Skill | Phase |
 |---|---|
-| `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
+| `/sdd-forge.flow-plan` | plan (specification) |
+| `/sdd-forge.flow-impl` | implement (coding + review) |
+| `/sdd-forge.flow-merge` | merge (wrap-up) |
 
-| Command | Description |
+**[Codex CLI](https://github.com/openai/codex)** — invoke via `$` prefix:
+
+| Command | Phase |
 |---|---|
-| `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 |
+| `$sdd-forge flow start` | plan (start specification) |
+| `$sdd-forge flow review` | implement (AI code review) |
+| `$sdd-forge flow merge` | merge (wrap-up) |
 
-### Other
+## Commands
 
 | 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 command list |
-
-## SDD Workflow
+| `help` | Show all commands |
 
-Feature development flow:
-
-```
-  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
-```
-
-#### Codex CLI
-
-Run workflows from the `$` prompt:
-
-```
-$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
 
-<!-- {{data: docs.chapters("Chapter|Summary")}} -->
+<!-- {{data("cli.docs.chapters", {header: "", labels: "Chapter|Summary", ignoreError: true})}} -->
 | 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/` →… |
+| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | sdd-forge is a CLI tool that automates technical documentation generation through source code analysis and provides a… |
+| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) | sdd-forge is a CLI tool built entirely in JavaScript on Node.js, using ES modules with zero external dependencies. |
+| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) | The project consists of 1 top-level source directory (src/) containing 157 files across 5 major areas: CLI entry poin… |
+| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | sdd-forge provides over 25 CLI commands organized into four namespaces — docs (12 subcommands), spec (4 subcommands),… |
+| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge uses two primary configuration files — .sdd-forge/config.json for project-specific settings and preset.json… |
 <!-- {{/data}} -->
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.31",
+  "version": "0.1.0-alpha.361",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",
@@ -12,7 +12,7 @@
   },
   "files": [
     "src/",
-    "docs/"
+    "!src/presets/*/tests/"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -25,7 +25,10 @@
     "technical-docs"
   ],
   "scripts": {
-    "test": "find tests -name '*.test.js' | xargs node --test"
+    "test": "node tests/run.js",
+    "test:unit": "node tests/run.js --scope unit",
+    "test:e2e": "node tests/run.js --scope e2e",
+    "test:acceptance": "node tests/acceptance/run.js"
   },
   "license": "MIT"
 }