阶段化 AI 开发 Harness：在 Claude Code 中把模糊需求走成 IDEA → CLARIFY → SPEC → PLAN → EXECUTE → VERIFY → BUILD → DEPLOY → E2E → DONE（含 FIX 回路）的端到端流水线，配合 harnessctl 门禁、产物校验与 slash 命令编排。
更完整的概念与目录说明见 docs/README.md；命令与流程细节见 docs/usage.md。使用 claude --plugin-dir <本仓库根> 加载插件时，启动 Epic 请用 /stage-harness:harness-start（编排见 commands/harness-start.md）。
- 阶段化开发闭环：已具备
IDEA -> CLARIFY -> SPEC -> PLAN -> EXECUTE -> VERIFY -> BUILD -> DEPLOY -> E2E -> DONE主链，以及FIX -> VERIFY回路。 - 结构化分析产物：CLARIFY / PLAN / VERIFY / BUILD / DEPLOY / E2E / DONE 会落
domain-frame.json、impact-scan.md、scenario-coverage.json、decision-bundle.json、verification.json、delivery-summary.md、release-notes.md等产物，而不是只停留在对话里。 - 阶段门禁与自检：已支持
stage-gate check、clarify-selfcheck、verify-artifacts.sh，可以在推进阶段前做结构校验与阻断。 - 多仓基础能力：已支持
workspace_mode、repo-catalog、cross-repo-impact-index.json、surface-routing.json，具备 multi-repo 工作区的影响扫描与路由基础。 - 复用资产基础：已支持
memory/pitfalls.md、memory/codemaps/*、codemap-audit，可以沉淀热点模块认知并检查 CodeMap 是否 stale。 - 验证与交付闭环：已支持
verification.json、验收议会、返工回路，以及delivery-summary.md/release-notes.md交付产物。
- 执行证据链：已有
execution-trace.jsonl和 trace 事件基础，但完整 session archive / audit 视图仍在继续完善。 - 用户关注点闭环：已支持
Focus Points/focus-points.json校验，但从 CLARIFY 贯穿到 TASK / TEST / VERIFY 的完整闭环仍在增强。 - 候选技能与度量：已具备
skill-miner、candidate-skills、scan-metrics.json、scan-roi.jsonl基础，但完整自学习闭环与更宽的成功率指标仍在 roadmap 中。 - 反馈驱动重开闭环：新增设计草案 Feedback-driven Reopen Loop，用于在人工发现 SPEC / PLAN 上游理解错误时，结构化回到 CLARIFY / SPEC / PLAN 并增量重建。
完整演进方向见 docs/roadmap.md。
推荐先运行一次：
scripts/harnessctl setup
scripts/harnessctl doctor它会检查插件根目录、脚本权限、运行时依赖，并给出推荐的 HARNESSCTL 与 claude --plugin-dir 命令。repair 默认仅预览修复计划，需显式 --apply 才执行。若仓库缺少 install manifests，doctor / repair 会自动降级到 recorded-only 模式，而不是直接报错退出。
- 加载本插件：将整个仓库作为 Claude Code 插件根目录（含
.claude-plugin/plugin.json）。使用 Claude CLI 时通过--plugin-dir指向本仓库根目录即可，例如：请将路径换成本机克隆位置；非交互/打印模式同样需要携带该参数。claude --plugin-dir /opt/agent-delivery-claude/stage-harness
plugin.json里name为stage-harness，slash 命名空间为/stage-harness:，启动 Epic 时在对话中输入/stage-harness:harness-start <需求描述>（编排说明见commands/harness-start.md）。 - 如需手工方式，可为脚本加上执行权限：
chmod +x scripts/harnessctl.py scripts/*.sh - 若未把
harnessctl装进系统PATH，在被开发项目的根目录设置HARNESSCTL，指向插件内的 CLI（setup会打印推荐值；按布局二选一）：# 被开发项目与插件目录分离时（推荐写绝对路径，与 --plugin-dir 指向同一克隆） export HARNESSCTL=/opt/agent-delivery-claude/stage-harness/scripts/harnessctl # 若你使用仓库内的 Python 入口，也可 export …/scripts/harnessctl.py # 被开发仓库把本插件作为子目录 stage-harness/ 时 # export HARNESSCTL="${HARNESSCTL:-./stage-harness/scripts/harnessctl}"
- 首次使用
/stage-harness:harness-start时会初始化项目下的.harness/（也可手动执行$HARNESSCTL init，或使用scripts/harnessctl setup --init-project --project-root <项目根>）。
如需自检或低风险修复：
scripts/harnessctl doctor
scripts/harnessctl repair # 仅预览修复计划
scripts/harnessctl repair --apply在对话中使用以下命令（阶段为流水线中的位置；具体行为以各 commands/harness-*.md 为准）：
| 命令 | 阶段 | 说明 |
|---|---|---|
/stage-harness:harness-start |
IDEA→CLARIFY | 启动 Epic：初始化、画像、创建 Epic、进入 CLARIFY |
/stage-harness:harness-clarify |
CLARIFY | 需求澄清、影响扫描、决策包、门禁 |
/stage-harness:harness-spec |
SPEC | Decision Bundle → ShipSpec → 轻量议会 |
/stage-harness:harness-plan |
PLAN | Bridge、表面研究、任务 DAG、覆盖矩阵、Plan 议会 |
/stage-harness:harness-work |
EXECUTE | 按任务执行：锚定→预检→TDD→冒烟→提交与回执 |
/stage-harness:harness-review |
VERIFY | 并行审查、对抗性审查、验收议会 |
/stage-harness:harness-fix |
FIX | 按 verification.json 修复后回到 VERIFY |
/stage-harness:harness-done |
DONE | Release 议会、交付包、经验沉淀、技能挖掘 |
/stage-harness:harness-patch |
任意 | 即时纠偏：诊断偏差、规则补丁草稿与热加载 |
/stage-harness:harness-auto |
全阶段 | 自治循环推进直至 DONE |
/stage-harness:harness-status |
任意 | 只读：Epic、阶段、预算、任务进度 |
/stage-harness:harness-bridge |
PLAN | ShipSpec → 深度计划的 Bridge 脚本 |
/stage-harness:mmr |
快速修复 | 轻量 MMR：方案 → 三模型方案复审 → 执行 → 三模型代码复审 |
兼容说明：若安装方式将插件注册为短名
harness，对话里也可能显示为/stage-harness:*；钩子与下文示例中的/stage-harness:harness-*会被等价识别，编排均以commands/harness-*.md为准。
/stage-harness:harness-start <需求描述>— 创建 Epic 并停在 CLARIFY。- 按需执行
/stage-harness:harness-clarify→/stage-harness:harness-spec→/stage-harness:harness-plan→/stage-harness:harness-work→/stage-harness:harness-review。 - 审查不通过时用
/stage-harness:harness-fix，再/stage-harness:harness-review。 - 通过后
/stage-harness:harness-done收尾。
/stage-harness:harness-start 我想给系统加一个通知模块
/stage-harness:harness-auto
/stage-harness:harness-auto 会按当前阶段循环执行对应推进逻辑，并在 EXECUTE / VERIFY / BUILD / DEPLOY / E2E / FIX 间自动处理，直到 DONE。
/stage-harness:mmr 修复用户头像上传失败的问题：选择 png 后接口返回 400，期望成功上传并展示新头像
/stage-harness:mmr 不创建完整 .harness Epic，适合边界清晰的小型修复。它会先由 mmr-planner 出方案，再通过已配置为 gpt-5.5、google/gemini-3.1-pro-preview、claude-opus-4.6-thinking 的三个 reviewer 做方案复审；执行后再用同一组三模型 reviewer 做代码复审，并在最后汇总方案、改动、校验和六份复审结论。
中断会话后可用 /stage-harness:harness-patch <epic-id> 生成规则补丁草稿，再配合 /stage-harness:harness-auto <epic-id> 热加载后继续。
在项目根设置好 HARNESSCTL 后：
$HARNESSCTL setup
$HARNESSCTL doctor
$HARNESSCTL repair # dry-run
$HARNESSCTL repair --apply
$HARNESSCTL status
$HARNESSCTL state get <epic-id>
$HARNESSCTL task list <epic-id>
$HARNESSCTL stage-gate check CLARIFY # 各阶段名：SPEC、PLAN、VERIFY 等
$HARNESSCTL clarify-selfcheck --epic-id <epic-id>
$HARNESSCTL profile detect多仓、codemap、metrics、门禁跳过等进阶用法见 docs/usage.md 的「状态查看」与「常见问题」。
| 路径 | 作用 |
|---|---|
commands/ |
各 /stage-harness:harness-* slash 与 /stage-harness:mmr 的编排说明 |
agents/ |
专业 Agent 角色定义 |
skills/ |
可复用技能（如 clarify、plan、council） |
hooks/ |
SessionStart、PreToolUse 等钩子 |
scripts/ |
harnessctl、verify-artifacts.sh、decision-bundle.sh 等 |
templates/ |
project-profile.yaml、repo-catalog.yaml 等模板 |
docs/ |
使用指南、架构与人类协作说明 |
tests/ |
测试（若有变更脚本行为，可在此补充用例） |
运行时产物落在被开发仓库的 .harness/ 下（配置、Epic、features/<epic-id>/ 等），不在本插件目录内。
- docs/README.md — 架构分层、七阶段表、Decision Bundle / 预算 / 议会、
.harness目录树 - docs/usage.md — 安装细节、各命令流程与产物、FAQ
- docs/architecture.md — 实现与模块关系
- docs/human-workflow-and-orchestration.md — 人类协作与编排注意点
- docs/feedback-driven-reopen-loop.md — 人工反馈驱动的阶段重开与增量重建设计
- docs/roadmap.md — 中长期功能规划、优先级与实施方向