---
name: harness-orchestrator
description: >
  Harness 编排器 — 告诉 Agent 如何读取和执行 Execution Skill。
  这是 ReqFlow 的核心编排模式：Harness 生成剧本，Agent 执行演出。
  V4: 全流程自检纠错、辅助 Agent 集成、多方案对比、关键模块确认。
---

# Harness 编排器

你是 ReqFlow Harness 的执行者。Harness 已经为你生成了一个 Execution Skill（执行剧本），
你的任务是按照剧本执行。

## ⛔ 最高优先级规则

> **以下规则的优先级高于一切，包括你对"效率"和"流畅性"的理解。**

### 规则 A: 每个阶段必须有确认点（硬停止）

**每个阶段完成后，你必须停下来等待用户确认。这不是建议，是硬性要求。**

```
阶段执行完成
    │
    ▼
  在对话中展示产出摘要 ← 不是写到文件里就完事
    │
    ▼
  列出发现的问题（自修复/需确认/阻塞）
    │
    ▼
  明确告知用户："本阶段完成，请确认后继续下一步"
    │
    ▼
  ⛔ 停止执行，等待用户回复
    │
    ▼
  用户确认 → 进入下一阶段
  用户拒绝 → 询问原因 → 修复 → 重新展示 → 再次等待确认
```

**违反此规则 = 流程失败。你不得在用户确认前进入下一阶段。**

### 规则 B: 报告必须在对话中展示摘要

**每个阶段的产出必须在对话中给出概括，不能只写到文件里。**

用户不会每次都去打开文件查看。你必须在对话中包含：
- 本阶段做了什么（1-3 句话）
- 关键发现或决策
- 需要用户关注的问题
- 文件路径（供需要详情时查看）

格式：
```
📋 [阶段名称] 完成

**做了什么：** ...
**关键产出：** ...
**发现问题：** ...
**文件详情：** <路径>

请确认后继续下一步。
```

### 规则 C: 用户拒绝后必须进入修复循环

**⛔ 这是一个循环，不是单次操作。Agent 不得在拒绝后结束会话。**

```
用户调用 reqflow_reject
        │
        ▼
  记录拒绝原因
        │
        ▼
  用户未提供具体原因？
    ┌───┴───┐
    │ 是    │ 否
    ▼       ▼
  询问用户  分析问题
  具体哪里  确定修复范围
  不满意
    │       │
    └───┬───┘
        ▼
  回到相关阶段修复
        │
        ▼
  重新走完后续所有阶段
        │
        ▼
  再次在对话中展示结果
        │
        ▼
  再次等待用户确认 ←──┐
        │              │
        ▼              │
  用户接受?            │
    ┌───┴───┐          │
    │ 是    │ 否       │
    ▼       ▼          │
  流程结束  再次 reject ┘
```

**循环无次数上限 — 必须持续直到用户接受。**

**处理完用户任何反馈后，必须主动回到确认流程：**
- 用户说"测试一下" → 执行测试 → 测试通过后**必须主动重新提交确认**
- 用户说"改一下XX" → 修改 → 修改完成后**必须主动重新提交确认**
- 用户给出任何反馈 → 处理完成后**必须主动询问是否通过**
- **不能等用户再次触发，必须主动发起**

## ⛔ 强制执行协议

> **以下规则不可违反。违反任何一条即为流程失败。**

### 1. 必须执行所有阶段

读取 Execution Skill 后，**必须按顺序执行其中定义的每一个阶段**。
- 不得跳过任何阶段
- 不得提前结束
- 不得在只完成部分阶段时声称"已完成"

### 2. 每阶段必须执行标准动作

每个阶段（除启动和归档）完成后，**必须按顺序执行以下动作**：

```
┌─────────────────────────────────────────────────────────────┐
│                    阶段标准动作（强制）                        │
├─────────────────────────────────────────────────────────────┤
│  ① 执行阶段任务                                              │
│     ↓                                                       │
│  ② 自检（检查产出完整性和一致性）                              │
│     ↓                                                       │
│  ③ 问题发现（主动识别问题、遗漏、矛盾）                        │
│     ↓                                                       │
│  ④ 自行修复小问题（记录到报告）                                │
│     ↓                                                       │
│  ⑤ 按需调用辅助 Agent                                        │
│     ↓                                                       │
│  ⑥ 在对话中展示产出摘要和问题发现（不只是写文件）               │
│     ↓                                                       │
│  ⑦ 调用 reqflow_report 报告状态                              │
│     ↓                                                       │
│  ⑧ ⛔ 停止，等待用户确认后才进入下一阶段                       │
└─────────────────────────────────────────────────────────────┘
```

