Init

Language Requirements

• ALL generated documentation content (CLAUDE.md, AGENT.md, checklists) MUST be in English
• Documentation file names and task/report topic directories under /docs MUST use Chinese names, while standard taxonomy directory names stay in English
• User-facing responses and comments should follow user's preferred language
• All generated files must use UTF-8 encoding
• Output should be concise, clear, and actionable

init Skill

统一的跨技术栈项目初始化入口。dt:init 现在是主编排 skill：它只负责按顺序读取 references/ 下的协议、侦察仓库事实、再生成或升级项目级 AI 规则。详细规则已经拆到 reference 文件中，不要再依赖通读一个超长文件来记忆全部约束。

Trigger

/dt:init [optional focus] [--experiment [converge|sync]] [--dry-run]

When to Use

• 第一次接手一个陌生仓库
• 需要为项目补充或优化 CLAUDE.md
• 需要让 VS Code Copilot 直接读取项目级规则
• 需要输出可快速浏览的代码库 onboarding 摘要
• 项目曾经执行过 init，但需要把旧版规则文件升级到当前标准
• 项目进入 Claude Code 或 Codex 工作流，需要生成项目级 hook 来执行任务收尾规则审计
• 项目需要补齐 /docs 分类规则、报告归档规则和 scoped rules 约束
• 产品根目录包含多个自带 .git 的直接子项目，需要隔离子仓库并初始化或刷新根 Git 提交/推送策略
• 用户显式要求 --experiment converge 或 --experiment sync

Command Parameters

• 无参数：标准 init。做侦察、总结和规则文件生成或优化，不主动改业务架构；检测到多仓库产品根目录时，额外执行 git-topology.md 的根 Git 初始化、commit/可选 push
• [optional focus]：可选关注模块、技术栈或目录范围，但所有结论仍必须由真实代码验证
• --experiment converge：启用 experimental 架构收敛模式
• --experiment sync：启用 experimental 同步更新模式
• --experiment：只允许使用这个开关名，不接受其他别名
• --dry-run：只输出侦察结果、变更预览、风险、验证项和回滚点，不落盘、不移动文件、不改配置

Main Responsibility

dt:init 只负责这几件事：

1. 基于真实代码侦察仓库事实
2. 按 reference 协议建立 /docs、项目级规则文件和必要的 scoped rules
3. 通过 dt:install-project-hooks 在 Claude Code 与 Codex 项目里 bootstrap 项目级 final rule audit hook
4. 增量升级已有 CLAUDE.md、AGENT.md、Copilot 配置，不无脑覆盖
5. 生成 onboarding 摘要与最小验证结果
6. 在项目根目录初始化本地 .worktree/，并把后续 Git worktree 的统一存放规则写入项目级 AI 规则
7. 根据真实栈信号加载 capabilities/registry.json 中的初始化能力插件
8. 检测多仓库产品根目录，隔离直接子 Git 仓库，并按根 remote 实际状态完成本地 commit 或根 remote push

项目级 .ai/skills 多端同步、configured mirrors 和 sync-project-skills.sh 默认能力已经移除；init 不再生成或维护这些文件。

Required Outputs

本技能默认产出以下内容：

1. 会话内 onboarding 摘要
2. 项目根目录 CLAUDE.md
3. 项目根目录 AGENT.md
4. Copilot 可读取的项目级配置（AGENTS.md 或 .github/copilot-instructions.md 二选一）
5. 项目级 Claude/Codex final rule audit hook（由 dt:install-project-hooks 生成）：
   • Claude：.claude/settings.json、当前 OS 对应的 .claude/hooks/final-rule-audit.{ps1|sh}
   • Codex：.codex/hooks.json、当前 OS 对应的 .codex/hooks/final-rule-audit.{ps1|sh}
6. /docs 文档根目录及必要分类目录骨架
7. （仅当项目有真实关注点或明确隔离价值时）按主题拆分的 .ai/rules/<topic>.md 与 src/ / tests/ 等目录级隔离规则
8. 项目根目录本地 .worktree/ 及 .gitignore 中的 /.worktree/ 忽略项（--dry-run 时只预览）
9. 可选 checklist（仅用户明确要求时）
10. 条件能力产物（仅匹配 capability 时生成；具体产物由 capability 自身定义）
11. （仅检测到直接子 Git 仓库时）根 .ai/init-root.yml、受控 .gitignore block，以及根本地/远程 Git finalization

