---
name: setup
description: Use when 需要用一个 setup 入口完成 Nucleus 目标仓库初始化引导和宿主工具检查规划。
---

# Setup

> 前置：使用本 Skill 前，先按 `using-nucleus` 完成 Nucleus 入口识别（Claude Code 会话由插件 SessionStart hook 自动注入该纪律）。

`setup` 是用户主入口。它对人呈现一次 setup 体验，内部仍然编排 `target-repo-setup` 和 `host-tool-setup`，不合并两者职责边界。

## 使用原则

- 用户主要使用本 Skill；`target-repo-setup` 和 `host-tool-setup` 保留为内部能力或高级入口。
- `target-repo-setup` 只初始化目标仓库资产，不检查、不安装、不配置宿主工具。
- `host-tool-setup` 只处理宿主工具检查、规划、确认、验证和回滚证据，不写目标业务产物。
- 计划已生成不代表安装成功。仓库初始化完成不代表工具可用。
- 用户主动执行 setup 后，仓库初始化默认继续执行；遇到冲突、路径风险或宿主工具写配置风险时才停下来确认。
- 宿主工具真实可用只能由 `verify` 证据证明。
- 总结果必须分别记录目标仓库初始化和宿主工具状态；目标仓库成功不等于宿主工具成功。
- 如果 `hostTools.status` 不是 `SUCCEEDED`，当前 agent 不得结束本轮 setup 回复；必须读取 `host-tool-setup/references/host-tool-install-session.md` 和 `host-tool-setup/references/tool-installation.md`，按共享子代理预审协议（`_shared/references/subagent-precheck-protocol.md`）完成 `subagentPreReview` 并确认材料可提交人工审查，再继续发起安装确认和执行。

<HARD-GATE>
未创建宿主 todo/task 跟踪 setup 步骤时，不得运行 `apply`、`verify` 或 `build-result`。

未按宿主任务逐项完成 inspect、plan、approval、apply、verify、build-result 和必要的宿主工具安装复验时，不得把 `summary.md`、`result.json` 或 setup plan 当作 setup 终态。

内部 `target-repo-setup` 或 `host-tool-setup` 到达人工审查点时，必须先按 `_shared/references/subagent-precheck-protocol.md` 完成 `subagentPreReview` 预审并取得"材料可提交人工审查"结论；未预审不得请求人工审批或评审通过。
</HARD-GATE>

## Checklist

启动本 Skill 后，必须先为以下每一项创建宿主 todo/task，并按顺序执行；Codex 使用计划 / 任务工具，Claude Code 使用 TodoWrite 或等价宿主 todo。每完成、阻塞、等待确认或需要复验一项，都必须逐项更新状态；任何等待确认若涉及人工审查点，仍必须先有 `subagentPreReview` 且材料可提交人工审查。

1. **执行 inspect**：同时执行目标仓库只读检查（preflight）和宿主工具只读检查（inspect）。
2. **执行 plan**：生成统一 setup plan，说明 target scopes、host scopes、默认动作和风险。
3. **执行 approval --auto-defaults**：由 setup 入口生成本轮默认确认事实；遇到冲突、路径风险或用户级配置风险时停住确认。
4. **执行 apply**：默认写入 AGENTS.md 受控规则区块、初始化 `.ac` 工作目录，并为缺失宿主工具生成安装和验证引导。
5. **处理 apply 阻塞或安装引导**：冲突、越界或用户级配置风险必须停住；宿主工具缺失时按 `_shared/references/subagent-precheck-protocol.md` 完成 `subagentPreReview` 并确认材料可提交人工审查，再进入安装确认。
6. **执行 verify**：统一验证目标仓库初始化状态和宿主工具真实状态。
7. **执行 build-result**：生成 `.nucleus/runs/<workflowRunId>/setup-entry/result.json` 和 `summary.md`。
8. **复核宿主工具状态**：如果宿主工具仍缺失或未验证，读取安装会话 reference，按 `_shared/references/subagent-precheck-protocol.md` 完成 `subagentPreReview` 并确认材料可提交人工审查，再发起安装确认、执行安装 / 配置 / 激活 / 索引，并重新运行 verify 和 build-result。

`summary.md`、`result.json`、setup plan 和 guidance-only report 只是证据，不能替代宿主任务、用户确认、真实安装执行或 verify 结果。

## 子命令

运行 `python3 scripts/setup.py list-subcommands` 查看完整能力。

- `inspect` / `plan` / `approval` / `apply` / `verify` / `build-result`

## 边界

- 统一入口证据写入 `.nucleus/runs/<workflowRunId>/setup-entry/**`。
- 目标仓库初始化证据仍写入 `.nucleus/runs/<workflowRunId>/setup/**` 和 `.nucleus/runs/<workflowRunId>/result.json`。
- 宿主工具证据仍写入 `.nucleus/runs/<workflowRunId>/host-tool-setup/**`。
- 不得写 `docs/requirement/**`。不写 `.autocode/**`、`.claude/notepads/**`、`docs/bugfix/**`。
- runtime 不写用户级 Codex、Claude Code 或 MCP 配置；真实配置写入只能由当前 agent 按 `_shared/references/subagent-precheck-protocol.md` 完成 `subagentPreReview` 并确认材料可提交人工审查后，再向用户确认后执行。
- 不能把宿主工具安装、MCP 配置或激活重新塞回 `target-repo-setup`。

## 何时读取资源

- workflow step、artifact、approval 和 result 语义：读 `references/workflow-contract.md`。
- 人读摘要字段和交付口径：读 `references/human-result.md`。
- 内部编排边界和禁止事项：读 `references/orchestration-boundary.md`。
- 宿主工具缺失后的安装确认和执行闭环：读 `host-tool-setup/references/host-tool-install-session.md`，再读 `host-tool-setup/references/tool-installation.md`，并在 `subagentPreReview` 确认材料可提交人工审查后执行。
- 摘要模板来自 `assets/setup-summary-template.md`。

## 对人交付口径

inspect / plan / approval / apply 默认静默执行，只在遇到阻塞、冲突或风险时向用户说话。

结束后先读统一 `summary.md`，再读统一 `result.json`。回复必须说明仓库初始化做了什么、宿主工具检查到了什么、哪些工具还没有真实可用证据，以及是否因为冲突或写配置风险停住。不要再逐项询问用户是否写 AGENTS.md、是否初始化 `.ac` 工作目录、是否进入宿主工具安装引导；用户已经主动执行 setup，默认就是要做这些。不要把 `planHash`、`approvedScopes`、`targetPath`、`executor`、`stub` 这类内部词放在人读主线；不要让用户执行内部 Python 命令。

如果宿主工具缺失，`summary.md` 和 `result.json` 只是中间证据。当前 agent 不得结束本轮 setup 回复，必须按 `host-tool-setup/references/host-tool-install-session.md` 继续安装确认和执行：先说明将安装或配置什么、会写哪些用户级文件，按 `_shared/references/subagent-precheck-protocol.md` 完成 `subagentPreReview` 并确认材料可提交人工审查后，再等待用户确认；确认后执行；最后重新运行 verify 和 build-result。只有 verify 通过，才能说 GitNexus、Serena、Context7 或 MCP 可用。