sdd-forge 0.1.0-alpha.4 → 0.1.0-alpha.549

package/README.md

@@ -1,50 +1,142 @@
-# sdd-forge
+# <!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} -->
 
-Spec-Driven Development tooling for automated documentation generation
+<!-- {{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)
 
-| カテゴリ | 技術 |
-|----------|------|
-| 言語 | Node.js (ES Modules) |
-| 配布 | npm |
-| テスト | — |
+> **Alpha:** APIs, command structure, and configuration formats may change without notice.
 
-## クイックスタート
+## Spec-Driven Development — Design, implement, and document in a single flow
 
-```bash
-npm install -g sdd-forge
-sdd-forge help
+A spec-first development flow manager designed to work with AI coding agents.
+
+## The SDD Flow
+
+Every feature goes through three phases, from spec to merge.
+
+```
+plan ──────── Specification
+│  ├─ draft       Refine requirements through dialogue
+│  ├─ spec        Create spec (feature branch + spec.md)
+│  ├─ gate        Spec validation + guardrail check
+│  └─ test        Write test code
+│
+implement ─── Coding
+│  ├─ implement   Write code after gate PASS
+│  └─ review      AI code review
+│
+finalize ──── Wrap-up
+│  ├─ commit      Commit + retro + report
+│  ├─ merge       Squash merge or PR
+│  ├─ sync        Auto-update documentation
+│  └─ cleanup     Remove branch / worktree
 ```
 
-## ドキュメント
+### AI stays in its lane
 
-| 章 | 概要 |
-|----|------|
-| [01. ツール概要とアーキテクチャ](docs/01_overview.md) | 本章では、sdd-forge がどのような課題を解決するツールであるか、その全体的なアーキテクチャ、および利用を開始するまでの典型的なフローを説明します。ソースコードの自動解析によるドキュメント生成と、Spec-Driven Development ワークフローの両面からツールの役割を理解できます。 |
-| [02. CLI コマンドリファレンス](docs/02_cli_commands.md) | `sdd-forge` は `sdd-forge <コマンド>` 形式のサブコマンド体系を採用しており、ドキュメント生成・品質チェック・SDD ワークフロー支援など 16 種類のコマンドを提供しています。すべてのコマンドで共通して利用できるグローバルオプションとして `--help` および `--project` が用意されています。 |
-| [02. 技術スタックと運用](docs/02_stack_and_ops.md) | 本章では、sdd-forge が動作するために必要な技術スタックと、日常的な運用・デプロイ手順を説明します。Node.js 18 以上を実行環境とする純粋な ES モジュール CLI ツールであり、外部フレームワークや npm 依存パッケージを持たない軽量な構成です。 |
-| [03. 設定とカスタマイズ](docs/03_configuration.md) | sdd-forge は `.sdd-forge/config.json` を中心とした複数の設定ファイルを読み込み、ドキュメント生成の言語・スタイル・AI プロバイダー・プロジェクト登録などを制御します。テンプレートや AI エージェントのコマンドをカスタマイズすることで、さまざまなプロジェクト環境に合わせた柔軟な運用が可能です。 |
-| [03. プロジェクト構成](docs/03_project_structure.md) | 本章では sdd-forge のソースコード構成を解説します。`src/` 配下は `docs`・`specs`・`lib`・`templates` の 4 つの主要ディレクトリに整理されており、それぞれドキュメント生成・仕様管理・共通処理・テンプレートの役割を担っています。 |
-| [04. 開発ガイド](docs/04_development.md) | 本章では、sdd-forge の開発環境セットアップからローカル開発の手順、テスト実行までを説明します。外部依存パッケージがないため `npm install` と `npm link` のみで開発環境を構築でき、テストは Node.js 標準の `node:test` モジュールと `node --test` コマンドで実行します。 |
-| [04. 内部設計](docs/04_internal_design.md) | 本章では sdd-forge の内部構造を解説します。エントリポイント `sdd-forge.js` からサブシステムディスパッチャ（`docs.js` / `spec.js` / `flow.js`）、さらに `commands/` 配下の個別コマンドへと三層構造で委譲が行われ、`src/lib/` の共有ユーティリティが各層から横断的に利用されます。 |
-| [05. CLI コマンドリファレンス](docs/05_commands.md) | `sdd-forge` が提供する 16 のサブコマンドをリファレンス形式でまとめた章です。すべてのコマンドに共通する `--project` および `--help` グローバルオプションを備え、ドキュメント生成系・SDD ワークフロー系・プロジェクト管理系の 3 つの用途に大別されるサブコマンド体系を構成しています。 |
-| [05. 開発・テスト・配布](docs/05_development.md) | 本章では、`npm link` を用いたビルドレスなローカル開発環境の構築手順から、ブランチ運用・コミット規約・リリースフローまで、sdd-forge の開発に参加するために必要な情報をまとめています。外部依存ライブラリを持たない素の ES Modules 構成により、セットアップは最小限の手順で完了します。 |
-| [06. 設定とカスタマイズ](docs/06_config.md) | sdd-forge は `.sdd-forge/config.json` を中心に動作し、プロジェクトタイプ・出力言語・ドキュメントスタイル・AI エージェントなどを一元管理します。`sdd-forge setup` で初期生成された設定ファイルを直接編集することで、ドキュメント生成の挙動やワークフローのマージ戦略などをカスタマイズできます。 |
+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.
 
-## 開発ワークフロー（SDD）
+- **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
 
-本プロジェクトは Spec-Driven Development（SDD）を採用しています。
+## Automatic Doc Sync
 
+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`.
+
+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
+
+### Install
+
+<pre>
+npm install -g <!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} -->
+</pre>
+
+### Setup
+
+<pre>
+<!-- {{data("cli.project.name")}} -->sdd-forge<!-- {{/data}} --> setup
+</pre>
+
+An interactive wizard configures your project type (preset) and AI agent.
+
+### Generate docs for an existing project
+
+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>
+
+### Develop with the SDD flow
+
+**[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — run each phase via skills:
+
+| Skill | Phase |
+|---|---|
+| `/sdd-forge.flow-plan` | plan (specification) |
+| `/sdd-forge.flow-impl` | implement (coding + review) |
+| `/sdd-forge.flow-finalize` | finalize (commit, merge, docs sync, cleanup) |
+
+**[Codex CLI](https://github.com/openai/codex)** — invoke via `$` prefix:
+
+| Command | Phase |
+|---|---|
+| `$sdd-forge flow prepare --title "..." --base main` | plan (create spec + branch) |
+| `$sdd-forge flow run review` | implement (AI code review) |
+| `$sdd-forge flow run finalize --mode all` | finalize (wrap-up) |
+
+## 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 prepare` | Create spec and branch |
+| `flow get status` | Show flow progress |
+| `presets` | List available presets |
+| `help` | Show all commands |
+
+See `sdd-forge help` or the [command reference](docs/cli_commands.md) for the full list.
+
+## Configuration
+
+`setup` generates `.sdd-forge/config.json`:
+
+```jsonc
+{
+  "type": "node-cli",          // project type (preset name)
+  "lang": "en",                // operating language
+  "agent": {
+    "default": "claude",       // AI agent
+    "providers": { ... }       // agent settings
+  }
+}
 ```
-1. sdd-forge spec --title "..."   — 仕様ファイル作成
-2. sdd-forge gate --spec ...      — 仕様ゲート（未解決事項がなければ PASS）
-3. 実装
-4. sdd-forge forge --prompt "..."  — ドキュメント自動更新
-5. sdd-forge review               — ドキュメントレビュー
-```
 
-詳細は [CLAUDE.md](CLAUDE.md) の「SDDフロー」セクションを参照してください。
+See the [configuration reference](docs/configuration.md) for details.
+
+## Documentation
+
+<!-- {{data("cli.docs.chapters", {header: "", labels: "Chapter|Summary", ignoreError: true})}} -->
+| Chapter | Summary |
+| --- | --- |
+| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter introduces sdd-forge — a CLI tool for automated documentation generation and Spec-Driven Development (SD… |
+| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) | sdd-forge is implemented in JavaScript using Node.js (>=18.0.0) with the ES Modules system, and is distributed as a z… |
+| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) | This chapter describes the source layout of sdd-forge across three major directory groups: src/docs (documentation ge… |
+| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | The CLI provides over 30 commands organized in a three-level dispatch hierarchy: the top-level sdd-forge entry point … |
+| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge reads a single JSON configuration file placed inside your project's .sdd-forge/ directory and exposes a bro… |
+| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | This chapter describes the internal architecture of sdd-forge, a layered CLI tool in which top-level dispatchers rout… |
+<!-- {{/data}} -->
+
+## License
 
-<!-- MANUAL:START -->
-<!-- MANUAL:END -->
+MIT

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.549",
   "description": "Spec-Driven Development tooling for automated documentation generation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpreadWorks/sdd-forge.git"
+  },
   "type": "module",
   "bin": {
     "sdd-forge": "./src/sdd-forge.js"
   },
   "files": [
-    "src/"
+    "src/",
+    "!src/presets/*/tests/"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -20,7 +25,11 @@
     "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"
+  "license": "MIT",
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319"
 }