Mandatory Read Order

在开始生成任何文件前，必须按顺序读取这些 reference：

1. references/general-principles.md
2. references/recon-and-stack-detection.md
3. references/git-topology.md
4. references/docs-taxonomy.md
5. references/project-bootstrap.md
6. references/claude-hook-bootstrap.md
7. references/scoped-rules-and-enforcement.md
8. references/output-files.md
9. capabilities/registry.json

按条件追加读取：

• 传入 --experiment：再读取 references/experimental-mode.md
• 用户明确要求 checklist：再读取
  • references/checklist-templates/api.md
  • references/checklist-templates/dependencies.md
  • references/checklist-templates/modules.md

执行要求：

• 未读取必需 reference 前，不得开始生成 CLAUDE.md、AGENT.md、Copilot 配置或调用 hook 安装
• dt:init 负责编排顺序，reference 负责细节规则
• capability 注册表只负责发现与路由；命中的 capability SKILL.md 负责自身产物和验证，主 skill 不复制其细节
• 不要在主 skill 里再把 reference 全文复述一遍
• 如果 reference 与旧版项目规则冲突，按 reference + 真实代码做增量升级，不要直接跳过

Execution Workflow

Step 0. CodeGraph Auto-Init (run first)

在开始任何侦察或文件生成之前，必须先检查并初始化 CodeGraph：

• 检测本机是否安装了 codegraph CLI（执行 which codegraph 或 codegraph 可用性检查）
• 检测项目根目录下是否已存在 .codegraph/ 文件夹
• 当本机已安装 codegraph 且项目不存在 .codegraph/ 时，自动执行 codegraph init -i 初始化索引
• 如果 codegraph 未安装或 .codegraph/ 已存在，静默跳过
• 此步骤的执行结果应反映在 onboarding 摘要中（标明 CodeGraph 是否已初始化或跳过）

Step 1. Parse Mode

• 判断当前是标准模式还是 experimental 模式
• 若只写了 --experiment 但未指定 converge|sync，且无法从用户意图与仓库事实推断，必须先澄清
• 若带 --dry-run，所有落盘动作都只输出预览

Step 2. Read References

• 严格按 Mandatory Read Order 读取必需 reference
• 只在需要时再读取 conditional reference

Step 3. Reconnaissance

• 按 references/recon-and-stack-detection.md 做并行侦察
• 先扫构建文件、入口、目录快照、文档目录、测试结构、工具链配置
• 同时扫描直接子目录 .git、根 .git、当前分支、upstream 和 remote，识别是否为多仓库产品根目录
• 只基于真实文件和目录得出结论

Step 4. Stack Detection And Conventions

• 识别 Android、Flutter、Web/Node、Python、Java/JVM 或混合仓库
• 建立 single sources of truth
• 判断命名、测试、错误处理、异步风格和 git 约定

Step 4.5. Resolve Initialization Capabilities

• 运行 scripts/resolve-capabilities.ps1 -WorkspaceRoot <project-root> -AsJson，并用 Step 3/4 的真实证据复核结果
• 读取 capabilities/registry.json，确认 resolver 返回项与注册表一致
• 只读取并执行命中项的 entry；不得为未命中的栈生成规则、脚本或空目录
• 当前内置能力：后端 API-first 检索、Flutter 语义驱动自动化测试
• --dry-run 时只报告命中证据、预期产物和验证命令，不写 capability 产物
• capability 修改 public API、依赖、业务源码或 3+ 源码文件时，仍须遵守 Plan-First；初始化能力本身不扩大用户授权

Step 5. Docs Taxonomy

• 按 references/docs-taxonomy.md 建立 /docs 根目录和标准分类
• 应用语义优先目录映射
• 把审计 / 性能 / 评估 / 复盘类报告的主题目录规则写进后续生成文件

Step 6. Project Bootstrap

