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

package/README.md

@@ -1,45 +1,137 @@
-# {{PROJECT_NAME}}
+# <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 
-{{PROJECT_DESCRIPTION}}
+<!-- {{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)
+[![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 {{PACKAGE_NAME}}
-{{PACKAGE_NAME}} 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       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
 ```
 
-## ドキュメント
+### AI stays in its lane
 
-| 章 | 概要 |
-|----|------|
-| [01. ツール概要とアーキテクチャ](docs/01_overview.md) | `sdd-forge` は、PHP-MVC プロジェクト（CakePHP 等）における「仕様と実装の乖離」および「技術ドキュメントの作成・維持コスト」という課題を解決するための Node.js CLI ツールである。ソースコード静的解析（`scan`）・テンプレート駆動のドキュメント生成（`init` / `populate` / `tfill`）・仕様ゲート管理（`spec` / `gate`）・反復改善ループ（`forge`）を単一パッケージに統合し、Spec-Driven Development（SDD）ワークフローをコマンドラインから一貫して実行できる。 |
-| [02. CLI コマンドリファレンス](docs/02_cli_commands.md) | `SCRIPTS` オブジェクトから `scan:all` を含めると 19 コマンド（エントリは 18 だが `scan:all` は別処理）が確認できます。正確な数を数えます。 |
-| [03. 設定とカスタマイズ](docs/03_configuration.md) | sdd-forge の動作は `.sdd-forge/config.json` を中心とした複数の JSON 設定ファイルによって制御され、言語・テンプレートタイプ・AIプロバイダー・タイムアウト・テキスト生成挙動など幅広い項目をカスタマイズできる。プロジェクトごとのテンプレート差し替えは `project-overrides.json`、解析結果の表現上書きは `overrides.json` で行い、関心ごとに設定を分離できる構成になっている。 |
-| [04. 内部設計](docs/04_internal_design.md) | `src/bin/sdd-forge.js` がサブコマンドを各モジュール（`analyzers/`・`engine/`・`spec/`・`forge/`・`flow/`）へディスパッチし、共通ユーティリティ `lib/` を底辺として解析→生成→改善の方向で一方向に依存が流れる設計になっている。PHPソースを `analyzers/` が `analysis.json` へ変換し、`engine/populate` と `engine/tfill` がそのデータをテンプレートと組み合わせて `docs/` へ展開するパイプラインが中心的な処理フローである。 |
-| [05. 開発・テスト・配布](docs/05_development.md) | `npm link` を使ったビルド不要のローカル開発環境、外部依存ゼロの Node.js 実装、および `npm version` と `npm publish` による npm レジストリへのリリースフローを中心に構成された章である。テストフレームワークは現時点では導入されておらず、動作確認はコマンド直接実行による手動テストで行う。 |
+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: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+</pre>
+
+### Setup
+
+<pre>
+<!-- {{data: 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: 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-merge` | merge (wrap-up) |
+
+**[Codex CLI](https://github.com/openai/codex)** — invoke via `$` prefix:
+
+| Command | Phase |
+|---|---|
+| `$sdd-forge flow start` | plan (start specification) |
+| `$sdd-forge flow review` | implement (AI code review) |
+| `$sdd-forge flow merge` | merge (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 start` | Start the SDD flow |
+| `flow 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": "cli/node-cli",     // project type (preset selection)
+  "lang": "en",               // operating language
+  "defaultAgent": "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: docs.chapters("Chapter|Summary")}} -->
+| 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 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
 
-<!-- MANUAL:START -->
-<!-- MANUAL:END -->
+MIT

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.3",
-  "description": "Spec-Driven Development tooling for PHP-MVC documentation generation",
+  "version": "0.1.0-alpha.32",
+  "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/bin/sdd-forge.js"
+    "sdd-forge": "./src/sdd-forge.js"
   },
   "files": [
     "src/"
@@ -15,9 +19,12 @@
   "keywords": [
     "sdd",
     "documentation",
-    "php",
-    "cakephp",
-    "spec-driven-development"
+    "spec-driven-development",
+    "source-analysis",
+    "technical-docs"
   ],
+  "scripts": {
+    "test": "find tests -name '*.test.js' | xargs node --test"
+  },
   "license": "MIT"
 }

package/src/README.md

@@ -0,0 +1,201 @@
+# sdd-forge — Internal Architecture
+
+## Overview
+
+sdd-forge は Spec-Driven Development (SDD) のための CLI ツール。
+対象プロジェクトのソースコードを解析し、テンプレートベースのドキュメントを自動生成する。
+
+- **Runtime**: Node.js >= 18
+- **Module system**: ES Modules (`"type": "module"`)
+- **External dependencies**: なし（Node.js 組み込み API のみ）
+
+## Directory Structure
+
+```text
+src/
+├── sdd-forge.js              # CLI エントリポイント（トップレベルディスパッチャ）
+├── docs.js                   # docs ディスパッチャ
+├── spec.js                   # spec ディスパッチャ
+├── flow.js                   # SDD フロー自動実行（直接実行コマンド）
+├── help.js                   # コマンド一覧表示
+│
+├── docs/                     # ドキュメント生成ドメイン
+│   ├── commands/             #   CLI コマンド（各サブコマンドの実装）
+│   ├── lib/                  #   共通ロジック（パーサー、レンダラー、リゾルバー等）
+│   └── presets/              #   フレームワーク固有の解析・テンプレート拡張
+│       └── webapp/cakephp2/  #     CakePHP 2.x 用プリセット
+│
+├── specs/                    # 仕様管理ドメイン
+│   └── commands/             #   CLI コマンド（spec 初期化、gate チェック）
+│
+├── lib/                      # パッケージ全体の共通ユーティリティ
+│   ├── cli.js                #   repoRoot(), sourceRoot(), parseArgs()
+│   ├── config.js             #   loadJsonFile(), 設定読み込み
+│   ├── agent.js              #   AI エージェント抽象化
+│   ├── process.js            #   プロセス実行ヘルパー
+│   ├── projects.js           #   プロジェクト管理（登録、解決、デフォルト）
+│   ├── i18n.js               #   国際化（メッセージ・UI テキスト）
+│   └── types.js              #   型定義・定数
+│
+├── presets/                  # プリセット（テンプレート + DataSource + スキャン設定）
+│   ├── base/templates/ja/   #   共通章テンプレート（全タイプ共通）
+│   ├── webapp/templates/ja/ #   Web アプリ用章テンプレート
+│   ├── cli/templates/ja/    #   CLI ツール用章テンプレート
+│   ├── library/templates/ja/#   ライブラリ用章テンプレート
+│   ├── cakephp2/            #   CakePHP 2.x（templates + data + scan）
+│   ├── laravel/             #   Laravel 8+
+│   ├── symfony/             #   Symfony 5+
+│   └── node-cli/            #   Node.js CLI
+├── locale/                   # 言語別メッセージ
+│   ├── en/                   #   English
+│   └── ja/                   #   日本語
+│       ├── messages.json     #     CLI メッセージ
+│       ├── prompts.json      #     AI プロンプトテンプレート
+│       └── ui.json           #     UI テキスト
+└── templates/                # 静的データ（npm publish に含まれる）
+    ├── config.example.json   #   .sdd-forge/config.json のサンプル
+    └── review-checklist.md   #   レビュー観点チェックリスト
+```
+
+## Command Routing
+
+3 段階のディスパッチで CLI コマンドをルーティングする。
+
+```
+sdd-forge <cmd> [args]
+    │
+    ├─ sdd-forge.js          # 1. プロジェクトコンテキスト解決 + ディスパッチ
+    │   ├─ docs.js           # 2. docs サブコマンドのルーティング
+    │   │   └─ docs/commands/*.js   # 3. 実際のコマンド実装
+    │   ├─ spec.js           # 2. spec サブコマンドのルーティング
+    │   │   └─ spec/commands/*.js   # 3. 実際のコマンド実装
+    │   ├─ flow.js           # 2+3. 直接実行（ディスパッチャなし）
+    │   └─ help.js           # 2+3. 直接実行
+```
+
+- **ディスパッチャ** (`docs.js`, `spec.js`): サブコマンド名を受け取り、`commands/` 配下のスクリプトに `import()` で委譲する
+- **直接実行コマンド** (`flow.js`, `help.js`): サブコマンドを持たず、引数をそのまま処理する
+
+### プロジェクトコンテキスト
+
+`sdd-forge.js` は実行時に以下の環境変数を設定する:
+
+| 環境変数 | 意味 | 設定元 |
+|---|---|---|
+| `SDD_SOURCE_ROOT` | 対象プロジェクトのソースコードルート | `projects.js` で解決 |
+| `SDD_WORK_ROOT` | 作業ディレクトリ（`.sdd-forge/`, `docs/` の親） | `projects.js` で解決 |
+
+各コマンドは `lib/cli.js` の `sourceRoot()` / `repoRoot()` 経由でこれらを参照する。
+
+## Coding Rules
+
+### プロジェクト固有情報の埋め込み禁止
+
+`src/` 配下のコードおよび `src/templates/` 配下のテンプレートに、特定プロジェクトの情報を直接書いてはならない。
+
+- **禁止**: プロジェクト名、ホスト名、ポート番号、コンテナ名、固有 DB 名
+- **許可**: `presets/` 配下のフレームワーク固有ロジック（汎用的な解析パターン）
+- **設定**: プロジェクト固有の値は `.sdd-forge/config.json` で外部化する
+
+### 外部依存の禁止
+
+Node.js 組み込み API (`fs`, `path`, `child_process`, `url` 等) のみを使用する。
+npm パッケージへの依存を追加しないこと。
+
+### フォールバック値の抑制
+
+必須の設定値・環境変数が不足している場合は、黙ってデフォルト値で動作させず、エラーメッセージを出力して停止すること。
+
+```js
+// NG
+const agent = config.agent ?? "claude";
+
+// OK
+if (!config.agent) {
+  console.error("Error: 'agent' is not configured in config.json");
+  process.exit(1);
+}
+```
+
+### コマンドファイルの構造
+
+`commands/` 配下のファイルは以下のパターンに従う:
+
+```js
+import { repoRoot, parseArgs } from "../../lib/cli.js";
+
+function main() {
+  const args = process.argv.slice(2);
+  const opts = parseArgs(args, { flags: [...], options: [...] });
+
+  if (opts.help) {
+    console.log("Usage: ...");
+    process.exit(0);
+  }
+
+  // 実装
+}
+
+main();
+```
+
+- `parseArgs()` で `--help` を処理する
+- 直接実行ガード (`isDirectRun`) が必要なスクリプトは、`docs.js` の `build` パイプラインで `import()` される場合のみ
+
+### presets の追加
+
+新しいフレームワークプリセットを追加する場合:
+
+1. `docs/presets/<type>/<framework>/` ディレクトリを作成
+2. `scanner.js` — フレームワーク固有のスキャン拡張
+3. `resolver.js` — `{{data}}` ディレクティブのデータ解決ロジック
+4. `analyze-*.js` — 個別カテゴリの解析スクリプト（必要に応じて）
+5. `templates/locale/<lang>/<type>/<framework>/` に章テンプレートのオーバーライドを配置
+
+### テンプレート継承
+
+テンプレートは `base → type → framework` の順で継承される。
+
+```
+locale/ja/base/01_overview.md          ← 全タイプ共通
+locale/ja/webapp/05_auth_and_session.md  ← webapp タイプ共通
+locale/ja/webapp/cakephp2/05_auth_and_session.md  ← CakePHP 2.x 固有オーバーライド
+```
+
+より具体的なパスにファイルが存在すれば、そちらが優先される。
+
+## Agent Invocation (`lib/agent.js`)
+
+### 非同期呼び出しで `execFile` を使ってはならない
+
+`callAgentAsync()` は CLI エージェント（`claude`, `codex` 等）を子プロセスとして起動する。
+Node.js の `execFile`（非同期版）はデフォルトで stdin を `pipe` モードで開くが、
+Claude CLI は stdin が pipe だと EOF を待ち続けてハングする。
+`execFileSync`（同期版）は内部で stdin を即座に閉じるため問題が起きないが、
+非同期版では閉じられない。
+
+**これは Node.js の既知の制限であり、`execFile` では stdin を `ignore` に設定できない。**
+
+- [nodejs/node#60077](https://github.com/nodejs/node/issues/60077) — `execFile` で stdin を ignore に設定できない
+- [anthropics/claude-code#771](https://github.com/anthropics/claude-code/issues/771) — Claude CLI が Node.js の `execFile` でハングする
+
+**対策**: `child_process.spawn` を使い、`stdio: ["ignore", "pipe", "pipe"]` を明示する。
+
+```js
+// NG: execFile — stdin が pipe のままでハングする
+execFile("claude", args, opts, callback);
+
+// OK: spawn — stdin を ignore で閉じる
+const child = spawn("claude", args, {
+  stdio: ["ignore", "pipe", "pipe"],
+  ...opts,
+});
+```
+
+`forge.js` の `streamOutput` パスは既にこのパターンを使用している。
+
+## File Operations
+
+- ファイルの削除・リネーム・移動は `git mv` / `git rm` を使用し、履歴を保持する
+- コミットメッセージは英語。形式: `<type>: <subject>`
+  - type: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`

package/src/docs/commands/agents.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * src/docs/commands/agents.js
+ *
+ * AGENTS.md を更新する。
+ * AGENTS.md 内の {{data: agents.sdd}} / {{data: agents.project}} ディレクティブを解決し、
+ * PROJECT セクションは AI で精査する。
+ */
+
+import fs from "fs";
+import path from "path";
+import { runIfDirect } from "../../lib/entrypoint.js";
+import { parseArgs } from "../../lib/cli.js";
+import { sddOutputDir } from "../../lib/config.js";
+import { callAgent, loadAgentConfig, DEFAULT_AGENT_TIMEOUT } from "../../lib/agent.js";
+import { translate } from "../../lib/i18n.js";
+import { resolveType } from "../../lib/types.js";
+import { createResolver } from "../lib/resolver-factory.js";
+import { createLogger } from "../../lib/progress.js";
+import { parseDirectives, replaceBlockDirective, resolveDataDirectives } from "../lib/directive-parser.js";
+import { resolveCommandContext, loadFullAnalysis, getChapterFiles, readText } from "../lib/command-context.js";
+
+const logger = createLogger("agents");
+
+// ---------------------------------------------------------------------------
+// AI プロンプト構築
+// ---------------------------------------------------------------------------
+
+function buildAgentsSystemPrompt() {
+  const t = translate();
+  const rules = t.raw("prompts:agents.outputRules") || [];
+  return [
+    t("prompts:agents.systemPrompt"),
+    "",
+    "## Output Rules (strict)",
+    ...rules.map((r) => `- ${r}`),
+  ].join("\n");
+}
+
+function buildRefinePrompt(projectContent, docsContent, config, srcRoot, sddContent) {
+  const parts = [];
+
+  if (sddContent) {
+    parts.push("## SDD Section (already present — do not duplicate)");
+    parts.push(sddContent);
+    parts.push("");
+  }
+
+  parts.push("## Current PROJECT Section (template-generated)");
+  parts.push(projectContent);
+  parts.push("");
+
+  if (config.type) {
+    parts.push("## Project Config");
+    parts.push(`- type: ${config.type}`);
+    parts.push("");
+  }
+
+  const pkgPath = path.join(srcRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      if (pkg.scripts) {
+        parts.push("## package.json scripts");
+        parts.push(JSON.stringify(pkg.scripts, null, 2));
+        parts.push("");
+      }
+    } catch (_) { /* skip */ }
+  }
+
+  if (docsContent) {
+    parts.push("## Generated Documentation");
+    parts.push(docsContent);
+  }
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// ディレクティブ解決
+// ---------------------------------------------------------------------------
+
+/**
+ * AGENTS.md 内の {{data}} ディレクティブを解決する。
+ * agents.project ディレクティブの解決結果を返す（AI 精査用）。
+ */
+function resolveAgentsDirectives(text, resolveFn) {
+  let sddContent = null;
+  let projectContent = null;
+
+  const result = resolveDataDirectives(
+    text,
+    (source, method, labels) => resolveFn(source, method, {}, labels),
+    {
+      onResolve(d, rendered) {
+        if (d.source === "agents" && d.method === "sdd") sddContent = rendered;
+        if (d.source === "agents" && d.method === "project") projectContent = rendered;
+      },
+    },
+  );
+
+  return { text: result.text, sddContent, projectContent };
+}
+
+/**
+ * AI 精査後の PROJECT セクションで、ディレクティブ内部を差し替える。
+ */
+function replaceProjectContent(text, refined) {
+  const directives = parseDirectives(text);
+  const lines = text.split("\n");
+
+  for (let i = directives.length - 1; i >= 0; i--) {
+    const d = directives[i];
+    if (d.type !== "data" || d.source !== "agents" || d.method !== "project") continue;
+    if (d.endLine < 0) continue;
+
+    replaceBlockDirective(lines, d, refined);
+    break;
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(ctx) {
+  if (!ctx) {
+    const cli = parseArgs(process.argv.slice(2), {
+      flags: ["--dry-run"],
+      options: [],
+      defaults: { dryRun: false },
+    });
+
+    if (cli.help) {
+      const tu = translate();
+      const h = tu.raw("ui:help.cmdHelp.agents");
+      const o = h.options;
+      console.log([
+        h.usage, "", `  ${h.desc}`, `  ${h.descDetail}`, "", "Options:",
+        `  ${o.dryRun}`,
+      ].join("\n"));
+      return;
+    }
+
+    ctx = resolveCommandContext(cli);
+    ctx.dryRun = cli.dryRun;
+  }
+
+  const { root, srcRoot, config, lang, t } = ctx;
+
+  const agentsPath = path.join(srcRoot, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) {
+    throw new Error(t("messages:agents.notFound", { path: agentsPath }));
+  }
+
+  // Load analysis
+  const analysis = loadFullAnalysis(root);
+  if (!analysis) {
+    throw new Error(t("messages:agents.analysisNotFound", { path: path.join(sddOutputDir(root), "analysis.json") }));
+  }
+
+  // Load generated docs as context (instead of raw analysis.json)
+  const docsDir = path.join(root, "docs");
+  const chapterFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: ctx.config?.chapters });
+  const docsContent = chapterFiles.map((f) => readText(path.join(docsDir, f))).join("\n\n");
+  const readmeContent = readText(path.join(srcRoot, "README.md"));
+  const combinedDocs = [docsContent, readmeContent].filter(Boolean).join("\n\n---\n\n");
+
+  // Create resolver and resolve {{data}} directives
+  const resolvedType = resolveType(config.type || "base");
+  const resolver = await createResolver(resolvedType, root, { configChapters: config.chapters });
+  const resolveFn = (source, method, a, labels) => resolver.resolve(source, method, analysis, labels);
+
+  let content = fs.readFileSync(agentsPath, "utf8");
+  const { text: resolved, sddContent, projectContent } = resolveAgentsDirectives(content, resolveFn);
+  content = resolved;
+
+  // AI refinement for PROJECT section
+  if (projectContent) {
+    const agent = loadAgentConfig(config, "docs.agents");
+
+    logger.log(t("messages:agents.refining"));
+    const systemPrompt = buildAgentsSystemPrompt();
+    const prompt = buildRefinePrompt(projectContent, combinedDocs, config, srcRoot, sddContent);
+
+    try {
+      const result = callAgent(agent, prompt, DEFAULT_AGENT_TIMEOUT * 1000, undefined, { systemPrompt });
+
+      let refined = result.trim();
+
+      content = replaceProjectContent(content, refined);
+    } catch (err) {
+      throw new Error(`AI agent call failed: ${err.message}`);
+    }
+
+    logger.log(t("messages:agents.generated"));
+  }
+
+  if (ctx.dryRun) {
+    logger.log(t("messages:agents.dryRun", { path: agentsPath }));
+    console.log(content);
+    return;
+  }
+
+  fs.writeFileSync(agentsPath, content, "utf8");
+  console.log(t("messages:agents.updated", { path: agentsPath }));
+}
+
+export { main };
+
+runIfDirect(import.meta.url, main);