tuannv0069/claude-doc-genome

init-project

目的

ポータブルバンドルから新しいプロジェクトのエージェントドキュメントシステムをワンショットでブートストラップします。初期化後、プロジェクトはデプロイされた標準（doc-organization.md §8.3 の決定木 + ポータブルメタ標準）を使用して自己維持します。init はプロジェクトごとに1回実行されます。update は後でそのプロジェクトで再実行し、バンドルから新しいポータブルファイルを取得できます（3ウェイセーフマージ — 昇格されていないローカル編集を上書きすることはありません）。check/promote はバンドル自体を維持し、このマスターリポジトリでのみ実行されます。

依存関係

• ./portable/rules/ — 7つのポータブルルール（常時読み込み + パススコープ）
• ./portable/agent-guide/ — five-why.md、markdown.md、mermaid.md、orchestration-policy.md、worktree.md（docs/agent-guide/general/ にデプロイ）
• ./portable/skills/ — skill-designer/、skill-writer/、document-writer/（ツリー全体）
• ./portable/agents/ — skill-writer-auditor.md
• ./templates/ — CLAUDE.md.tpl、agent-guide/index.md.tpl、docs/index.md.tpl
• ./VERSION — バンドルバージョン。プロモートのたびに更新
• scripts/update.mjs（リポジトリルート） — update モードのエンジン（3ウェイバンドル→ライブマージ）。scripts/sync-version.mjs — バージョンの単一ソース同期

モード

呼び出し	実行場所	アクション
/init-project	新しいプロジェクト	バンドルをデプロイ（以下のワークフロー）
/init-project check	マスターリポジトリ	マップに従ってバンドル↔ライブをsha256比較し、ドリフトを報告
/init-project promote	マスターリポジトリ	マップされたすべてのファイルについてライブ→バンドルをコピーし、VERSION を更新
/init-project update	初期化済みプロジェクト	新しいポータブルファイルをバンドル→ライブにプル、3ウェイセーフ（マニフェスト↔ライブ↔バンドル）。競合をスキップ（以下のワークフロー）

ワークフロー（init — 新しいプロジェクト）

