---
name: ralplan
description: 在执行前自动拦截并门控模糊的 ralph/autopilot/team 请求的共识规划入口
level: 4
---

# Ralplan（共识规划别名）

Ralplan 是 `/oh-my-claudecode:omc-plan --consensus` 的简写别名。它会触发由 Planner、Architect 和 Critic agent 参与的迭代式规划，直到达成共识，并采用 **RALPLAN-DR 结构化审议**（默认使用 short 模式，高风险工作使用 deliberate 模式）。

## 用法

```
/oh-my-claudecode:ralplan "task description"
```

## 标志

- `--interactive`：在关键决策点启用用户提示（第 2 步的草案评审和第 6 步的最终批准）。不带此标志时，工作流将完全自动运行，即 Planner → Architect → Critic 循环，并在不请求确认的情况下输出最终计划。
- `--deliberate`：对高风险工作强制启用 deliberate 模式。会增加预演失败分析（3 个场景）和扩展测试规划（unit/integration/e2e/observability）。不带此标志时，如果请求明确表现出高风险信号（auth/security、migrations、destructive changes、production incidents、compliance/PII、public API breakage），也仍可能自动启用 deliberate 模式。
- `--architect codex`：当 Codex CLI 可用时，在 Architect 阶段使用 Codex。否则，简要说明回退情况，并继续使用默认的 Claude Architect 评审。
- `--critic codex`：当 Codex CLI 可用时，在 Critic 阶段使用 Codex。否则，简要说明回退情况，并继续使用默认的 Claude Critic 评审。

## 结合 interactive 模式的用法

```
/oh-my-claudecode:ralplan --interactive "task description"
```

## 行为

此技能会以共识模式调用 Plan skill：

```
/oh-my-claudecode:omc-plan --consensus <arguments>
```

共识工作流如下：
1. **Planner** 在评审前创建初始计划和紧凑的 **RALPLAN-DR 摘要**：
   - 原则（3-5 条）
   - 决策驱动因素（前 3 项）
   - 可行选项（>=2 个），并附带有边界的利弊分析
   - 如果最终只剩下一个可行选项，需要明确说明其他备选方案失效的原因
   - 仅在 deliberate 模式下：预演失败分析（3 个场景）+ 扩展测试计划（unit/integration/e2e/observability）
2. **用户反馈** *(`--interactive` only)*：如果设置了 `--interactive`，在评审前使用 `AskUserQuestion` 展示草案计划 **以及 Principles / Drivers / Options 摘要**（Proceed to review / Request changes / Skip review）。否则，自动继续进入评审。
3. **Architect** 评审架构合理性，并且必须给出最强有力的 steelman antithesis、至少一个真实的权衡张力，以及（在可能时）综合结论；**在进入第 4 步之前必须等待其完成**。在 deliberate 模式下，Architect 应明确标出违反原则的地方。
4. **Critic** 根据质量标准进行评估，仅能在第 3 步完成后运行。Critic 必须强制检查原则与选项的一致性、备选方案是否公平、风险缓解是否清晰、验收标准是否可测试，以及验证步骤是否具体。在 deliberate 模式下，Critic 必须拒绝缺失或薄弱的预演失败分析或扩展测试计划。
5. **重新评审循环**（最多 5 轮）：只要 Critic 的结论不是 `APPROVE`（即 `ITERATE` 或 `REJECT`），就必须运行同样的完整闭环：
   a. 收集 Architect + Critic 的反馈
   b. 由 Planner 修订计划
   c. 返回 Architect 评审
   d. 返回 Critic 评估
   e. 重复此循环，直到 Critic 返回 `APPROVE` 或达到 5 轮
   f. 如果达到 5 轮仍未得到 `APPROVE`，则向用户展示当前最佳版本
6. 在 Critic 批准后 *(`--interactive` only)*：如果设置了 `--interactive`，使用 `AskUserQuestion` 展示计划和批准选项（Approve and implement via team (Recommended) / Approve and execute via ralph / Clear context and implement / Request changes / Reject）。最终计划必须包含 ADR（Decision、Drivers、Alternatives considered、Why chosen、Consequences、Follow-ups）。否则，输出最终计划并停止。
7. *(`--interactive` only)* 用户选择：Approve（team 或 ralph）、Request changes，或 Reject
8. *(`--interactive` only)* 在批准后：调用 `Skill("oh-my-claudecode:team")` 进行并行团队执行（推荐），或调用 `Skill("oh-my-claudecode:ralph")` 进行顺序执行；绝不能直接实现