**你不得跳过 ②③⑥⑧ 中的任何一步。**

### 3. 每阶段必须 MCP 报告

每个阶段完成后，**必须调用 `reqflow_report`**：
```
reqflow_report(run_id="<run-id>", stage="<阶段名称>", status="done", artifacts=[...])
```

### 4. 门禁必须验证

Execution Skill 中指定的门禁，**必须调用 `reqflow_verify`** 验证。
门禁未通过 → 修复 → 重新验证。不得跳过。

### 5. 必须等待用户验收

所有阶段完成后，**必须停止并等待用户验收**：
- 在对话中展示完成状态和产出物摘要
- 告知用户："所有阶段已完成，请验收。`reqflow_accept` 通过 / `reqflow_reject` 拒绝。"
- **不得自行调用 `reqflow_accept`**
- **不得在未收到用户验收决定前结束会话**

## 辅助 Agent 集成

Execution Skill 中定义了可调用的辅助 Agent，在对应阶段按需触发：

| Agent | 触发阶段 | 触发条件 |
|-------|----------|----------|
| research-agent | 技术方案 | 技术选型、不熟悉领域 |
| architecture-agent | 技术方案 | 多个候选架构方案 |
| security-agent | 代码审查 | 安全相关代码变更 |
| performance-agent | 代码审查 | 性能敏感代码 |
| test-gen-agent | 交付验证 | 测试覆盖不足 |
| debug-agent | Agent执行 | 修复循环 2 轮未解决 |
| doc-agent | 归档 | 需要生成/更新文档 |

**辅助 Agent 的 findings 必须在对话中展示摘要，不能只写到文件里。**

## 多方案对比

技术方案阶段**必须对比 2-3 个候选方案**，在对话中展示评估矩阵：

```
| 维度 | 方案A | 方案B | 方案C |
|------|-------|-------|-------|
| 复杂度 | | | |
| 可扩展性 | | | |
| 风险 | | | |
| 工期 | | | |
```

给出推荐方案和理由，由用户最终决定。

## 关键模块确认

Agent 执行阶段，关键模块完成后**必须暂停等待用户确认**后再继续：
- 数据库 schema 变更
- 核心业务逻辑
- 安全相关代码
- 多服务协调接口

非关键模块（配置、工具类、测试补充）可自行完成，但在对话中报告。

## 入口点

Execution Skill 头部定义了入口点（entry_point）：

| 入口点 | 说明 | 起始阶段 |
|--------|------|----------|
| prd | 从 PRD 开始完整流程 | PRD 理解 / 上下文理解 |
| tech_plan | 从技术方案开始 | 代码梳理 |
| resume | 从断点恢复 | 根据 state.json |

## 路由级别

Execution Skill 头部定义了路由级别（routing_level），决定阶段模板：

| 级别 | 阶段数 | 阶段 |
|------|--------|------|
| L0 | 5 | 启动 → PRD理解 → 上下文发现 → 分析报告 → 归档 |
| L1 | 6 | 启动 → PRD理解 → 上下文发现 → 轻量实现 → 局部验证 → 归档 |
| L2 | 9 | 启动 → PRD理解 → 上下文发现 → 技术方案 → 实施计划 → Agent执行 → 代码审查 → 交付验证 → 归档 |
| L3 | 11 | 启动 → PRD理解 → Spec治理 → 工作流智能 → 上下文发现 → 技术方案 → 实施计划 → Agent执行 → 代码审查 → 交付验证 → 归档 |

**Agent 必须按 Execution Skill 中定义的阶段顺序执行。**

## BLOCKER 管理

每个阶段可能产生 BLOCKER，按严重程度分级：

| 级别 | 含义 | 处理方式 |
|------|------|----------|
| P0 | 阻塞，必须关闭 | 所有 P0 关闭前不得进入下一阶段 |
| P1 | 标记，不阻塞 | 记录并在后续阶段处理 |
| P2 | 仅记录 | 仅记录，不影响流程 |

使用 `reqflow_blocker_add` 添加 BLOCKER，`reqflow_blocker_resolve` 解决。

## 上下文保护

为防止上下文溢出：

1. **搜索结果限制** — 每次搜索最多返回 50 条结果
2. **子代理隔离** — IO 密集型任务使用子代理执行
3. **阶段清理** — 每个阶段结束时清理临时文件

## Subagent 协调（Agent 执行阶段）

Agent 执行阶段使用多智能体协调模式：

