init-project
目的
從可攜帶的捆綁包中一次性引導新專案的代理文件系統。初始化後，專案會使用已部署的標準（doc-organization.md §8.3 決策樹 + 可攜帶的元標準）進行自我維護。init 在每個專案中僅執行一次；update 可在之後針對該專案重新執行，以從捆綁包中拉取更新的可攜帶檔案（三方安全合併 — 絕不覆蓋未提升的本機編輯）。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 模式的引擎（三方捆綁包→實際檔案合併）；scripts/sync-version.mjs — 版本單一來源同步
模式
| 呼叫方式 | 執行位置 | 動作 |
|---|
/init-project | 新專案 | 部署捆綁包（如下工作流程） |
/init-project check | 主儲存庫 | 根據對應表進行 sha256 比較捆綁包 ↔ 實際檔案 → 報告差異 |
/init-project promote | 主儲存庫 | 針對每個對應的檔案，將實際檔案複製到捆綁包，並更新 VERSION |
/init-project update | 已初始化的專案 | 拉取更新的可攜帶檔案從捆綁包到實際檔案，三方安全合併（清單 ↔ 實際檔案 ↔ 捆綁包）；跳過衝突（如下工作流程） |
工作流程（init — 新專案）
- 掃描專案：根據
## 模組矩陣 信號欄位偵測堆疊和可選模組。輸出：建議的模組集合 + 發現的插槽值。
- 訪談：確認建議的模組集合；詢問無法掃描的插槽（使用的開發連接埠、範圍所有權、文件語言）。無法回答的插槽 → 留下 TODO 標記，絕不憑空發明值；模組不確定 → 跳過它。
- 逐字複製
portable/：portable/rules/* → .claude/rules/；portable/agent-guide/* → docs/agent-guide/general/；portable/skills/* → .claude/skills/；portable/agents/* → .claude/agents/。
- 渲染模板：利用訪談中的
{{slots}} 填入 CLAUDE.md、docs/agent-guide/index.md、docs/index.md；缺少的插槽 → 保留 TODO 標記。
- 產生可選規則：對於每個確認的可選模組，根據
rule-writing-standards 在 docs/agent-guide/general/ 中寫入一個專案適配的規則，並在相同步驟中將其觸發行附加到 CLAUDE.md — 無硬編碼模板。
- 寫入清單
.claude/init-manifest.json：{ version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] }（出處；files[] 由 update 讀取以進行三方漂移偵測 — 保持 sha256 準確；templates[] 記錄每個渲染檔案所基於的 .tpl 的 sha，path = 相對於 templates/ 的模板路徑，例如 CLAUDE.md.tpl，由 update 用於在模板自部署以來發生變更時發出警告）。
- 驗證：每個已部署的檔案位於正確的層級；每個規則/代理指南檔案帶有
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 是已初始化的專案根目錄，預設為目前目錄。
- 試執行：
node <plugin>/scripts/update.mjs --project <project-root> → 檢視 ADD / UPDATE / CONFLICT 計畫和版本差異。
- 首先解決每個 CONFLICT — 衝突 = 自部署以來在本機編輯過的可攜帶檔案。將其提升到上游（以便改進進入捆綁包），或在檢視後手動覆蓋。絕不盲目覆蓋。
- 套用：
node <plugin>/scripts/update.mjs --apply --project <project-root> → 寫入 ADD + UPDATE，跳過衝突，重新整理清單 version + files[].sha256。
- 僅新增和原地變更 —
update 絕不刪除：從捆綁包中移除的檔案會保留在專案中，而在本機刪除的檔案會被重新新增。如有需要，請手動清理這些檔案。
templates/*（CLAUDE.md, index.md — 渲染的表現型）絕不會被覆寫：它們的插槽持有專案特定的值。update 僅在 .tpl 自部署以來發生變更時發出警告（sha vs manifest.templates[]）；請手動重新渲染（比較 .tpl 與實際檔案，重新套用結構性變更，保留插槽值）或重新執行 /init-project。該警告會持續存在，直到下次 init 重新記錄模板 sha。
- 退出碼：0 = 已是最新或已乾淨套用；1 = 仍有衝突；2 = 設定錯誤（無清單 → 專案未由此外掛初始化）。
模組矩陣
| 模組 | 包含 | 部署時機 | 掃描信號（範例，非詳盡） |
|---|
| 核心 | portable/*（所有 4 組）+ 3 個模板 | 始終 | — |
| 執行時期 | agent-guide/general/local-runtime.md + CLAUDE.md 觸發（技能根據掃描寫入，步驟 5） | 專案自行執行開發伺服器 | package.json dev/start 腳本、launchSettings.json、vite/next/dotnet/django/cargo 配置 |
| 端到端 | 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 進入捆綁包。
獨立性規則
- 技能在每個專案中執行一次；已部署的檔案不引用此主儲存庫的任何檔案；專案規則絕不引用此技能。
- 除了上述的捆綁包↔實際檔案對應表外，完全獨立，該對應表僅在主儲存庫中用於檢查/提升。
範例
✅ 掃描發現 package.json 帶有 "dev" 腳本 → 建議執行時期模組 → 步驟 5 寫入
general/local-runtime.md + 將 "self-run dev server → MUST Read ..." 附加到 CLAUDE.md
❌ 在沒有掃描信號且未經訪談確認的情況下部署執行時期模組（猜測的模組）
✅ /init-project check → "MISMATCH: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
→ 先修正實際檔案 → /init-project promote
❌ 直接編輯 portable/* 然後初始化新專案（捆綁包與實際檔案無聲地分歧）
參考檔案
- 捆綁包：
./portable/**
- 模板：
./templates/**
- 版本：
./VERSION