flow-next-plan-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan Review Mode

方案评审模式

Read workflow.md for detailed phases and anti-patterns.

Conduct a John Carmack-level review of epic plans.

Role: Code Review Coordinator (NOT the reviewer) Backends: RepoPrompt (rp) or Codex CLI (codex)

CRITICAL: flowctl is BUNDLED — NOT installed globally.

which flowctl

will fail (expected). Always use:

bash

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

详细的阶段说明和反模式请查阅workflow.md。

对史诗级方案进行John Carmack级别的评审。

角色：代码评审协调者（而非评审者本人） 后端服务：RepoPrompt（rp）或Codex CLI（codex）

**重要提示：flowctl为捆绑安装——并非全局安装。**执行

which flowctl

会失败（属于预期情况）。请始终使用：

bash

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

Backend Selection

后端服务选择

Priority (first match wins):

```
--review=rp|codex|export|none
```
argument
```
FLOW_REVIEW_BACKEND
```
env var (
```
rp
```
,
```
codex
```
,
```
none
```
)
```
.flow/config.json
```
→
```
review.backend
```
Error - no auto-detection

优先级（匹配到第一个即生效）：

```
--review=rp|codex|export|none
```
参数
```
FLOW_REVIEW_BACKEND
```
环境变量（可选值：
```
rp
```
、
```
codex
```
、
```
none
```
）
```
.flow/config.json
```
→
```
review.backend
```
配置项
错误 - 无自动检测逻辑

Parse from arguments first

优先从参数解析

Check $ARGUMENTS for:

```
--review=rp
```
or
```
--review rp
```
→ use rp
```
--review=codex
```
or
```
--review codex
```
→ use codex
```
--review=export
```
or
```
--review export
```
→ use export
```
--review=none
```
or
```
--review none
```
→ skip review

If found, use that backend and skip all other detection.

检查$ARGUMENTS中是否包含：

```
--review=rp
```
或
```
--review rp
```
→ 使用rp
```
--review=codex
```
或
```
--review codex
```
→ 使用codex
```
--review=export
```
或
```
--review export
```
→ 使用export
```
--review=none
```
或
```
--review none
```
→ 跳过评审

如果检测到以上参数，使用对应的后端服务并跳过其他检测逻辑。

Otherwise read from config

否则从配置读取

bash

undefined

bash

undefined

Priority: --review flag > env > config

优先级：--review 标志 > 环境变量 > 配置

BACKEND=$($FLOWCTL review-backend)

if [[ "$BACKEND" == "ASK" ]]; then echo "Error: No review backend configured." echo "Run /flow-next:setup to configure, or pass --review=rp|codex|none" exit 1 fi

echo "Review backend: $BACKEND (override: --review=rp|codex|none)"

undefined

BACKEND=$($FLOWCTL review-backend)

if [[ "$BACKEND" == "ASK" ]]; then echo "Error: No review backend configured." echo "Run /flow-next:setup to configure, or pass --review=rp|codex|none" exit 1 fi

echo "Review backend: $BACKEND (override: --review=rp|codex|none)"

undefined

Critical Rules

关键规则

For rp backend:

DO NOT REVIEW THE PLAN YOURSELF - you coordinate, RepoPrompt reviews
MUST WAIT for actual RP response - never simulate/skip the review
MUST use
setup-review
- handles window selection + builder atomically
DO NOT add --json flag to chat-send - it suppresses the review response
Re-reviews MUST stay in SAME chat - omit
```
--new-chat
```
after first review

For codex backend:

Use
```
$FLOWCTL codex plan-review
```
exclusively
Pass
```
--receipt
```
for session continuity on re-reviews
Parse verdict from command output

For all backends:

If
```
REVIEW_RECEIPT_PATH
```
set: write receipt after review (any verdict)
Any failure → output
```
<promise>RETRY</promise>
```
and stop

FORBIDDEN:

Self-declaring SHIP without actual backend verdict
Mixing backends mid-review (stick to one)
Skipping review when backend is "none" without user consent