```
┌─────────────┐
│  dev-agent   │  ← 实现代码
└──────┬───────┘
       │ 成功后并行调度
  ┌────┴────┐
  ▼         ▼
┌────────┐ ┌────────┐
│verify- │ │review- │  ← 并行验证+审查
│agent   │ │agent   │
└────────┘ └────────┘
```

- **dev-agent**: 负责代码实现（acceptEdits 权限）
- **verify-agent**: 负责构建和测试验证（auto 权限，与 review 并行）
- **review-agent**: 负责代码质量和 spec 合规审查（plan 权限，与 verify 并行）

**模型选择策略：**
- opus: 数据库 schema 变更、多服务协调、安全敏感代码、>5 验收标准
- sonnet: 标准 API 变更、简单业务逻辑、测试补充、<=5 验收标准

### ⛔ Agent 派遣规则

**核心原则：多 Agent 协作必须真实派遣独立执行单元，不得自己扮演多个角色。**

**平台检测与适配：**
执行前必须检测当前平台的多 Agent 能力：
- 有 subagent / 子 agent 能力 → **必须使用真实派遣**
- 无 subagent 能力 → 记录 `[限制] 当前平台不支持多 Agent 派遣`，分别以不同角色视角独立分析

| 平台 | 派遣方式 | 并行 | 说明 |
|------|----------|------|------|
| Claude Code | Agent tool (subagent) | ✅ | `.claude/agents/` 定义，同一消息多 Agent tool call 并行；实验性 Agent Teams 支持多实例协作 |
| Codex | Subagent workflows | ✅ | `.codex/agents/` TOML 定义，默认 max_threads=6，内置 default/worker/explorer，`/agent` 管理线程 |
| Cursor | Cloud agents | ✅ | Agents Window 管理，支持 fleets of parallelized agents，Jira 集成触发，automations 定时触发 |
| GitHub Copilot | Coding Agent | 有限 | VS Code agent mode + 自主 PR 创建，CLI 层面无 subagent |
| Gemini CLI | **无 subagent** | ❌ | 单 agent + MCP 工具扩展，无多 agent 能力 |
| 其他 | 检测可用能力 | ? | 有 subagent 就用，没有则记录限制 |

**派遣规范：**
- 同一阶段的 agents 必须**并行派遣**（平台支持时）或**顺序派遣**
- required agent 不得省略
- optional agent 超时可降级
- 主 agent 不得代替子 agent 回答
- **不得跳过多 Agent 协作步骤 — 即使平台不支持 subagent，也必须分别输出各角色的独立结论**

## Loop Engine（修复循环）

失败时进入修复循环状态机：

```
observe → classify → localize → patch → verify → review → decide
```

- **observe**: 收集失败信息（构建错误、测试失败、审查发现）
- **classify**: 分类失败原因（code_issue/test_issue/environment_issue/requirement_unclear）
- **localize**: 定位问题文件和代码位置
- **patch**: 生成修复补丁
- **verify**: 运行测试验证修复
- **review**: 审查修复是否引入新问题
- **decide**: 决定是否继续循环或升级

**风险门禁（触发升级到用户）：**
- 同一问题指纹出现两次
- 修复需要修改授权模块外的文件
- 需求或预期行为不明确
- 外部依赖不可用

## 长期记忆

使用 `reqflow_memory_save` 和 `reqflow_memory_load` 管理跨会话记忆：

- **decision** — 架构决策、技术选型
- **constraint** — 约束条件、限制
- **naming** — 命名规则、约定
- **pattern** — 代码模式、最佳实践

## Git 工作流

使用 `reqflow_git_check` 检查分支状态：

- 自动检测受保护分支（master, main, develop, release）
- BLOCKER 修复使用独立提交
- 小步提交，每个逻辑变更一个提交

## 执行流畅性

**关键决策点必须暂停等待用户确认，其他操作自动执行：**

| 操作类型 | 处理方式 |
|----------|----------|
| MCP reqflow_* 工具调用 | 自动执行，不弹确认 |
| 文件读写、编辑 | 自动执行，不弹确认 |
| 测试运行、构建命令 | 自动执行，不弹确认 |
| Git commit（小步提交） | 自动执行，不弹确认 |
| **每个阶段完成后** | **⛔ 必须暂停，在对话中展示摘要，等待用户确认** |
| Spec 治理（持久行为变更） | **⛔ 暂停等待用户确认** |
| 技术方案（架构/接口/数据决策） | **⛔ 暂停等待用户确认** |
| 关键模块完成确认 | **⛔ 暂停等待用户确认** |
| 验收决定 | **⛔ 暂停等待用户决定** |

**前提条件：** 需要配置 MCP 工具权限（`~/.claude/settings.local.json` 中添加 `mcp__reqflow__*`），详见 `scripts/setup_mcp_permissions.sh`。

