init-project
目的
一键从便携捆绑包为新项目搭建智能体文档系统。初始化后，项目将通过已部署的标准（doc-organization.md §8.3 决策树 + 便携元标准）实现自我维护。init 模式每个项目仅运行一次；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 — 捆绑包版本，每次 promote 时递增scripts/update.mjs（仓库根目录）— 用于 update 模式的引擎（3 路捆绑包→在线合并）；scripts/sync-version.mjs — 版本单一来源同步
模式
| 调用方式 | 执行位置 | 操作 |
|---|
/init-project | 新项目 | 部署捆绑包（如下工作流） |
/init-project check | 主仓库 | 按 §map 对捆绑包↔在线文件进行 sha256 比较 → 报告差异 |
/init-project promote | 主仓库 | 将每个映射文件的在线版本复制到捆绑包，递增 VERSION |
/init-project update | 已初始化的项目 | 拉取更新的便携文件捆绑包→在线，3 路安全（清单↔在线↔捆绑包）；跳过冲突（如下工作流） |
工作流（init — 新项目）
- 扫描项目：检测技术栈及按
## module matrix 信号列的可选模块。输出：提议的模块集 + 发现的槽值。
- 访谈：确认提议的模块集；询问不可扫描的槽（开发端口使用情况、所有权范围、文档语言）。无法回答的槽 → 保留 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 读取用于 3 路差异检测——保持 sha256 准确；templates[] 记录每个渲染文件所依据的 .tpl sha——path 是相对于 templates/ 的模板路径，例如 CLAUDE.md.tpl，在 update 中用于在部署后模板发生更改时发出 WARN 警告）。
- 验证：每个已部署的文件位于正确的层级；每个规则/智能体指南文件带有
scope: 前置元数据；CLAUDE.md 在 token 预算内；每个影响行为、按需访问的文件都有触发行或路由条目（可达性，文件→触发）；每个 CLAUDE.md 中的 MUST Read 触发器都对应一个已部署的文件（可达性，触发→文件——无死触发器）；没有未渲染的 {{slot}} 残留（有意保留的 TODO 标记除外）。完成条件 = 检查清单通过 + 清单已写入。
捆绑包↔在线映射（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 发生更改时发出 WARN 警告（sha 对比 manifest.templates[]）；手动重新渲染（比较 .tpl 与在线版本，重新应用结构性更改，保留槽值）或重新运行 /init-project。该 WARN 警告会持续存在，直到下次 init 重新记录模板 sha。
- 退出码：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 进入捆绑包。
独立性规则
- 技能每个项目仅运行一次；部署的文件不引用此主仓库的任何文件；项目规则从不提及此技能名称。
- 自包含，但上述捆绑包↔在线映射除外，该映射仅在主仓库的 check/promote 模式中执行。
示例
✅ 扫描发现 package.json 中有 "dev" 脚本 → 提议 runtime 模块 → 步骤 5 编写
general/local-runtime.md + 将 "self-run dev server → MUST Read ..." 追加到 CLAUDE.md
❌ 在没有扫描信号且未在访谈中确认的情况下部署 runtime 模块（猜测的模块）
✅ /init-project check → "MISMATCH: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
→ 先修复在线文件 → /init-project promote
❌ 直接编辑 portable/* 然后初始化新项目（捆绑包与在线文件悄悄产生分歧）
参考文件
- 捆绑包：
./portable/**
- 模板：
./templates/**
- 版本：
./VERSION