sdsrss/onboard/onboard

/onboard — Legacy Project Onboarding Protocol (v3.2.0)

参数：$ARGUMENTS

本包是 Skill 形式发布（.claude/skills/onboard/）。

包含预制的 4 个 hook 脚本作为 supporting files：

- hooks/guard-bash.sh — PreToolUse on Bash，拦截危险命令

- hooks/guard-edit.sh — PreToolUse on Edit|Write|MultiEdit，拦截禁区编辑

- hooks/post-edit-check.sh — PostToolUse on Edit|Write|MultiEdit，记录触及文件 + 轻量检查

- hooks/stop-verify.sh — Stop hook，按 mode 跑增量验证

Phase 7 不再动态生成脚本，而是直接在 .claude/settings.json 中引用 ${CLAUDE_PROJECT_DIR}/.claude/skills/onboard/hooks/<name>.sh。

兼容 Command 形式：把 SKILL.md 重命名为 .claude/commands/onboard.md，Phase 7 改回动态生成脚本到 .claude/hooks/。

关于 `disable-model-invocation: true`

防止 Claude 自动触发。已知 Skill 形式有兼容性 bug，若异常移除该字段或改用 Command 形式。

关于 `allowed-tools`

故意限制为只读工具。Bash/Write/Edit 走正文授权流程。会话开始时若希望连续执行，请在首个权限弹窗选择"允许本会话"；否则保持逐次确认。两种节奏都安全。

0. 总则（贯穿全流程）

文件四分类