1. プロジェクトをスキャン：スタックとオプショナルモジュールを ## モジュールマトリックス のシグナル列に従って検出。出力：提案されたモジュールセットと発見されたスロット値。
2. インタビュー：提案されたモジュールセットを確認。スキャンできないスロット（使用中の開発ポート、スコープの所有者、ドキュメント言語）を質問。答えられないスロット → TODO マーカーを残し、値を発明しない。モジュールが不明確 → スキップ。
3. portable/ をそのままコピー：portable/rules/* → .claude/rules/；portable/agent-guide/* → docs/agent-guide/general/；portable/skills/* → .claude/skills/；portable/agents/* → .claude/agents/。
4. テンプレートをレンダリング：インタビューからの {{slots}} を CLAUDE.md、docs/agent-guide/index.md、docs/index.md に埋め込む。欠落したスロット → TODO マーカーを維持。
5. オプショナルルールを生成：確認されたオプショナルモジュールごとに、rule-writing-standards に従ってプロジェクトに適合したルールを docs/agent-guide/general/ に書き込み、そのトリガー行を同じステップで CLAUDE.md に追加（ハードコードされたテンプレートは使用しない）。
6. マニフェスト .claude/init-manifest.json を書き込み：{ version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] }（来歴。files[] は update で3ウェイドリフト検出のために読み取られる — sha256 を正確に保つ。templates[] は各レンダリングファイルが構築された元の .tpl sha を記録 — path は templates/ からの相対テンプレートパス（例：CLAUDE.md.tpl）、update でデプロイ以降にテンプレートが変更された場合に WARN を出力するために使用）。
7. 検証：デプロイされたすべてのファイルが正しい階層にあること。すべてのルール/エージェントガイドファイルに scope: フロントマターがあること。CLAUDE.md がトークン予算内であること。動作に影響するすべてのオンデマンドファイルにトリガー行またはルーターエントリがあること（到達可能性、ファイル→トリガー）。CLAUDE.md のすべての MUST Read トリガーがデプロイされたファイルに解決されること（到達可能性、トリガー→ファイル — デッドトリガーなし）。意図的な TODO マーカーを除き、未レンダリングの {{slot}} が残っていないこと。完了 = チェックリスト合格 + マニフェスト書き込み済み。

バンドル↔ライブマップ（check / promote — マスターリポジトリ；update — 初期化済みプロジェクト）

バンドルパス	ライブパス
portable/rules/*	.claude/rules/*
portable/agent-guide/*	docs/agent-guide/general/*
portable/skills/*	.claude/skills/*
portable/agents/*	.claude/agents/*

• check：各ペアを sha256 比較 → 不一致をリスト表示。デフォルトの更新方向はライブ→バンドル（promote）。まずライブを修正し、その後 promote。
• promote：マップされたすべてのファイルについてライブ→バンドルをコピーし、node scripts/sync-version.mjs set <x.y.z> でバージョンを更新（標準 VERSION を書き込み、.claude-plugin/* と README バッジにも反映）。

ワークフロー（update — 初期化済みプロジェクト）

方向 バンドル→ライブ（promote の逆）。影響を受けるのはそのままコピーされたポータブルセットのみ。レンダリングされた表現型（CLAUDE.md、index.md、プロジェクト作成ガイド）は対象外。update.mjs はインストールされたプラグイン内のパスで呼び出します（自身の場所からバンドルを特定します）。--project は初期化されたプロジェクトルートで、デフォルトはカレントディレクトリです。

1. ドライラン：node <plugin>/scripts/update.mjs --project <project-root> → ADD / UPDATE / CONFLICT 計画とバージョン差分を確認。
2. 最初にすべての CONFLICT を解決 — 競合 = デプロイ以降にローカル編集されたポータブルファイル。上流にプロモートする（改善がバンドルに入るようにする）か、レビュー後に手動で上書きします。決して盲目的に上書きしないでください。
3. 適用：node <plugin>/scripts/update.mjs --apply --project <project-root> → ADD + UPDATE を書き込み、競合をスキップし、マニフェストの version と files[].sha256 を更新。
4. 追加とインプレースのみ — update は決して削除しません：バンドルから削除されたファイルはプロジェクトに残り、ローカルで削除されたファイルは再追加されます。必要に応じて手動で削除してください。
   • templates/*（CLAUDE.md、index.md — レンダリングされた表現型）は決して上書きされません：それらのスロットはプロジェクト固有の値を保持します。update はデプロイ以降に .tpl が変更された場合にのみ WARN を出力します（sha と manifest.templates[] の比較）。手動で再レンダリング（.tpl とライブを差分、構造変更を再適用、スロット値を保持）するか、/init-project を再実行します。WARN は次の init でテンプレート sha が再記録されるまで続きます。
5. 終了コード：0 = 最新状態、またはクリーンに適用。1 = 競合が残っている。2 = セットアップエラー（マニフェストなし → このプラグインでプロジェクトが初期化されていない）。

モジュールマトリックス

モジュール	含まれるもの	デプロイ条件	スキャンシグナル（例、網羅的ではない）
core	portable/*（全4グループ）+ 3テンプレート	常時	—
runtime	agent-guide/general/local-runtime.md + CLAUDE.md トリガー（スキルがステップ5のスキャンに基づいて書き込み）	プロジェクトが開発サーバーを自己実行する	package.json の dev/start スクリプト、launchSettings.json、vite/next/dotnet/django/cargo 設定
e2e	agent-guide/general/<tool>.md（検出されたツールにちなんで命名）+ CLAUDE.md トリガー（ステップ5）	プロジェクトに E2E ブラウザテストがある	playwright/cypress/selenium の依存関係、e2e/ フォルダ、E2E 設定

• オプショナルモジュールは、スキャンが確認した場合、またはユーザーがインタビューで確認した場合にのみデプロイ。不明確 → スキップ。
• Git：最小限のガードレール（リクエストがあった場合のみコミット、プッシュはしない）が CLAUDE.md.tpl に含まれています。詳細なポリシーは scope: project — プロジェクトは必要に応じて docs/agent-guide/general/git.md を書き込み、そのトリガー行を同じコミットで追加します（到達可能性 — 存在しないファイルを指すトリガーは決してありません）。
• スキップされたモジュールが後で必要になった場合 → プロジェクトはデプロイされた標準に従ってルールを自身で作成します。新しいモジュールがバンドルに入るのは、実際のプロジェクトでパターンが実戦テストされた後の promote によってのみです。

独立性ルール

• スキルはプロジェクトごとに1回実行されます。デプロイされたファイルはこのマスターリポジトリのファイルを参照しません。プロジェクトルールは決してこのスキルに名前を付けません。
• 上記のバンドル↔ライブマップを除き、自己完結型。このマップは check/promote のためにマスターリポジトリでのみ実行されます。

例

✅ スキャンで "dev" スクリプトを含む package.json を発見 → runtime モジュールを提案 → ステップ5で
   general/local-runtime.md を作成し、"自己実行開発サーバー → MUST Read ..." を CLAUDE.md に追加
❌ スキャンシグナルもインタビュー確認もなく runtime モジュールをデプロイ（推測されたモジュール）

✅ /init-project check → "MISMATCH: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
   → まずライブを修正 → /init-project promote
❌ portable/* を直接編集してから新しいプロジェクトで init を実行（バンドルがライブから密かに乖離する）

参照ファイル

• バンドル：./portable/**
• テンプレート：./templates/**
• バージョン：./VERSION