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

package/README.md

@@ -1,6 +1,6 @@
-# {{PROJECT_NAME}}
+# sdd-forge
 
-{{PROJECT_DESCRIPTION}}
+Spec-Driven Development tooling for automated documentation generation
 
 ## 技術スタック
 
@@ -13,19 +13,24 @@
 ## クイックスタート
 
 ```bash
-npm install -g {{PACKAGE_NAME}}
-{{PACKAGE_NAME}} help
+npm install -g sdd-forge
+sdd-forge help
 ```
 
 ## ドキュメント
 
 | 章 | 概要 |
 |----|------|
-| [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 レジストリへのリリースフローを中心に構成された章である。テストフレームワークは現時点では導入されておらず、動作確認はコマンド直接実行による手動テストで行う。 |
+| [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` で初期生成された設定ファイルを直接編集することで、ドキュメント生成の挙動やワークフローのマージ戦略などをカスタマイズできます。 |
 
 ## 開発ワークフロー（SDD）
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.2",
-  "description": "Spec-Driven Development tooling for PHP-MVC documentation generation",
+  "version": "0.1.0-alpha.4",
+  "description": "Spec-Driven Development tooling for automated documentation generation",
   "type": "module",
   "bin": {
-    "sdd-forge": "./src/bin/sdd-forge.js"
+    "sdd-forge": "./src/sdd-forge.js"
   },
   "files": [
     "src/"
@@ -15,9 +15,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,169 @@
+# 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              #   型定義・定数
+│
+└── templates/                # 静的データ（npm publish に含まれる）
+    ├── config.example.json   #   .sdd-forge/config.json のサンプル
+    ├── review-checklist.md   #   レビュー観点チェックリスト
+    └── locale/               #   言語別テンプレート・メッセージ
+        ├── en/               #     English
+        └── ja/               #     日本語
+            ├── base/         #       共通章テンプレート（全プロジェクトタイプ共通）
+            ├── webapp/       #       Web アプリ用章テンプレート
+            │   └── cakephp2/ #         CakePHP 2.x オーバーライド
+            ├── cli/          #       CLI ツール用章テンプレート
+            │   └── node-cli/ #         Node.js CLI オーバーライド
+            ├── library/      #       ライブラリ用章テンプレート
+            ├── messages.json #       CLI メッセージ
+            ├── prompts.json  #       AI プロンプトテンプレート
+            ├── sections.json #       セクション定義
+            └── ui.json       #       UI テキスト
+```
+
+## Command Routing
+
+3 段階のディスパッチで CLI コマンドをルーティングする。
+
+```
+sdd-forge <cmd> [args]
+    │
+    ├─ sdd-forge.js          # 1. プロジェクトコンテキスト解決 + ディスパッチ
+    │   ├─ docs.js           # 2. docs サブコマンドのルーティング
+    │   │   └─ docs/commands/*.js   # 3. 実際のコマンド実装
+    │   ├─ spec.js           # 2. spec サブコマンドのルーティング
+    │   │   └─ specs/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 固有オーバーライド
+```
+
+より具体的なパスにファイルが存在すれば、そちらが優先される。
+
+## File Operations
+
+- ファイルの削除・リネーム・移動は `git mv` / `git rm` を使用し、履歴を保持する
+- コミットメッセージは英語。形式: `<type>: <subject>`
+  - type: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`

package/src/docs/commands/agents.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+/**
+ * src/docs/commands/agents.js
+ *
+ * AGENTS.md を更新する。
+ *   デフォルト: AI エージェントで analysis.json を要約し PROJECT セクションを生成
+ *   --template: AI を使わずテンプレートベースで生成
+ *   --force:    SDD + PROJECT + 空の Guidelines で全体を書き直す
+ */
+
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+import { sourceRoot, repoRoot, parseArgs } from "../../lib/cli.js";
+import { loadJsonFile, loadConfig, resolveProjectContext } from "../../lib/config.js";
+
+const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// ---------------------------------------------------------------------------
+// SDD テンプレート読み込み
+// ---------------------------------------------------------------------------
+
+function loadSddTemplate(lang) {
+  for (const l of [lang, "en"]) {
+    const p = path.join(PKG_DIR, "templates", "locale", l, "base", "AGENTS.sdd.md");
+    if (fs.existsSync(p)) return fs.readFileSync(p, "utf8");
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// AI エージェント呼び出し
+// ---------------------------------------------------------------------------
+
+function loadAgentConfig(cfg, agentName) {
+  const providerKey = agentName || cfg.defaultAgent;
+  if (!providerKey) {
+    throw new Error("No default agent configured. Set 'defaultAgent' in config.json or run 'sdd-forge setup'.");
+  }
+  const provider = cfg.providers?.[providerKey];
+  if (!provider) {
+    throw new Error(`Unknown agent provider: ${providerKey}. Available: ${Object.keys(cfg.providers || {}).join(", ")}`);
+  }
+  return provider;
+}
+
+function callAgent(agent, prompt, timeoutMs) {
+  const args = Array.isArray(agent.args) ? [...agent.args] : [];
+  const resolvedArgs = args.map((a) =>
+    typeof a === "string" ? a.replaceAll("{{PROMPT}}", prompt) : a
+  );
+  const hasToken = args.some((a) => typeof a === "string" && a.includes("{{PROMPT}}"));
+  const finalArgs = hasToken ? resolvedArgs : [...resolvedArgs, prompt];
+
+  const env = { ...process.env };
+  delete env.CLAUDECODE;
+
+  return execFileSync(agent.command, finalArgs, {
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    timeout: timeoutMs,
+    env,
+  }).trim();
+}
+
+// ---------------------------------------------------------------------------
+// AI 要約プロンプト構築
+// ---------------------------------------------------------------------------
+
+function buildSummaryPrompt(analysis, config, srcRoot) {
+  const parts = [];
+
+  parts.push("以下のソースコード解析データ (analysis.json) を要約し、AGENTS.md の Project Context セクションを生成してください。");
+  parts.push("");
+  parts.push("## 出力ルール（厳守）");
+  parts.push("- <!-- PROJECT:START --> と <!-- PROJECT:END --> タグで囲むこと");
+  parts.push("- 最初の行は `<!-- PROJECT:START — managed by sdd-forge. Do not edit manually. -->` とすること");
+  parts.push("- 最後の行は `<!-- PROJECT:END -->` とすること");
+  parts.push("- `## Project Context` の見出しで始めること");
+  parts.push("- AI エージェントがプロジェクトを理解するのに役立つ情報を構造的にまとめること");
+  parts.push("- 技術スタック、プロジェクト構造の概要、主要コンポーネント、DB 構成、利用可能なコマンドを含めること");
+  parts.push("- マークダウンのテーブルやリストを活用して読みやすくすること");
+  parts.push("- 前置き・メタコメンタリーは含めないこと");
+  parts.push("");
+
+  // config info
+  if (config.type) {
+    parts.push(`## プロジェクト設定`);
+    parts.push(`- type: ${config.type}`);
+    const ctx = resolveProjectContext(repoRoot());
+    if (ctx) parts.push(`- context: ${ctx}`);
+    parts.push("");
+  }
+
+  // package.json scripts
+  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 (_) { /* ignore */ }
+  }
+
+  // analysis.json (truncated)
+  parts.push("## analysis.json");
+  const analysisJson = JSON.stringify(analysis, null, 2);
+  if (analysisJson.length > 30000) {
+    parts.push(analysisJson.slice(0, 30000));
+    parts.push("... (truncated)");
+  } else {
+    parts.push(analysisJson);
+  }
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// テンプレートベース PROJECT セクション生成
+// ---------------------------------------------------------------------------
+
+function generateProjectSectionTemplate(analysis, config, srcRoot) {
+  const lines = [];
+
+  lines.push("<!-- PROJECT:START — managed by sdd-forge. Do not edit manually. -->");
+  lines.push("## Project Context");
+  lines.push("");
+  lines.push(`- generated_at: ${new Date().toISOString().replace("T", " ").replace(/\.\d+Z$/, " UTC")}`);
+  lines.push("");
+
+  if (config.type) {
+    lines.push("### Technology Stack");
+    lines.push("");
+    lines.push(`- type: ${config.type}`);
+
+    if (analysis.extras?.composerDeps?.require) {
+      const req = analysis.extras.composerDeps.require;
+      if (req.php) lines.push(`- PHP: ${req.php}`);
+    }
+
+    const pkgPath = path.join(srcRoot, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        if (pkg.engines?.node) lines.push(`- Node.js: ${pkg.engines.node}`);
+      } catch (_) { /* ignore */ }
+    }
+
+    lines.push("");
+  }
+
+  const ctrl = analysis.controllers?.summary;
+  const mdl = analysis.models?.summary;
+  const sh = analysis.shells?.summary;
+  const rt = analysis.routes?.summary;
+
+  if (ctrl || mdl || sh || rt) {
+    lines.push("### Structure Summary");
+    lines.push("");
+    lines.push("| category | count | details |");
+    lines.push("| --- | --- | --- |");
+    if (ctrl) lines.push(`| Controllers | ${ctrl.total} | ${ctrl.totalActions} actions |`);
+    if (mdl) lines.push(`| Models | ${mdl.total} | FE: ${mdl.feModels || 0}, Logic: ${mdl.logicModels || 0} |`);
+    if (sh) lines.push(`| Shells | ${sh.total} | ${sh.withMain || 0} with main() |`);
+    if (rt) lines.push(`| Routes | ${rt.total} | ${(rt.controllers || []).length} controllers |`);
+    lines.push("");
+  }
+
+  if (mdl?.dbGroups) {
+    const groups = Object.entries(mdl.dbGroups).filter(([, v]) => v.length > 0);
+    if (groups.length > 0) {
+      lines.push("### Database Groups");
+      lines.push("");
+      lines.push("| connection | models |");
+      lines.push("| --- | --- |");
+      for (const [name, models] of groups) {
+        lines.push(`| ${name} | ${models.length} |`);
+      }
+      lines.push("");
+    }
+  }
+
+  const pkgPath2 = path.join(srcRoot, "package.json");
+  if (fs.existsSync(pkgPath2)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath2, "utf8"));
+      if (pkg.scripts && Object.keys(pkg.scripts).length > 0) {
+        lines.push("### Available Commands");
+        lines.push("");
+        lines.push("| command | script |");
+        lines.push("| --- | --- |");
+        for (const [name, script] of Object.entries(pkg.scripts)) {
+          lines.push(`| \`npm run ${name}\` | ${script.replace(/\|/g, "\\|")} |`);
+        }
+        lines.push("");
+      }
+    } catch (_) { /* ignore */ }
+  }
+
+  lines.push("<!-- PROJECT:END -->");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// AGENTS.md 更新
+// ---------------------------------------------------------------------------
+
+function updateProjectSection(filePath, projectSection) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`Error: ${filePath} not found. Run 'sdd-forge setup' first.`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const projectPattern = /<!-- PROJECT:START[^>]*-->[\s\S]*?<!-- PROJECT:END -->/;
+
+  let updated;
+  if (projectPattern.test(content)) {
+    updated = content.replace(projectPattern, projectSection);
+  } else {
+    const sddEndPattern = /<!-- SDD:END -->/;
+    if (sddEndPattern.test(content)) {
+      updated = content.replace(sddEndPattern, `<!-- SDD:END -->\n\n${projectSection}`);
+    } else {
+      updated = content.trimEnd() + "\n\n" + projectSection + "\n";
+    }
+  }
+
+  fs.writeFileSync(filePath, updated, "utf8");
+}
+
+function rewriteAgentsMd(filePath, sddSection, projectSection) {
+  const parts = [
+    sddSection.trim(),
+    "",
+    projectSection,
+    "",
+    "## Project Guidelines",
+    "",
+    "<!-- Add project-specific guidelines here -->",
+    "",
+  ];
+  fs.writeFileSync(filePath, parts.join("\n"), "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  const opts = parseArgs(args, {
+    flags: ["--force", "--template", "--dry-run"],
+    options: [],
+    defaults: { force: false, template: false, dryRun: false },
+  });
+
+  if (opts.help) {
+    console.log("Usage: sdd-forge agents [--force] [--template]");
+    console.log("");
+    console.log("  analysis.json から AGENTS.md を更新する。");
+    console.log("  デフォルトで AI エージェントを使用して PROJECT セクションを要約生成する。");
+    console.log("");
+    console.log("Options:");
+    console.log("  --force      AGENTS.md を全体書き直す（SDD + PROJECT + 空の Guidelines）");
+    console.log("  --template   AI を使わずテンプレートベースで生成する");
+    console.log("  --dry-run    ファイル書き込みせず生成内容を stdout に出力する");
+    process.exit(0);
+  }
+
+  const workRoot = repoRoot();
+  const srcRoot = sourceRoot();
+
+  // Load analysis.json
+  const analysisPath = path.join(workRoot, ".sdd-forge", "output", "analysis.json");
+  let analysis;
+  try {
+    analysis = loadJsonFile(analysisPath);
+  } catch (err) {
+    console.error(`Error: ${analysisPath} not found.`);
+    console.error("Run 'sdd-forge scan' first.");
+    process.exit(1);
+  }
+
+  // Load config.json
+  let config = {};
+  try {
+    config = loadJsonFile(path.join(workRoot, ".sdd-forge", "config.json"));
+  } catch (_) {
+    // config is optional for template mode
+  }
+
+  const lang = config.lang || config.output?.default || "en";
+
+  // Generate PROJECT section
+  let projectSection;
+
+  if (opts.template) {
+    projectSection = generateProjectSectionTemplate(analysis, config, srcRoot);
+    console.error("[agents] template mode: generating from analysis.json without AI");
+  } else {
+    // AI mode (default)
+    let agent;
+    try {
+      agent = loadAgentConfig(config);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+
+    console.error("[agents] generating PROJECT section with AI...");
+    const prompt = buildSummaryPrompt(analysis, config, srcRoot);
+
+    try {
+      const result = callAgent(agent, prompt, 180000);
+
+      // Extract PROJECT section from AI response
+      const projectMatch = result.match(/<!-- PROJECT:START[^>]*-->[\s\S]*?<!-- PROJECT:END -->/);
+      if (projectMatch) {
+        projectSection = projectMatch[0];
+      } else {
+        // AI didn't wrap in tags — wrap it
+        projectSection = [
+          "<!-- PROJECT:START — managed by sdd-forge. Do not edit manually. -->",
+          result,
+          "<!-- PROJECT:END -->",
+        ].join("\n");
+      }
+    } catch (err) {
+      console.error(`Error: AI agent call failed: ${err.message}`);
+      process.exit(1);
+    }
+
+    console.error("[agents] AI summary generated.");
+  }
+
+  // Update AGENTS.md
+  const agentsPath = path.join(srcRoot, "AGENTS.md");
+
+  if (opts.dryRun) {
+    console.error("[agents] DRY-RUN: would update " + agentsPath);
+    process.stdout.write(projectSection + "\n");
+    return;
+  }
+
+  if (opts.force) {
+    const sddSection = loadSddTemplate(lang);
+    if (!sddSection) {
+      console.error("Error: SDD template not found.");
+      process.exit(1);
+    }
+    rewriteAgentsMd(agentsPath, sddSection, projectSection);
+    console.log(`[agents] rewrote ${agentsPath}`);
+  } else {
+    updateProjectSection(agentsPath, projectSection);
+    console.log(`[agents] updated PROJECT section in ${agentsPath}`);
+  }
+}
+
+export { main };
+
+const isDirectRun = process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isDirectRun) {
+  main();
+}