> **重要：**步骤 3 和 4 **必须**按顺序运行。**不要**在同一个并行批次中同时发出这两个 agent Task 调用。始终先等待 Architect 的结果，再发出 Critic Task。

有关共识模式的详细信息，请参阅 Plan skill 的完整文档。

## 执行前门控

### 为什么需要这个门控

执行模式（ralph、autopilot、team、ultrawork、ultrapilot）会启动重量级的多 agent 编排。当它们被用于像 “ralph improve the app” 这样模糊的请求时，agent 没有明确目标，只能把时间浪费在本应在规划阶段完成的范围探索上，结果往往交付出局部或不对齐的工作，后续还需要返工。

ralplan-first 门控会拦截这类规格不足的执行请求，并将其重定向到 ralplan 共识规划工作流。这可以确保：
- **显式范围**：PRD 精确定义将要构建的内容
- **测试规范**：在编写代码之前，验收标准就是可测试的
- **达成共识**：Planner、Architect 和 Critic 对方案一致认可
- **不浪费执行资源**：agent 在清晰且边界明确的任务上启动

### 好提示词与坏提示词

**通过门控**（足够具体，可以直接执行）：
- `ralph fix the null check in src/hooks/bridge.ts:326`
- `autopilot implement issue #42`
- `team add validation to function processKeywordDetector`
- `ralph do:\n1. Add input validation\n2. Write tests\n3. Update README`
- `ultrawork add the user model in src/models/user.ts`

**会被门控并重定向到 ralplan**（需要先明确范围）：
- `ralph fix this`
- `autopilot build the app`
- `team improve performance`
- `ralph add authentication`
- `ultrawork make it better`

**绕过门控**（当你已经明确知道自己想要什么时）：
- `force: ralph refactor the auth module`
- `! autopilot optimize everything`

### 门控不会触发的情况

当门控检测到**任意一个**具体信号时，就会自动放行。你不需要同时满足全部条件，只要有一个就够了：

| Signal Type | Example prompt | Why it passes |
|---|---|---|
| File path | `ralph fix src/hooks/bridge.ts` | 引用了具体文件 |
| Issue/PR number | `ralph implement #42` | 有具体工作项 |
| camelCase symbol | `ralph fix processKeywordDetector` | 指定了具体函数 |
| PascalCase symbol | `ralph update UserModel` | 指定了具体类 |
| snake_case symbol | `team fix user_model` | 指定了具体标识符 |
| Test runner | `ralph npm test && fix failures` | 有明确的测试目标 |
| Numbered steps | `ralph do:\n1. Add X\n2. Test Y` | 有结构化交付项 |
| Acceptance criteria | `ralph add login - acceptance criteria: ...` | 明确给出了成功定义 |
| Error reference | `ralph fix TypeError in auth` | 指向了具体错误 |
| Code block | `ralph add: \`\`\`ts ... \`\`\`` | 提供了具体代码 |
| Escape prefix | `force: ralph do it` or `! ralph do it` | 用户显式要求绕过 |

### 端到端流程示例

1. 用户输入：`ralph add user authentication`
2. 门控检测到：执行关键词（`ralph`）+ 规格不足的提示词（没有文件、函数或测试规范）
3. 门控将请求重定向到 **ralplan**，并附带解释重定向原因的消息
4. Ralplan 共识流程运行：
   - **Planner** 创建初始计划（涉及哪些文件、使用什么 auth 方法、需要哪些测试）
   - **Architect** 评审其合理性
   - **Critic** 验证质量与可测试性
5. 在共识批准后，用户选择执行路径：
   - **team**：并行协作的协调 agent（推荐）
   - **ralph**：带验证的顺序执行
6. 执行在一个清晰、边界明确的计划基础上开始

### 故障排查

| Issue | Solution |
|-------|----------|
| Gate fires on a well-specified prompt | 添加文件引用、函数名或 issue 编号，为请求提供锚点 |
| Want to bypass the gate | 使用 `force:` 或 `!` 作为前缀（例如 `force: ralph fix it`） |
| Gate does not fire on a vague prompt | 该门控只会捕获有效词数 <=15 且没有具体锚点的提示词；请补充更多细节，或显式使用 `/ralplan` |
| Redirected to ralplan but want to skip planning | 在 ralplan 工作流中说 “just do it” 或 “skip planning”，即可直接过渡到执行 |