harness-workflow: Instructions file for Codex

AGENTS.md

项目概览

本项目是 harness-workflow agent workflow skills 仓库，把 Learn Harness Engineering 的方法落成一组可执行 workflow skills；安装面以 skills.sh 为主（一条命令多端可选：选择目标 agent 与要装的技能），Claude Code 另有托管插件路径，未列入 skills.sh 的 CLI 手动拷贝。核心目标是让 agent 工作具备项目入口、状态协议、验证闸门、恢复路径和收尾纪律。

项目地图

• .claude-plugin/: Claude Code plugin manifest 和 marketplace catalog（source 指向仓库根）。
• .harness/: 运行时 recovery 三文件（work_index、state、lessons）。
• README.md / README.zh-CN.md: 用户入口，说明安装（skills.sh 多端可选）、workflow 分层、使用场景和验证命令。
• CONTEXT.md: 术语和边界澄清。
• docs/harness-method-contract.md: Harness Method Contract，解释 C1-C10 稳定方法论。
• docs/install.md: 统一安装指南（skills.sh、Claude Code 插件路径、Grok/ZCode/Kimi 手动拷贝）。
• docs/skills.md / docs/skills.zh-CN.md: 双语技能详解指南，面向第三方用户的逐技能通俗导读（协议权威仍在 skills/*/SKILL.md）。
• docs/specs/: brainstorm 默认 Spec 产物目录，允许多份独立 Spec（目录按需重建）。
• docs/plans/: plan 默认 Executable Plan 产物目录，允许多份独立计划和恢复记录（目录按需重建）。
• docs/adr/: 架构决策记录目录（目录按需重建）。
• docs/research/、docs/reviews/: 调研日志与审查报告的默认落点（目录按需重建）。
• docs/out-of-scope/: 不做清单——每个被拒想法一个文件（拒绝内容/理由/替代做法/来源），含改动门槛说明。
• .github/workflows/ci.yml: GitHub Actions，运行结构检查、README 资产检查、Claude 插件可选校验与 harness-builder 脚本测试。
• scripts/check-plugin.mjs: 仓库结构与安装面一致性的快速验证脚本。
• scripts/agent/check.sh: agent-facing 快速验证入口，串联默认结构检查。
• skills/*/SKILL.md: 每个 active workflow skill 的主入口和执行协议。
• skills/*/references/: 按需读取的细节政策、检查表和参考资料。
• skills/*/templates/: skill 使用或 backend 生成时复用的模板。

快速开始

• 快速验证：node scripts/check-plugin.mjs
• Agent 快速验证：bash scripts/agent/check.sh
• Skill 脚本测试：python3 -B skills/harness-builder/tests/test_scripts.py
• 当前没有 package install 或测试框架配置；不要虚构 npm test、npm install 或不存在的 agent 脚本。

项目铁律

• 这是 skills 仓库；安装面以 skills.sh 为主、Claude Code 插件为辅；所有改动必须保持 README.md（含 zh-CN）、docs/install.md、docs/skills.md（含 zh-CN）、.claude-plugin/、docs/harness-method-contract.md 和 skills/*/SKILL.md 之间语义一致；docs/ 顶层只放面向第三方用户的文档，内部任务产物走退休流程不留存（git 历史即归档）。
• Active workflow skills 只有 harness-builder、brainstorm、plan、implement、diagnose、review、ship、cleanup、autoresearch；verify 只是 review 的历史触发词别名，不再是独立 skill；autoresearch 是研究循环编排总控（同 ship 只编排底层阶段，自带授权边界与预算规则，研究日志为保留交付物）；find-skills、capability-recommender、writing-for-agents 是辅助 skill，不是额外 workflow lane；tdd 是被 implement 驱动的纪律 skill；工具 skill 四个：remove-deadcode-py（按需全仓 Python 死代码清理）、sweep（按需全仓对账）由 cleanup 路由或显式触发，research（轻量单发调研：后台跑腿、一手来源、产物自登记落 docs/research/）、handoff（会话交接：压缩当前会话给下一个 agent，有恢复面优先写 state）显式触发；四个工具 skill 均不做任务收尾。
• AGENTS.md 只做薄入口（T1）；临时计划、会话摘要、active slice 和当前任务 plan/Spec 路径不要写进这里。
• 本插件仓库使用 .harness/；生成到目标项目时按所选 backend 复用恢复入口，不强制迁移已有系统。
• harness-builder 是 canonical 项目 harness skill；"bootstrap" 只能作为历史别名或触发词出现。
• 每个 SKILL.md 必须保留 YAML frontmatter，并让 name 与目录名匹配。
• 没有 fresh verification，不声明插件结构、流程图或方法论覆盖已经可用。
• 修改 skill 行为须附观察到的失败（真实会话里跑了什么、技能做了什么、期望什么）；借鉴上游或纸面推演的改动在 commit/state 标注「未首跑」并写首跑观察点，首跑后回填。被拒想法落 docs/out-of-scope/，提议前先查。
• 关键里程碑必须使用 Git commit，commit 信息使用中文，清晰简洁。