• 按 references/project-bootstrap.md 识别并增量升级项目级 AI 规则文件
• 不创建 .ai/skills/、.ai/exports/、.claude/skills/
• 不写入 configured mirrors，不安装 sync-project-skills.sh
• 按 references/claude-hook-bootstrap.md 了解项目 hook 安装委托规则；具体 hook 生成由 dt:install-project-hooks 负责

Step 6.5. Worktree Root Bootstrap

• 非 --dry-run 模式下，在项目根目录创建或复用 .worktree/，不得在仓库根目录直接创建平级 worktree
• 确保项目根 .gitignore 包含精确的根目录忽略项 /.worktree/；若 .gitignore 不存在则创建，保留所有既有内容
• 后续生成或升级的 CLAUDE.md、AGENT.md 和 Copilot 项目级配置必须明确：所有新 Git worktree 统一放在 <project-root>/.worktree/<worktree-name>，不得默认放到项目根目录平级位置或其他外部目录
• 只约束后续新建 worktree；不得自动移动或删除初始化前已存在于其他位置的 worktree
• --dry-run 模式只展示目录、忽略项和规则文件预期变更，不创建目录、不修改 .gitignore

Step 7. Scoped Rules And Enforcement

• 按 references/scoped-rules-and-enforcement.md 规划规则模块化与强制层
• 评估是否需要把规则按主题拆到 .ai/rules/<topic>.md，主控文件只保留红线 + 索引（SR-2）
• 评估是否需要在 src/ 与 tests/ 等真实目录边界生成目录级隔离规则，防止 Mock 渗透生产代码（SR-3）
• 检测项目已有的 Linter / 静态检查工具，优先增量补充依赖边界规则；不擅自引入新工具（SR-4）
• 准备把“接口 -> 确认 -> 业务 -> 测试”分步工作流写入后续规则文件（SR-5）
• 按 Step 3/4 侦察到的栈，生成对应的依赖注入隔离规则（SR-8）与集成测试反 Mock / 环境防呆规则（SR-9）
• SR-8 / SR-9 必须栈感知 + 条件生成：只写侦察到的栈那一套，侦察不到外部依赖就不写 DI，无测试栈就只建议；禁止跨栈套用写法
• 任何对 Linter / 构建配置的改动都先走 Plan-First 预览；带 --dry-run 时只输出预览

Step 8. Experimental Flow

• 仅在显式传入 --experiment 时执行
• 必须先读 references/experimental-mode.md
• 先给 dry-run 预览，再决定是否落盘
• 只在该 reference 允许的范围内做结构改动

Step 9. Generate Output Files

• 按 references/output-files.md 生成或增量升级：
  • CLAUDE.md
  • AGENT.md
  • Copilot 项目级配置
  • onboarding 摘要
  • 可选 checklist
• 同时落实 references/scoped-rules-and-enforcement.md 的产出：模块化规则索引、目录级隔离规则、Linter 强制说明、分步工作流段落
• 将已启用 capability 的短触发规则与细则路径写入项目级 AI 规则；详细协议保留在 capability 生成的 scoped rule 中
• 检测到直接子 Git 仓库时，同时按 references/git-topology.md 把真实根 Git policy 写入规则文件，并生成或更新 .ai/init-root.yml 与根 .gitignore 受控 block

Step 9.5. Install Project Hooks

• 读取并执行 skills/install-project-hooks/SKILL.md
• 默认安装 Claude 与 Codex 项目级 hooks；如用户明确只启用某一工具，则透传对应参数
• 当前默认只生成 final rule audit hook：
  • Claude：.claude/settings.json、当前 OS 对应的 .claude/hooks/final-rule-audit.{ps1|sh}
  • Codex：.codex/hooks.json、当前 OS 对应的 .codex/hooks/final-rule-audit.{ps1|sh}
• Windows 必须生成并注册 final-rule-audit.ps1（pwsh -NoProfile -ExecutionPolicy Bypass -File ...），且脚本提示输出到 stdout；macOS / Linux / WSL 才生成并注册 final-rule-audit.sh
• 带 --dry-run 时只输出 hook 文件和配置预览，不写盘
• 不生成 sync-project-skills.sh，不注册 PostToolUse