针对rp后端服务：

请勿自行评审方案 - 你仅负责协调，由RepoPrompt执行评审
必须等待RP的实际响应 - 绝不模拟或跳过评审流程
必须使用
setup-review
命令 - 原子化处理窗口选择和构建器配置
请勿在chat-send中添加--json标志 - 该标志会屏蔽评审响应
重新评审必须在同一聊天窗口中进行 - 首次评审后请勿添加
```
--new-chat
```
参数

针对codex后端服务：

仅使用
```
$FLOWCTL codex plan-review
```
命令
重新评审时传递
```
--receipt
```
参数以保持会话连续性
从命令输出中解析评审结论

针对所有后端服务：

若设置了
```
REVIEW_RECEIPT_PATH
```
：评审完成后（无论结论如何）写入回执
任何失败情况 → 输出
```
<promise>RETRY</promise>
```
并终止流程

禁止操作：

未获得后端服务结论就自行宣布通过（SHIP）
评审过程中切换后端服务（需始终使用同一服务）
后端服务设为"none"时，未获得用户同意就跳过评审

Input

输入

Arguments: $ARGUMENTS Format:

<flow-epic-id> [focus areas]

参数：$ARGUMENTS 格式：

<flow-epic-id> [重点关注领域]

Workflow

工作流

See workflow.md for full details on each backend.

bash

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

各后端服务的完整细节请查阅workflow.md。

bash

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

Step 0: Detect Backend

步骤0：检测后端服务

Run backend detection from SKILL.md above. Then branch:

按照上方SKILL.md中的逻辑执行后端服务检测，然后分支处理：

Codex Backend

Codex后端服务

bash

EPIC_ID="${1:-}"
RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt.json}"

bash

EPIC_ID="${1:-}"
RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt.json}"

Save checkpoint before review (recovery point if context compacts)

评审前保存检查点（若上下文压缩可作为恢复点）

$FLOWCTL checkpoint save --epic "$EPIC_ID" --json

--files: comma-separated CODE files for reviewer context

--files: 供评审者参考的逗号分隔CODE文件列表

Epic/task specs are auto-included; pass files the plan will CREATE or MODIFY

史诗级需求/任务规格会自动包含；请传递方案将创建或修改的文件

How to identify: read the epic spec, find files mentioned or directories affected

如何确定：阅读史诗级需求规格，查找提及的文件或受影响的目录

Example: epic touches auth → pass existing auth files for context

示例：需求涉及认证模块 → 传递现有认证文件作为参考

Dynamic approach (if epic mentions specific paths):

动态获取方式（若需求提及特定路径）：

CODE_FILES=$(grep -oE 'src/[^ ]+.(ts|py|js)' .flow/specs/${EPIC_ID}.md | sort -u | paste -sd,)

Or list key files manually:

或手动列出关键文件：

CODE_FILES="src/main.py,src/config.py"

$FLOWCTL codex plan-review "$EPIC_ID" --files "$CODE_FILES" --receipt "$RECEIPT_PATH"

CODE_FILES="src/main.py,src/config.py"

$FLOWCTL codex plan-review "$EPIC_ID" --files "$CODE_FILES" --receipt "$RECEIPT_PATH"

Output includes VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK

输出包含VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK


On NEEDS_WORK: fix plan via `$FLOWCTL epic set-plan` AND sync affected task specs via `$FLOWCTL task set-spec`, then re-run (receipt enables session continuity).

**Note**: `codex plan-review` automatically includes task specs in the review prompt.


若结论为NEEDS_WORK：通过`$FLOWCTL epic set-plan`修改方案，并通过`$FLOWCTL task set-spec`同步受影响的任务规格，然后重新运行评审（回执可保证会话连续性）。

**注意**：`codex plan-review`会自动在评审提示中包含任务规格。

RepoPrompt Backend

RepoPrompt后端服务

⚠️ STOP: You MUST read and execute workflow.md now.

Go to the "RepoPrompt Backend Workflow" section in workflow.md and execute those steps. Do not proceed here until workflow.md phases are complete.