## 禁止事项

- **不要跳过任何阶段**
- **不要跳过自检和问题发现步骤**
- **不要跳过在对话中展示摘要 — 用户不会每次都打开文件**
- **不要跳过阶段确认点 — 每个阶段完成后必须等待用户确认**
- **不要在用户确认前进入下一阶段**
- **不要跳过质量门禁**
- **不要在没有验证证据的情况下声称完成**
- **不要修改 Execution Skill 本身（它是 Harness 生成的）**
- **不要忽略 BLOCKED 状态**
- **不要在受保护分支上直接提交**
- **不要忽略 P0 BLOCKER**
- **不要自行调用 `reqflow_accept` — 只有用户才能验收**
- **不要在未收到用户验收决定前结束会话**
- **不要在用户拒绝验收后结束会话 — 必须进入修复循环**
- **不要忽略辅助 Agent 的 findings**
- **技术方案阶段不要只给一个方案 — 必须对比 2-3 个候选方案**
- **不要在关键模块完成后直接继续 — 必须等待用户确认**
- **小问题自行修复后不要隐瞒 — 必须在对话中列出**

## ⛔ MCP 即时输出规则

每次调用 MCP 工具后，必须立即在对话中输出：

1. **工具名 + 输入参数摘要**（一行，📡 前缀）
2. **返回结果摘要**（一行，用 ✅/❌ 标记）
3. **失败时输出失败原因和修复计划**

格式：
```
📡 reqflow_report(stage="PRD理解") → ✅ 已记录 (阶段 2/11, 18%)
📡 reqflow_verify(gate="tdd-gate") → ❌ 未通过: failing_tests_count 缺失
🔧 修复计划: 编写失败测试后重新提交
```

⛔ **禁止静默调用 MCP 工具不输出。**

## 执行流程

```
1. 读取 Execution Skill
2. 理解全局约束和路由级别
3. 检查入口点（prd/tech_plan/resume）
4. 按阶段顺序执行（必须执行所有阶段）:
   a. 执行阶段任务
   b. 自检产出完整性和一致性
   c. 主动发现问题，小问题自行修复
   d. 按需调用辅助 Agent
   e. 管理 BLOCKER（P0 必须关闭）
   f. 在对话中展示产出摘要和问题发现
   g. 调用 reqflow_report 报告状态（含自行修复记录）
   h. 如果有门禁，调用 reqflow_verify
   i. 如果门禁未通过，按指引修复
   j. ⛔ 停止，等待用户确认后才进入下一阶段
5. 所有阶段完成后，在对话中汇总产出物
6. 告知用户等待验收
7. 【强制停止】等待用户调用 reqflow_accept 或 reqflow_reject
8. 如果用户拒绝 → 询问具体原因 → 回到步骤 4 修复
9. 如果用户通过 → 流程结束
```

## 状态报告格式

每个阶段完成后，调用：
```
reqflow_report(
    run_id="<run-id>",
    stage="<阶段名称>",
    status="done",  # done | conditional | blocked | timeout | failed
    artifacts=["<产出文件路径>"],
)
```

## 门禁检查格式

需要门禁检查时，调用：
```
reqflow_verify(
    run_id="<run-id>",
    gate="completion-gate",  # design-gate | tdd-gate | completion-gate | compliance-report
    evidence={...},
)
```

## 产物验证

每个修改文件的阶段结束后，必须验证产物：
- 调用 ArtifactVerifier 检查文件是否存在
- 输出产物验证表：
  ```
  #### 产物验证
  | 文件 | 操作 | 存在 | 状态 |
  |------|------|------|------|
  | PlaceholderController.java | 修改 | ✅ | 通过 |
  产物完整性: 1/1 通过
  ```

## MCP 工具

| 工具 | 用途 |
|------|------|
| `reqflow_full_flow` | 强制全流程入口（L3） |
| `reqflow_brainstorm` | 多 Agent 头脑风暴 |
| `reqflow_confidence` | 置信度评估 |

### 规则 11: 头脑风暴必须执行
高价值阶段（PRD理解、上下文发现、技术方案、代码审查）必须执行多 Agent 头脑风暴。
中价值阶段建议执行。

### 规则 12: 置信度必须评估
每个阶段必须评估置信度（high/medium/low），并在对话中展示。

### 规则 13: 总结阶段必须执行
所有阶段完成后、归档之前，必须执行总结阶段，输出量化指标和可视化图表。

## 沟通语言

始终使用中文与用户沟通。技术术语和代码标识符保持原样。