Step 10. Minimal Verification

• 优先运行与改动范围最小相关的 test / lint / typecheck / build / smoke
• 如果没有可执行验证命令，必须明确写 not verified
• 文档-only 变更至少检查路径、目录规则和规则文件一致性
• 非 --dry-run 模式还必须确认项目根 .worktree/ 已存在、/.worktree/ 已被根 .gitignore 忽略，且三类项目级 AI 规则中的 worktree 路径约束一致

Step 11. Code Review Generated Rules

在所有文件生成和验证完成后，对产出的规则文件做一次完整性审查：

• 检查 CLAUDE.md 是否完整覆盖了 references/output-files.md 要求的 21 项必备内容（其中 SR、Worktree 与多仓库 Git 条件项按本项目事实裁剪）
• 检查 AGENT.md 是否完整覆盖了 10 项必备内容
• 检查 Copilot 项目级配置是否涵盖精简版 GP-2 至 GP-9
• 交叉检查各文件之间的一致性（单一事实来源声明、hook 安装规则、文档分类规则是否在各文件中一致）
• 检查 capability 选择有真实证据、未误装到不适用项目，且主规则只保留短触发语句与细则索引
• 检查是否有遗漏的规则类别：安全、测试、编码风格、Git 工作流、性能、Agent 编排、Hook 系统
• 检查 .worktree/ 初始化、.gitignore 忽略项和三类项目级 AI 规则中的 worktree 统一路径约束是否一致
• 对照 references/general-principles.md 的 GP-1 至 GP-10，逐项确认关键约束已写入对应文件
• 对照 references/scoped-rules-and-enforcement.md 的 SR-1 至 SR-9，确认模块化规则索引、目录级隔离、Linter 强制说明、分步工作流、依赖注入隔离、集成测试与环境防呆已按本项目栈裁剪写入对应文件；确认没有跨栈套用错误写法
• 发现缺失或冲突时，补充或修正对应文件
• 输出一份简短的 review 结论到会话中：列出已覆盖的规则类别、发现的 gap 及是否已修复

Step 11.5. Project Hook Verification

在所有文件生成、验证和规则文件 review 完成后，检查本次生成或升级的项目级 hook 是否完整：

• Claude 项目 hook 必须包含 .claude/settings.json 与当前 OS 对应的 .claude/hooks/final-rule-audit.{ps1|sh}
• Codex 项目 hook 必须包含 .codex/hooks.json 与当前 OS 对应的 .codex/hooks/final-rule-audit.{ps1|sh}
• final-rule-audit.{ps1|sh} 的职责是提醒/阻断 AI 在最终回复前重新读取适用规则、审计已修改文件、运行最小验证，并在发现违反规则时先修复再回复
• hook 脚本不得自动改业务代码；自动修复必须由 AI agent 在 hook 反馈后显式执行，避免无上下文脚本破坏代码
• 不得生成或注册 sync-project-skills.sh / PostToolUse mirror refresh hook
• 若当前工具不支持某个 hook 事件或无法验证事件语义，必须保留脚本与配置预览，并在 onboarding 摘要中写明 not verified

Step 12. Add .codegraph to .gitignore

在所有文件生成和 review 完成后，确保 .codegraph/ 已加入项目的 .gitignore：

• 检查项目根目录是否存在 .gitignore 文件，如果不存在则创建
• 检查 .gitignore 中是否已有 .codegraph/ 条目
• 如果没有，在 .gitignore 末尾追加 .codegraph/（前面保留一个空行作为分隔）
• 如果 Step 0 中未初始化 CodeGraph（未安装或已存在），此步骤仍要执行 — 确保仓库在任何情况下都不会将 codegraph 索引目录提交到版本控制

Step 13. Finalize Multi-Repository Root Git

仅在 Step 3 检测到直接子 Git 仓库时执行 references/git-topology.md：

