| name | harness-init |
| description | 为当前项目初始化完整的 Harness Engineering 配置（Rules、Hooks、Constraints、QA 标准）。Use when bootstrapping a new project or adding harness to an existing project. |
Harness Init
为当前项目生成完整的 Harness Engineering 配置。
何时使用
- 新建项目，需要搭建开发 Harness
- 已有项目，需要加装约束和 QA 体系
- 用户说"初始化 harness"或"搭建开发流程"
生成原则（不可违反，违反即视为 bug）
历史教训 VH-08（2026-04-08）：本 skill 的旧版本只画了文件树和必选清单，没有要求 AI 读取真实源。AI 走到这里时凭训练记忆拼 .claude/settings.json，结果生成了 Claude Code 不认识的 key 结构（Invalid key in record），用户重启 session 即报错。同一个失败模式在 templates ⇌ required-wiring.json 这一对上已经被 #16 / #23 修复过，但当时没意识到 SKILL.md 也是一份会"凭记忆生成"的入口。
约束 C-INIT-04（+ C-SKILL-01 路径解析约定）：
路径解析约定（C-SKILL-01, VH-10 教训）：本 SKILL.md 中所有 ./resources/xxx 路径均相对 SKILL.md 文件本身的位置（通常是 ~/.claude/skills/harness-init/resources/ 或 <project>/.claude/skills/harness-init/resources/），这是 skill 安装后的真实路径，与 AI 当前 cwd 无关。kit 仓库相关的文件（hooks、templates/rules、e2e-acceptance-validate.sh）通过 Step 0 定位的 $KIT_ROOT 变量访问。cwd-relative 路径（如直接写 simple-harness-kit/foo）会直接失败——60+ 用户把 kit 放在任意位置。
.claude/settings.json 不能凭记忆生成。必须先读取 ./resources/settings-json.tmpl（skill-relative），以模板为唯一真实源，再做项目定制（替换路径、可选 hook 增删）。- Hook 脚本不能凭记忆生成。必须从 kit 仓库
scripts/hooks/ 读取对应脚本，并同步 scripts/lib/ 下的共享库（定位方式见 Step 0），复制到目标项目，不修改脚本内容——它们是 kit 的一部分，会随升级更新。如目标项目用 monorepo，复制策略由项目结构决定，但脚本本体保持不变。
- Rules 文件不能凭记忆生成。必须从 kit 仓库
templates/rules/ 下的 *.tmpl 派生，做项目占位符替换。
- 必选/可选组件清单以
./resources/init-prompt.md 为权威（skill-relative）。本文件不复述清单——任何看到必选项变化的人，都必须改 init-prompt.md，而不是改这里。
- wiring（hook event/matcher 注册）以
./resources/required-wiring.json 为权威（skill-relative）。这是工程层的 single source of truth，validate.sh 和 template-integrity 都从它派生。
- 生成完毕后必须做 Step 4 的 6 项用户层完整性检查（C-SKILL-03），全部通过才可宣称 init 完成。不要默认跑 kit CI 工具
tests/e2e-acceptance-validate.sh（那是 kit 维护者用的 76 项全量检查，不是用户 flow）。用户如需深度验证可自行跑。
- 必须先复制 hook/lib，再写 runtime 配置（C-INIT-06, VH-24）：写
.claude/settings.json 前，先根据 ./resources/required-wiring.json 的 required_files 复制所有本地 hook 脚本和共享库依赖，尤其 scripts/lib/spec-quality.js；如需 .codex/hooks.json，也必须在这些文件存在后再生成。禁止先写 settings、后补 lib；Claude Code 会在同一轮后续工具调用中立即加载刚写入的 hook，半安装状态会直接 MODULE_NOT_FOUND。
任何"为了简化/适配/AI 觉得这样更好"而违反以上 7 条的行为，都是 bug，不是优化。
执行流程
Step 0: 定位 kit 仓库（只为 Step 3 的脚本/rule 拷贝 + Step 4 的 validate.sh）
本 skill 已自包含 4 个关键资源（./resources/ 下），Step 1 全部从 resources/ 读取。
但 Step 3 需要把 kit 的 scripts/hooks/*.js、scripts/lib/*.js 和 templates/rules/*.tmpl 拷贝到目标项目——这一步需要知道 kit 仓库在哪。
定位顺序（取第一个命中且锚点校验通过的）：
-
环境变量 SIMPLE_HARNESS_KIT_ROOT 指向的目录（若用户显式设置，最可信）
-
~/.simple-harness-kit-root 文件第一行（install.sh / update.sh 写入，用户运行过 install 即有）
-
主动扫描以下候选位置 + 当前 SKILL.md 文件位置向上回溯（如 skill 在 $HOME/.codex/skills/harness-init/SKILL.md，回溯到 $HOME/ 不会找到 kit；但若是 project-scope 装在 project root 的 .claude/skills/harness-init/，向上找可能命中 project root 下的 simple-harness-kit/）：
~/simple-harness-kit~/ops/simple-harness-kit~/Projects/simple-harness-kit~/code/simple-harness-kit~/Dropbox/*/simple-harness-kit（常见 Dropbox 结构）
每个候选都必须做下面的 7 锚点校验。校验通过的候选列出来让用户确认/选择（多个候选时让用户输入数字），不得静默使用。
-
让用户手动输入 kit 绝对路径
优先级 (1) 和 (2) 是用户已显式信任的源（设了 env var / 跑过 install.sh），校验通过即可使用，不必再问。
优先级 (3) 是自动扫描，校验通过的候选必须显式让用户确认。
优先级 (4) 是兜底。
禁止（C-SKILL-02, VH-10 后加强的 trust model 规则）：
-
不得在用户当前 cwd 或其父目录自动"向上查找 simple-harness-kit/"然后静默使用。如果用户在 /tmp/untrusted-project 下工作，而该目录恰好有 simple-harness-kit/ 子目录，自动信任这个"子目录" = supply-chain 攻击：恶意 kit 的 install.sh / templates/rules/*.tmpl / scripts/hooks/*.js 会被写入用户项目。必须用户显式确认。
-
不得假设第一个找到的 simple-harness-kit/ 目录就是真的。必须做结构完整性校验：定位到候选路径 $CAND 后，先校验以下所有文件/目录都存在且非空：
$CAND/methodology/00-philosophy.md（方法论根文档，真实文件名）$CAND/templates/settings-json.tmpl$CAND/tests/required-wiring.json$CAND/tests/template-integrity.js$CAND/scripts/hooks/ 下至少 5 个 .js 文件$CAND/CHANGELOG.md 首行含 # Changelog$CAND/init-prompt.md 存在
这 7 个锚点都是 kit 长期稳定的文件。任一不满足 → 拒绝使用该候选，回到定位流程 next priority。
-
必须：优先级 (3) 主动扫描定位到候选 kit 路径时，必须显式告诉用户："我打算用 $CAND 作为 kit 仓库，这是你的安装位置吗？(确认/否)"。得到用户确认后才继续 Step 3/4。如果用户不确认 → 进入优先级 (4) 询问绝对路径。
-
优先级 (1)（env var）和 (2)（~/.simple-harness-kit-root 文件）已是用户显式信任的源（设了变量 / 跑过 install.sh 自己写的），校验通过后可直接使用，无需再问。
反模式（禁止）：
- 直接写
simple-harness-kit/... 这样的 cwd-relative 路径（VH-10 问题 B）
- 自动信任 cwd 向上搜索到的
simple-harness-kit/（VH-10 Codex gpt-5.4 round 3 F3 发现的 supply-chain 风险）
Codex 模式提示：如果你检测到当前是 Codex exec (non-interactive) 模式（hook stdin 的 permission_mode === "bypassPermissions" 且无法等待用户输入），且优先级 (1) (2) 都没命中、(3) 多个候选需要用户选择 / 确认 → 直接退出并提示用户："Codex exec 模式无法交互回答 kit 路径，请改用 TUI: 关掉当前会话, 跑 codex --enable hooks --sandbox workspace-write --ask-for-approval on-request, 进入 TUI 后再输 \$harness-init"。强行猜路径或继续 = VH-15 类回归。
Step 1: 读取真实源（全部 skill-relative，cwd 无关）
依次 Read 以下文件，作为本次 init 的全部依据：
./resources/init-prompt.md —— 流程总纲、必选/可选组件清单、定制说明./resources/settings-json.tmpl —— settings.json 唯一真实源./resources/required-wiring.json —— hook wiring 唯一真实源./resources/hook-coverage-matrix.md —— hook 覆盖矩阵，理解每个 wiring 的来由
这些路径相对 SKILL.md 文件本身，skill 安装到任何位置都能解析。
不要跳过这一步。不要"我已经知道大概结构"。
Step 2: 自动扫描项目信息
按 init-prompt.md 描述的方式扫描：package.json / pyproject.toml / go.mod / 目录结构 / 已有 CLAUDE.md / 已有 .claude/。
Step 3: 按 init-prompt.md 生成产物
完全遵循 ./resources/init-prompt.md 的"必选 / 可选 / 定制"段落。.claude/settings.json 必须从 ./resources/settings-json.tmpl 派生（不是从记忆里写）。
拷贝 kit 脚本和 rule 模板到目标项目时，用 Step 0 定位到的 kit 根目录 $KIT_ROOT：
- Hook 脚本源:
$KIT_ROOT/scripts/hooks/*.js
- Hook 共享库源:
$KIT_ROOT/scripts/lib/*.js
- Rule 模板源:
$KIT_ROOT/templates/rules/*.tmpl
强制生成顺序（C-INIT-06，禁止调整）：
- 创建目标目录：
.claude/rules、scripts/hooks、scripts/lib、docs、.harness，需要 Codex 时再创建 .codex。
- 读取
./resources/required-wiring.json 的 required_files。
- 先复制
required_files 里的所有 scripts/hooks/*.js 和 scripts/lib/*.js 到目标项目。不要只复制旧的 6 个 hook；必须包含 scripts/hooks/harness-entry-banner.js、scripts/hooks/stage-since-autofill.js、scripts/lib/spec-quality.js。
- 再复制 rule 模板和
docs/constraints.md / CLAUDE.md / AGENTS.md 等非 runtime 配置。
- 最后写
.claude/settings.json，然后如适用再由 .claude/settings.json 派生 .codex/hooks.json。
原因：.claude/settings.json 一旦写入，Claude Code 后续工具调用可能立刻触发 PreToolUse。如果此时 harness-stage-guard.js 已存在但 scripts/lib/spec-quality.js 尚未复制，真实 runtime 会报 MODULE_NOT_FOUND: ../lib/spec-quality。
生成 settings.json 的两种策略 — 默认走更安全的那条：
- (推荐) 从
./resources/required-wiring.json 直接派生最小集 — 这是工程层的 single source of truth，只包含必选 wiring，不含 optional hooks。一行一行翻译成 {event, matcher, hooks: [{type, command}]} 即可。优点：默认安全，AI 不会"忘记删 optional"
- (高级) 从
./resources/settings-json.tmpl 复制后删 optional 条目 — template 包含 optional hooks (verification-gate / delivery-review / commit-check / agent-check / context-monitor / delivery-gate) 的预设 wiring。如果项目需要这些 hooks，按 init-prompt.md 的"可选组件"表判断保留哪些；其余必须删除。风险：AI 容易漏删，结果是 settings 引用了不存在的 hook 脚本（被 validate.sh E2 检查 catch，但多一次 round trip）
默认走第一种。只有当用户明确要求启用某个 optional hook 时，才走第二种并精确取舍。
Step 3.5: 检测并生成 Codex 配置（如适用）
Step 3 生成了 Claude Code 的 .claude/settings.json。此步检测是否需要同时生成 Codex 的 .codex/hooks.json。
检测方式（按优先级，任一命中即视为需要 Codex 配置）：
- 用户在 prompt 中提到了 "Codex" 或 "codex"
- 项目中已有
.codex/ 目录
- 系统中
which codex 可用
如检测到 Codex 适用，向用户说明：
检测到 Codex 环境，我会额外生成:
.codex/hooks.json — canonical hooks 配置（顶层 hooks，无 deprecated alias）
不需要 Codex 配置? 告诉我"跳过 Codex"。
用户确认（或未反对）后，生成步骤：
- 读取刚生成的
.claude/settings.json
- 用
$KIT_ROOT/scripts/generate-codex-hooks.js 派生 canonical .codex/hooks.json（顶层只含 hooks）
- 确认
PreToolUse stage guard matcher 覆盖 Bash|apply_patch|mcp__.*
- 确认包含
PermissionRequest guard，用官方 decision.behavior shape 拦截 PLAN 阶段权限升级
- 确认没有 deprecated feature alias
- 在输出中提醒：
Codex 用户注意:
hooks feature flag 必须启用才能触发 Hook。
推荐在 ~/.codex/config.toml 中添加:
[features]
hooks = true
新增或变更 project-local hooks 后，请在新 session 里运行 /hooks 做 trust/review。
如未检测到 Codex — 跳过此步，不生成 .codex/hooks.json。
手动工具：如果 init 时未生成，用户后续可手动生成：
node $KIT_ROOT/scripts/generate-codex-hooks.js --input .claude/settings.json --output .codex/hooks.json
Step 4: 验证 init 完整性（C-SKILL-03: 用户层最小集）
生成产物后，做以下 6 项用户层检查（不跑 76 项 kit CI）:
- 必选文件存在: 以
./resources/required-wiring.json.required_files 为准，确认所有必选文件存在；不得使用旧的“6 个 hook”清单代替真实源。
- settings.json JSON 有效:
node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))"
- hook 脚本存在: settings.json 里每个
command 引用的 scripts/hooks/xxx.js 都有对应文件
- hook 本地 require 依赖存在: 对 settings.json 引用的每个 hook，扫描
require('./...') / require('../...') 这类本地依赖，确认目标文件存在；例如 harness-stage-guard.js 的 require('../lib/spec-quality') 必须对应 scripts/lib/spec-quality.js。缺依赖会导致新 session 一触发 hook 就 MODULE_NOT_FOUND，不能放行。
- CLAUDE.md 非空: 大于 200 bytes
- Codex harness 检查（如生成
.codex/hooks.json）: JSON 顶层是 canonical hooks、不含 deprecated alias、PreToolUse matcher 含 Bash|apply_patch|mcp__.*、包含 PermissionRequest、hook command 引用的脚本存在且可执行/可读
全部通过 → 输出:
Harness init 完成 ✓
下一步: 开新 session (当前 session 的 hook 不生效), 输入任务开始工作
Codex: 如生成/更新了 .codex/hooks.json，请在新 session 里运行 /hooks trust/review
如需深度验证: bash $KIT_ROOT/tests/e2e-acceptance-validate.sh
任何失败 → 输出失败项 + 修复 → 重新检查。
禁止默认跑 tests/e2e-acceptance-validate.sh 的 76 项全量 CI 输出（C-SKILL-03）。那是 kit 维护者的工具，不是用户 init flow 的组成部分。用户想跑就给路径让用户自己决定。
注意事项
- 不覆盖已有的
CLAUDE.md 或 .claude/settings.json，而是合并
docs/constraints.md 初始为空模板，随项目迭代逐步填充- Hook 脚本需要 Node.js 环境
- Hook 配置写入后当前 session 不生效，必须新 session
Codex 用户
Codex 用户执行 init 时必须使用 TUI 模式；推荐启动参数为 codex --enable hooks --sandbox workspace-write --ask-for-approval on-request。Step 3.5 会自动检测 Codex 环境并生成 canonical .codex/hooks.json。
如果 init 时未自动生成，可手动：
node $KIT_ROOT/scripts/generate-codex-hooks.js --input .claude/settings.json --output .codex/hooks.json
详见 ./resources/init-prompt.md 中"Codex 用户注意"段。
Attribution
如果项目已有 README.md，默认在底部追加：
---
Harnessed by [Simple Harness Kit](https://github.com/duoglas/simple-harness-kit)
- 已有此标注则不重复
- 没有 README 不创建
HARNESS_ATTRIBUTION=off 跳过
