onboard

/core:onboard 一次性可选配置引导

用途

由用户显式 /core:onboard 触发。Claude 不会自动调用（disable-model-invocation: true）。

以保守默认 + 显式 opt-in + local 优先 + 默认 skip + onboard 统一写入状态原则，向用户呈现 workframe 推荐但不强求的可选环境配置（当前仅 1 项：Claude Code Agent Teams flag），完成后写入 .claude/workframe-state/onboarded.json 标记。

完成此 skill 后，SessionStart hook 不再打印 onboarding 提示。

设计原则（不可妥协）

• plugin 不依赖任何被引导的可选 flag——所有可选项默认 skip 后 plugin 仍正常工作
• 所有写入必须用户当面授权——SKILL.md 不允许"为了流程顺滑"擅自写任何文件
• 写 settings.json / settings.local.json / ~/.claude/settings.json 必须：备份 + JSON merge 保留原字段 + 失败兜底输出手动补丁
• 写 .gitignore 必须先询问——动 git 行为相关文件需用户当面同意
• skip 也是有效决策——同样写 onboarded.json 让 hook 静默

输入

参数（自由文本）：

• 无参数 → 标准 onboarding 流程
• --upgrade → 已 onboarded 但 onboarding version 落后时的增量补齐（预留接口，落地版本待定）

前置检查

1. 是否已 onboarded：Read .claude/workframe-state/onboarded.json

   • 文件存在且 version == 当前 SKILL.md 中 ONBOARDING_VERSION 常量 → 用 AskUserQuestion 问"已完成 onboarding，是否重走全流程"，拒绝则结束并打印当前 onboarded.json 摘要
   • 文件不存在 → 进入正式流程
   • version 落后 → 仅处理新增项（不动已有 status 为 enabled_* 的旧项）

2. 找到 recommended-env.json：

   • 优先：Read .claude/workframe-state/plugin-root.txt 取插件根（SessionStart hook 每会话刷新）→ 拼接 <插件根>/recommended-env.json
   • 回退：Glob **/plugins/core/recommended-env.json（plugin-root.txt 缺失的开发场景）
   • 找不到 → 终止 skill，输出"plugin 安装可能不完整：core 插件根下缺 recommended-env.json"

3. Read recommended-env.json，按 recommended_env_vars 数组逐项处理（Step 1-7）。

ONBOARDING_VERSION 常量：当前 0.2.1。每次新增 recommended_env_var 项时 bump，配合 --upgrade 增量逻辑。

单项 env 处理流程

对 recommended_env_vars 中每一项执行 Step 1-7。本 SKILL.md 的所有"该项"指代当前正在处理的 env 项。

Step 1 — 版本检查

claude --version

解析输出形如 2.1.32 (Claude Code) 的版本号。对比该项 min_cli_version：

• 当前 < min_cli_version → 打印"当前 Claude Code 版本 X.Y.Z < {min_cli_version}（{env_name} 要求版本），跳过此项"，记录 status=skipped_version，跳到下一项
• 解析失败 → 打印 warning，按"无法判断版本"处理，记录 status=skipped_version_check_failed，跳到下一项

Step 2 — 已配置检查

检查环境变量是否已被用户在系统层面设置：

PowerShell:

[Environment]::GetEnvironmentVariable('{env_name}','User')
[Environment]::GetEnvironmentVariable('{env_name}','Machine')