• 根没有自己的 .git 时初始化根本地 Git
• 根无可用 remote 时只创建根本地 commit
• 根 remote 可唯一确定时，额外完整读取 skills/push/references/git-transport.md，完成根 upstream 同步、commit 和 push
• 初始化阶段不得 commit 或 push 子仓库；子仓库只写入根 .gitignore 并记录到 .ai/init-root.yml
• --dry-run 只输出拓扑、ignore、commit 和 push 预览，不执行任何 Git 写操作

Minimum Rules Generated Files Must Carry

生成的 CLAUDE.md、AGENT.md、Copilot 项目级配置，至少必须体现这些约束：

• 如果项目存在 Claude/Codex final rule audit hook，则任务收尾前必须重新读取项目规则、审计已修改文件、发现违反规则时先修改再回复
• 任务聚合文档使用 docs/plan/<中文任务名>/
• 审计 / 性能 / 评估 / 复盘类报告使用 docs/reports/<中文报告主题>/
• /docs 下文档文件名、任务目录名和报告主题目录名必须使用中文；标准分类目录名保持英文
• CHANGELOG.md 这类持续更新日志可保留在 docs/reports/ 根下
• 项目根目录必须创建并保留本地 .worktree/；所有后续 Git worktree 必须放在 <project-root>/.worktree/<worktree-name>，且 /.worktree/ 必须加入项目根 .gitignore
• 需求不清或跨 3+ 源码文件时先计划
• 所有结论必须来自真实代码、配置或目录扫描
• 规则按主题模块化，主控文件只保留红线 + 索引，细则按需加载
• 生产代码目录禁止 Mock，测试目录允许 Mock，按目录边界做物理隔离
• 哪些依赖 / import 边界由 Linter / 静态检查强制（仅记录项目已采用或用户要求的方案）
• 后续 AI coding 遵循接口 -> 确认 -> 业务 -> 测试 的分步工作流
• 外部依赖经接口 / 注入隔离，业务函数内禁止直接实例化或发真实请求（按本项目栈裁剪，侦察不到外部依赖则不写）
• 单元测试外补集成测试（禁用 Mock）与负面边界测试，Mock 用环境判断包裹防呆（按本项目栈选写法，禁止跨栈套用）
• 若检测到后端接口定义：任何业务能力、数据访问或新增接口需求先搜索并验证现有后端 API
• 若检测到 Flutter App：Flutter 内部 UI 自动化使用 integration_test 与稳定 Key/Semantics，AI 探索不作为最终 PASS/FAIL
• 多仓库根目录必须隔离直接子 Git 仓库；根无 remote 时本地提交，根有可唯一确定 remote 时在全部子仓库成功后提交并推送根仓库

Best Practices

1. 先并行侦察，再定向读取，避免一上来通读整个仓库
2. 优先增强已有规则文件，不要无脑覆盖
3. 能复用 reference 里的固定协议时，不要在主 skill 里重新发明步骤
4. 能用标准模式解决时，不要滥用 --experiment
5. 对未知项明确写 unknown，优先正确而不是看起来完整

Anti-Patterns To Avoid

• 未读取 reference 就开始生成规则文件
• 看到框架关键词就直接套模板，不验证真实文件
• 未传入 --experiment 却自动进入 experimental 模式
• 把旧版规则文件升级误解为主动重构项目源码
• 把审计 / 性能 / 评估 / 复盘类报告直接平铺到 docs/reports/
• 重新引入 .ai/skills 多端同步、configured mirrors、sync-project-skills.sh 或 PostToolUse mirror refresh hook
• 未完成最小验证就宣称已通过
• 把所有规则塞进单个超长 CLAUDE.md，不做模块化与索引
• 擅自引入项目尚未采用的新 Linter / IDE 规则机制，而非增量补充已有工具
• 在每个子目录无脑塞规则文件，或为不存在的关注点创建空 .ai/rules/<topic>.md
• 跨栈套用强制写法（如给 Flutter 项目写 process.env、给 React 写 kReleaseMode、给纯 UI 库强加 DI）
• 给侦察不到外部依赖的项目强加依赖注入规则，或给无测试栈的项目强制集成测试
• 检测到子 Git 仓库后仍把子项目内容加入 root index，或无视真实 root remote 把 policy 永久写死为 commit_only_no_push