---
name: target-repo-setup
description: Use when 需要初始化目标产品仓库的 Nucleus V2 资产、只读检查、候选产物、审批后写入和结果证据。
---

# Target Repo Setup

用于目标产品仓库的 Nucleus V2 初始化。它是 Skill package 入口，确定性本地能力由 `scripts/target_repo_setup.py` 的显式子命令执行。人读说明先使用中文动作；CLI 子命令、JSON 字段和 approval scope 保持英文机器契约。

## 最短操作顺序

1. 执行目标仓库只读检查（`run-preflight`），原始报告写到目标仓库外部。
2. 归一化只读检查结果（`normalize-preflight`）；未审批时只写 `.nucleus/runs/<workflowRunId>/**`。
3. 生成初始化计划、规则块候选差异、`docs/specs/**` 规范模板候选和模板候选产物（`build-plan`、`check-boundary`、`build-candidates`）。
4. 生成运行结果包（`build-result`）：先读 `.nucleus/runs/<workflowRunId>/summary.md`，机器事实源仍是 `.nucleus/runs/<workflowRunId>/result.json`。
5. 缺少人工审批事实时停在 `NEEDS_HUMAN_REVIEW`；只有审批事实有效时，才能写 `AGENTS.md` 的 Nucleus 管理规则块、允许目录和缺失的默认 `docs/specs/**` 规范模板。
6. 正式特性/测试骨架不由初始化步骤默认选择路径；必须由目标仓库特性树评审给出明确目标路径（targetPath）后，才允许单独执行提升命令。
7. 如需检查、安装、配置或激活宿主工具，单独使用 `$host-tool-setup`；本 Skill 的成功不代表宿主工具可用。

## 对人交付口径

运行结束后必须先读 `.nucleus/runs/<workflowRunId>/summary.md` 和 `result.json`，再按 `references/human-interaction.md` 输出结论。最终回复不能只列状态（status）、检查项（gate）或工具状态；必须明确“已经完成什么、还没有做什么、需要用户决定什么、下一步怎么做”。

## 人审前子代理预审

到达 setup plan review 或 template candidate review 前，必须按 workflow 的 `subagentPreReview` 调度独立 reviewer 子代理；未取得“材料可提交人工审查”预审结论时，不得请求人工审批或评审通过。

## 本地子命令

运行 `python3 scripts/target_repo_setup.py list-subcommands` 查看完整能力。当前实现：

- 只读检查和运行证据：`run-preflight`、`normalize-preflight`、`build-plan`、`check-boundary`、`build-candidates`、`build-result`。
- 审批后初始化写入：`resolve-approval`、`write-managed-block`、`init-assets`。
- 评审后正式写入：`promote-feature-skeleton`、`promote-test-skeleton`。

## 边界

- 目标是目标产品仓库，不是 Nucleus 插件仓库。
- `SKILL.md`、`scripts/`、`references/`、`assets/` 是 Claude Code / Codex 共享的 Skill 主体。
- `agents/openai.yaml` 只是 Codex-only optional metadata；Claude Code 不应依赖它执行本 Skill。
- 标准过程路径是 `.nucleus/**`，测试过程证据路径是 `.nucleus/tests/**`。
- 正式开发规范事实源位于 `docs/specs/**`；初始化只在 `init-assets` 审批后写缺失的默认规则模板，已有文件不覆盖，后续补充必须走目标仓库评审。
- 正式产品能力写入只面向 `docs/features/**` 和 `tests/**`，且必须经过 review gate。
- `docs/requirement/**` 是受保护需求事实源；普通 setup 和普通开发不得写。
- legacy risk path 只读探测：`.autocode/**`、`.claude/notepads/**`、`docs/bugfix/**`。命中时登记风险并阻塞确认。

## 何时读取资源

- workflow step、artifact、approval 和 command policy：读 `references/workflow-contract.md`。
- 写入边界或 plannedWrites 判断：读 `references/repo-asset-boundaries.md`。
- managed block marker、重复 marker、partial marker 或 dirty conflict：读 `references/managed-block.md`。
- 审批事实、result status 和 changedFiles 证据：读 `references/approval-and-result.md`。
- blocker code、恢复建议和 result 映射：读 `references/blocker-matrix.md`。
- 机器词和中文显示名：读 `references/terminology.md`。
- 对人交付格式、审批提示和反例：读 `references/human-interaction.md`。
- 候选内容只从 `assets/` 取，不把 asset 当作已批准正式写入。

## 阻塞规则

必须 `ALERT_AND_BLOCK`：

- 目标仓库只读检查报告（preflight report）缺失、结构错误或已阻塞。
- `plannedWrites` 越界，或计划写 legacy risk path。
- Nucleus 管理规则块边界标记（managed block marker）重复、残缺、hash 不匹配或无法安全定位。
- 缺少 `setup-plan-review.subagentPreReview` 且材料可提交人工审查的预审结论，或缺少后续人工审批事实，却要写 `AGENTS.md`、`CLAUDE.md`、`docs/features/**` 或 `tests/**`。
- 尝试把宿主工具检查、安装、配置、激活、索引或回滚纳入本 Skill。
- hooks 被当作关键检查项（gate）的替代品，而不是增强检查项。