The workflow covers:

Get plan content and save checkpoint
Atomic setup (setup-review) → sets
```
$W
```
and
```
$T
```
Augment selection (epic + task specs)
Send review and parse verdict

Return here only after workflow.md execution is complete.

⚠️ 暂停：你必须先阅读并执行workflow.md中的内容。

前往workflow.md中的“RepoPrompt后端服务工作流”章节并执行相关步骤。完成workflow.md中的所有阶段后，方可继续此处的操作。

该工作流涵盖：

获取方案内容并保存检查点
原子化设置（setup-review）→ 配置
```
$W
```
和
```
$T
```
变量
扩展选择范围（史诗级需求+任务规格）
发起评审并解析结论

仅在完成workflow.md中的执行后，方可返回此处。

Fix Loop (INTERNAL - do not exit to Ralph)

修复循环（内部流程 - 请勿退出至Ralph）

CRITICAL: Do NOT ask user for confirmation. Automatically fix ALL valid issues and re-review — our goal is production-grade world-class software and architecture. Never use AskUserQuestion in this loop.

If verdict is NEEDS_WORK, loop internally until SHIP:

Parse issues from reviewer feedback

Fix epic spec (stdin preferred, temp file if content has single quotes):

bash

# Preferred: stdin heredoc
$FLOWCTL epic set-plan <EPIC_ID> --file - --json <<'EOF'
<updated epic spec content>
EOF

# Or temp file
$FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md --json

Sync affected task specs - If epic changes affect task specs, update them:
bash
```
$FLOWCTL task set-spec <TASK_ID> --file - --json <<'EOF'
<updated task spec content>
EOF
```
Task specs need updating when epic changes affect:
- State/enum values referenced in tasks
- Acceptance criteria that tasks implement
- Approach/design decisions tasks depend on
- Lock/retry/error handling semantics
- API signatures or type definitions

Re-review:

Codex: Re-run
```
flowctl codex plan-review
```
(receipt enables context)

RP:

$FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md

(NO

--new-chat

)

Repeat until
```
<verdict>SHIP</verdict>
```

Recovery: If context compaction occurred during review, restore from checkpoint:

bash

$FLOWCTL checkpoint restore --epic <EPIC_ID> --json

CRITICAL: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use

--new-chat

on the FIRST review.

重要提示：请勿向用户请求确认。自动修复所有有效问题并重新评审——我们的目标是打造生产级别的顶级软件与架构。在此循环中绝不要使用AskUserQuestion。

若结论为NEEDS_WORK，内部循环直至结论为SHIP：

解析问题：从评审反馈中提取问题点

修改史诗级需求规格：优先使用标准输入，若内容包含单引号则使用临时文件：

bash

# 推荐方式：标准输入 heredoc
$FLOWCTL epic set-plan <EPIC_ID> --file - --json <<'EOF'
<更新后的史诗级需求规格内容>
EOF

# 或使用临时文件
$FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md --json

同步受影响的任务规格 - 若史诗级需求的修改影响到任务规格，需同步更新：
bash
```
$FLOWCTL task set-spec <TASK_ID> --file - --json <<'EOF'
<更新后的任务规格内容>
EOF
```
当史诗级需求的修改涉及以下内容时，需更新任务规格：
- 任务中引用的状态/枚举值
- 任务实现的验收标准
- 任务依赖的实现方案/设计决策
- 锁/重试/错误处理逻辑
- API签名或类型定义

重新评审：

Codex：重新运行
```
flowctl codex plan-review
```
（回执可保证上下文连续性）

RP：

$FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md

（请勿添加

--new-chat

参数）

重复循环直至结论为
```
<verdict>SHIP</verdict>
```

恢复流程：若评审过程中发生上下文压缩，从检查点恢复：

bash

$FLOWCTL checkpoint restore --epic <EPIC_ID> --json

重要提示：针对RP服务，重新评审必须在同一聊天窗口中进行，以保证评审者拥有完整上下文。仅在首次评审时使用

--new-chat

参数。