• PROJECT：仓库已有内容。默认不得修改；仅当 Phase 2 plan 列入 touches 并经授权后可改。
• RUNTIME：本命令运行期状态与日志：.claude/onboarding-state.json、.claude/onboarding-logs/、.claude/tmp/。
• OUTPUT：本流程新增/维护的 Claude 产物：CLAUDE.md、.claude/settings.json、.claude/hooks/*、.gitignore 修订等。
• LOCAL-SIDE-EFFECT：不入仓但改变本机环境的写入目标：.git/hooks/*、.git/info/exclude、专用 onboarding 分支。不参与 touch_budget。

工作区"干净"仅针对 PROJECT。

Iron Laws（19 条，与 v2.3 同；Iron Law 3 / 14 措辞精化）

1. Read-before-write：未读取现状不得写入；现状报告未生成不得进入 Phase 1.5/2。
2. No silent overwrite：覆盖任何已存在配置文件前必须 diff + 用户确认。
3. Respect existing stack(s)：同一语言栈内禁止引入冲突工具（如 Node 内同时 ESLint + JSHint）。允许多语言项目并存多套工具栈——按栈分别应用。
4. Idempotent：可重复执行；已完成阶段须基于状态文件跳过或验证而非重做。
5. Verifiable：每个阶段必须有可执行验证步骤，失败不得标记为完成。
6. Stateful：所有阶段决策、产出、验证结果写入状态文件。
7. No auto-install：任何安装/升级动作必须先列清单 + 显式授权。凡 installs != []，对应 lockfile 自动追加到该 item 的 touches。（v2.7 注释）：Phase 2.5 引入的 batch AUTH（approve dev-tools-all）满足"显式授权"语义——用户看过清单后给出的一次性授权 = N 次单批授权之和，颗粒度变粗但约束未弱化。绝不允许"只要是 dev-only 就跳过 AUTH"的无差别豁免。
8. No business logic changes：onboarding 不得修改业务代码；唯一例外是 Phase 5 中用户批准的最小 smoke test。
9. No dependency upgrades：不得升级已有依赖版本；只允许新增经授权的开发依赖。
10. Prefer existing task runner：若项目已有 Makefile / justfile / package scripts，不新增平行入口；新增 script 前必须先做任务运行器健康检查。
11. Cross-platform awareness：hook 脚本默认 POSIX shell；Windows-first 项目必须提示兼容性风险并给替代或 defer。
12. CI alignment：本地 lint/test/typecheck 命令必须优先复用 CI 中已有命令。
13. Touch budget：实际改动文件集合若超出 Phase 2 计划中 touches 并集（含自动追加的 lockfile），立即中止并重新进入 Phase 2。local_side_effects 不计入。
14. No file-level reset on PROJECT：禁止对 PROJECT 文件执行 git reset --hard / git checkout -- <file> / git restore <file>。`git checkout -b <new-branch>`（创建新分支）不在此限——配合 --isolate-branch 模式使用。测试改动一律走 .claude/tmp/。
15. Exit code or JSON, never both：hook 脚本必须明确选择 exit 0 + stdout JSON 或 exit 2 + stderr；混用时 JSON 被忽略。
16. Forbidden zones are global：Phase 1 探测出的禁区是 candidates；只有 Phase 1.5 用户确认的 confirmed forbidden zones 才进入全流程消费——CLAUDE.md / lint ignore / hook env / guard-edit 必须保持一致。
17. New-check first failure is deferred, not blocking：Phase 4 首次引入的检查若首次跑失败，标 deferred: pre_existing_violations，不阻塞。
18. Mutex group authorization：同一 mutex_group 最多批准一个 plan item；Phase 2 即刻拒绝冲突。
19. warn-only must exit 0：标 warn-only 的检查必须输出 warning 但 exit 0，绝不返回非零退出码导致推送阻断。

参数解析

• --local-only（v2.6 新增，默认模式）：local 模式。所有 OUTPUT 文件走 Claude Code 原生 .local.* 约定 + .git/info/exclude，完全不入仓，团队成员 pull 后看不到任何 onboard 痕迹。详见下文「Mode model」章节。
• --share（v2.6 新增，opt-in）：team-share 模式（v2.5 及之前的默认行为）。OUTPUT 文件入仓，通过 .gitignore 管控 RUNTIME。需要团队对 AI 工具有共识。
• --dry-run：只输出"将要做什么"，不写 OUTPUT 文件。RUNTIME 正常创建/更新。
• --phase=<n>：只跑指定阶段（0, 0.5, 1, 1.5, 2, 3-8）。
• --resume：从上次中断处继续（同版本状态文件）。
• --update（v2.4 新增）：升级已完成的旧版 onboarding 到当前 spec。触发 Phase 0.5 Migration，继承旧决策、只跑差异阶段。
• --strict：任何验证失败立即中止整个流程。
• --isolate-branch（v2.4 新增）：在专用 git 分支 chore/onboarding-<timestamp> 上执行写入阶段。失败/不满意切回原分支即可整体回滚。仅在 `--share` 模式下有意义；local-only 模式文件均不入仓，分支隔离无收益（Phase 0 检测到 --local-only --isolate-branch 组合会发出 warn，但不阻断）。
• --doctor（v2.5 新增）：诊断模式。不跑任何 Phase，不写 PROJECT/OUTPUT，仅做健康检查 + RUNTIME log。详见下文「Doctor Mode」章节。
• --uninstall[=skill|all]（v2.8 新增；v2.11 参数化）：卸载模式。=skill 只卸 user-global skill 包 + plugin cache + mirror，保留项目侧所有 onboard 写入（hook 脚本、settings 引用、CLAUDE.md 内容）；=all（裸 --uninstall 等价，向后兼容 v2.8+）卸 user-global + 项目侧全部 onboard 痕迹。详见下文「Uninstall Mode」章节。
• --allow-large-claude-md（v2.7 新增）：覆盖 CLAUDE.md token 硬上限 5000。仅在项目实测确需超长 CLAUDE.md 时使用；触发 Phase 3 hard AUTH 并标 phase_3.token_budget_override: true。
• --verbose-plan（v3.1 新增）：Phase 2 plan 卡片 + Phase 2.5 install plan 默认 Top-N 折叠展示（"don't overwhelm"原则）；本 flag 展示全部项。折叠时显式提示 +N more (use --verbose-plan to show all)，用户不打这个 flag 也能看见有几项被折叠。

--resume、--update、--doctor、--uninstall 四者互斥。--local-only 与 --share 互斥（默认 --local-only，显式给 --share 才入仓）。--verbose-plan 与其他 flag 全部正交。

阶段卡片输出契约

─── Phase <n> · <name> ───
status:   done | skipped | failed | dry-run | blocked | deferred | verification_skipped | migrated
mode:     local-only | share
elapsed:  <耗时，例：1m23s>
actions:  <逐条做了什么>
outputs:  <OUTPUT 文件路径>
local_side_effects: <LOCAL-SIDE-EFFECT 路径>
verify:   <验证命令及结果摘要>
next:     <下一阶段或建议>
tip:      <可选 - actionable 一次性提示给用户；省略则不输出此行>

Mode model（v2.6 核心新增）

设计原则

默认 local-only：大多数公司不全员支持 AI 工具，少数人试用。默认不入仓 = 不强加 AI 工具给同事 = 零团队污染风险。

显式 share：用户明确知道团队接受 AI 工具，主动 --share 入仓共享。

文件归宿表（v2.6 关键契约）

模式不变量

• local-only 永远不修改 PROJECT 文件——onboard 只在 .claude/local-only/ 和 .git/info/exclude 写入；唯一例外是 CLAUDE.local.md 写到项目根（Claude Code 自动 load 它需要这个位置，但 git 默认 ignore *.local.*）
• local-only 不改 .gitignore——任何修改都可能成为 PR 噪音
• share 模式必须显式——用户 --share 即视为知情同意 AI 工具入仓
• 混合升级：local-only 已 onboard 的项目可 --update --share 升级为团队共享（state file 标 mode_migration: local-only→share，需 hard AUTH）

Local-only 模式下 Iron Laws 的特别要求

• Iron Law 8（No business logic changes）：local-only 模式扩展为"不修改任何 PROJECT 文件，包括 .gitignore"
• Iron Law 13（Touch budget）：local-only 模式的 touch_budget 限定为 CLAUDE.local.md 单文件 + .git/info/exclude 追加（LOCAL-SIDE-EFFECT，不计入预算）
• Iron Law 16（Forbidden zones global）：local-only 模式下 forbidden zones 仅通过 hook env ONBOARD_FORBIDDEN_PATHS 强制，不同步到项目的 .eslintignore / .prettierignore 等（避免 PROJECT 文件修改）

Git host adapter（v2.6 新增）

支持多 git 托管平台的统一抽象。Phase 0 探测，Phase 8 调用。

支持平台

Adapter 接口（实现层 contract）

每个 adapter 必须提供：

detect()         → bool                            是否检测到此 host
cli_available()  → bool                            对应 CLI 是否安装
template_path()  → string | null                   PR/MR 模板文件路径
create_pr(base, title, body) → command_string      构造 PR/MR 命令
web_url_hint(branch) → string                      未装 CLI 时的"手动开 PR"网址

Phase 0 探测得出 git_host 字段写入状态文件：

git_host:
  platform: github | gitlab | gitea | bitbucket | unknown
  remote_url: <git remote get-url origin 输出>
  cli_command: gh | glab | tea | null
  cli_available: true | false
  template_path: <文件路径或 null>
  enterprise: true | false   # 自托管标志（gitlab.example.com 等）

Fallback 策略

Local-only 模式下的 adapter 行为

local-only 模式 Phase 8 不 offer 任何 PR/MR——文件根本没入仓，没有可推送的 commit。但 adapter 仍然探测并记录，用于：

• --update --share 模式升级时直接复用 adapter 决策
• Doctor mode D8 检查"如未来切到 share，host 工具链是否就绪"

CLI / runtime install priority（v2.7 新增）

Phase 2.5 调用此协议生成安装命令。永不自动执行系统级安装——一律列出命令让用户确认。

三层优先级

OS / 包管理器探测

detect_os() {
  case "$(uname -s)" in
    Darwin) echo "macos" ;;
    Linux) [ -f /etc/os-release ] && . /etc/os-release && echo "$ID" || echo "linux" ;;
    MINGW*|MSYS*|CYGWIN*) echo "windows" ;;
    *) echo "unknown" ;;
  esac
}
 
detect_package_managers() {
  for pm in mise asdf brew apt dnf pacman zypper apk choco scoop winget; do
    command -v "$pm" >/dev/null 2>&1 && echo "$pm"
  done
}

系统 CLI 安装命令矩阵（核心 4 个）

未在矩阵中的 CLI → 给出官网 URL 让用户自行选择安装路径。

Local-only 模式约束

• 永不自动执行系统级安装（brew install 等）
• 永不修改项目 PROJECT 文件做 dev-dep 安装（要 --share）
• 仅可用：npx / pipx run 临时调用 + 列出系统 CLI 命令让用户手动跑

Claude Code plugin recommendation matrix（v2.7 新增；v3.2 spec 抽到 sub-file）

本段保留要点（不替代 sub-file）：