chief-install

将 Chief 框架安装到当前项目。

这是一次延迟安装：安装时只会放置子 Agent 和 AGENTS.md。.chief/（project.md、里程碑、规则）会由 chief-agent 按需创建——运行 /chief-init 以初始化项目上下文，或直接从 /chief-plan 开始。

参数

第一个参数是目标版本（分支或标签）。可选。

• 不带参数 → 安装最新稳定版（最高的 semver 标签）。运行 git ls-remote --tags https://github.com/thaitype/chief.git 查找，去掉 refs/tags/，忽略 ^{} 条目，并选择最高的 semver 版本。
• canary → 最新的 canary 分支（正在开发，尚未发布）
• v1.0.0、v2.0.0 等 → 指定的标签版本

步骤

1. 检查是否已安装

检查以下信号，确认 Chief 是否已安装：

1. .agents/agents/chief-agent.md 是否存在
2. 根目录下的 AGENTS.md 是否包含关键字 "Chief" 或 "chief-agent"（检查文件内容，而不仅是文件是否存在——这些文件可能来自其他配置）

如果任意一项匹配 → 框架可能已安装。警告用户并建议升级。向用户显示：

npx skills@latest add thaitype/chief --skill chief-upgrade
/chief-upgrade

除非用户明确确认要全新安装，否则不要继续。

如果均不匹配 → 继续。

2. 询问编码 Agent 和安装模式

询问用户：

1. 使用哪个编码 Agent？ — 支持的 Agent：claude-code、opencode、codex、cursor、copilot、gemini-cli、amp、windsurf、kiro、aider
2. 安装模式？（适用于 claude-code 和 copilot）
   • link（推荐）——从 Agent 专属目录创建指向 .agents/ 的符号链接
   • copy ——复制文件而非创建符号链接
   • 在 Windows 上，link 模式需要启用开发者模式，并设置 git config --global core.symlinks true。如果无法满足条件，建议使用 copy 模式。
   • 对于其他所有 Agent，由于它们会直接读取 AGENTS.md 和 .agents/，安装模式不会影响行为

3. 克隆并运行设置脚本

git clone --depth 1 --branch <version> https://github.com/thaitype/chief.git .chief-agent-tmp
bash .chief-agent-tmp/scripts/setup.sh --agent <agent> --mode <mode>

脚本会安装：

• .agents/agents/*.md — 子 Agent 定义（chief、builder、tester、review-plan）
• AGENTS.md — 框架规则（不存在时全新写入；如果 AGENTS.md 已存在，则会在一个 `` 块中追加）
• Agent 专属集成文件（claude-code / copilot 对应的 .claude/agents/、.github/agents/）

脚本不会创建 .chief/。这是有意为之。

如果设置脚本完全失败（退出代码非零或发生崩溃），跳转到步骤 3b 进行完整手动安装。此时不要运行 rm -rf .chief-agent-tmp——手动安装步骤需要用到它。

如果设置脚本成功，继续步骤 4。

3b. 完整手动安装（设置脚本失败时的备用方案）

如果设置脚本失败，请手动完成整个安装：

# Subagent definitions (canonical)
cp -r .chief-agent-tmp/template/.agents .agents

安装 AGENTS.md（全新写入或追加）：

if [ ! -f AGENTS.md ]; then
  cp .chief-agent-tmp/template/AGENTS.md AGENTS.md
elif ! grep -qF "" AGENTS.md; then
  {
    echo ""
    echo ""
    cat .chief-agent-tmp/template/AGENTS.md
    echo ""
  } >> AGENTS.md
fi

仅对于 claude-code，设置 Claude Code 集成：

link 模式：

ln -s AGENTS.md CLAUDE.md
mkdir -p .claude/agents
for f in .agents/agents/*.md; do ln -s "../../$f" ".claude/agents/$(basename "$f")"; done

copy 模式：

cp AGENTS.md CLAUDE.md
mkdir -p .claude/agents
cp .agents/agents/*.md .claude/agents/

仅对于 copilot，设置 GitHub Copilot 集成：

link 模式：

mkdir -p .github/agents
for f in .agents/agents/*.md; do ln -s "../../$f" ".github/agents/$(basename "$f")"; done

copy 模式：

mkdir -p .github/agents
cp .agents/agents/*.md .github/agents/

对于其他所有 Agent——无需额外步骤。

对于非 claude-code Agent，向用户询问模型名称：

1. 思考模型（用于 chief-agent，例如 o3、gemini-2.5-pro）
2. 编码模型（用于 builder/tester/review-plan，例如 gpt-4.1、gemini-2.5-flash）

在 chief-agent 中，将 ${thinking_model} 替换为思考模型；在其他所有 Agent 文件中，将 ${coding_model} 替换为编码模型。对于 claude-code，自动替换为 opus 和 sonnet（无需询问）。对于 copilot，更新 .github/agents/ 中的文件。对于其他 Agent，更新 .agents/agents/ 中的文件。

跳过任何已存在的文件（并警告用户）。

4. 验证安装

设置脚本或手动安装完成后，请验证：

1. 子 Agent 文件存在：

   • .agents/agents/chief-agent.md
   • .agents/agents/builder-agent.md
   • .agents/agents/tester-agent.md
   • .agents/agents/answer-verifier-agent.md

   review-plan-agent.md 已弃用，不会为新项目安装。升级时，现有安装中仍保留在本地的该文件不会被更改。

2. AGENTS.md 存在，并包含 chief 框架内容（可以是整个文件，也可以是一个 `` 块）。

3. 仅限 Claude Code（如果 agent 是 claude-code）：

   • CLAUDE.md 存在（根据模式使用符号链接或副本）
   • .claude/agents/ 中包含全部 4 个 Agent 的条目
   • 如果使用链接模式：验证符号链接是否正确指向目标

4. 仅限 Copilot（如果 agent 是 copilot）：

   • .github/agents/ 中包含全部 4 个 Agent 的条目（根据模式使用符号链接或副本）
   • 如果使用链接模式：验证符号链接是否正确指向目标
   • 如果用户提供了模型名称，则模型值已替换

安装后不应存在 .chief/——不要将其缺失标记为问题。

5. 修复问题（备用方案）

如果任何验证检查失败，请手动修复：

• 缺少子 Agent 文件 → 如果 .chief-agent-tmp/template/.agents/agents/ 仍存在，则从中复制；否则重新克隆并复制相应文件
• 缺少 AGENTS.md → 重新运行 3b 中的 Fresh-or-Append 代码段
• 缺少 CLAUDE.md → 根据模式创建符号链接（ln -s AGENTS.md CLAUDE.md）或复制文件
• 缺少 .claude/ 符号链接 → 逐个创建：

  mkdir -p .claude/agents
  ln -s ../../.agents/agents/<file>.md .claude/agents/<file>.md
  

• 符号链接损坏 → 删除并重新创建
• 模式错误（例如，用户想要链接，却得到副本）→ 删除并按正确模式重新创建

6. 清理

确保已移除 .chief-agent-tmp：

rm -rf .chief-agent-tmp

7. 后续步骤

告知用户：

1. 运行 /chief-init，使用技术栈和开发命令初始化 .chief/project.md
2. 检查 AGENTS.md，并根据需要进行自定义
3. 开始规划：/chief-plan（或直接向 chief-agent 提问）

随着工作推进，.chief/ 及其子文件夹会自动创建——里程碑文件夹、规则子文件夹和报告都会在首次需要时写入。

重要规则

• 未经用户明确批准，绝不覆盖现有文件
• 如果 AGENTS.md 已存在且包含内容，请追加 chief 区块；不要覆盖
• 如果框架已安装，请改为建议使用 /chief-upgrade
• 即使安装已取消或失败，也务必清理 .chief-agent-tmp
• 如果设置脚本失败，请先尝试手动修复，再放弃
• 安装时不要创建 .chief/——现在会延迟创建
• 向用户报告所有验证结果——包括成功的结果