flow

Flow - 复杂任务编排引擎

将多个技能串联为"优化 → 思考 → 规划 → 执行"的完整管道，通过参数灵活控制每个阶段。

触发条件

TRIGGER when user:

• 显式调用 /flow <任务描述>
• 请求处理复杂任务："帮我处理这个复杂任务"、"这个任务比较复杂"
• 请求编排式执行："先优化再规划再执行"、"从优化到执行"
• 使用关键词：flow、编排、管道、复杂任务流程
• 任务描述明确涉及多步骤、多角色、或需要拆分执行

AUTO-DETECT:

• 用户描述的任务涉及 3 个以上步骤
• 用户提及多个技能的组合使用（如"先 /prompt 再 plan 再 multi-agent"）

选型指南：何时用 flow vs flow-deep vs grill-me

flow 是轻量编排。更轻用 grill-me，更重用 flow-deep。完整决策依据、组合用法、误用案例见 references/selection-guide.md。

口诀：小澄清 grill-me，大工程 flow-deep，中间 flow。拿不准问"做错了多难恢复"。

升级/降级信号、组合用法、三种误用 → 详见 references/selection-guide.md。交互式路由可用 /ask-matt（路由 mattpocock 体系，不覆盖 flow/flow-deep）。

必需依赖

可选依赖（按需启用）:

superpowers 技能依赖（通过参数启用）:

调用原则: 标注 "Skill tool 加载" 的依赖，必须在对应 Stage 开始时通过 Skill tool 加载完整技能内容，而非使用简化版指令。Agent 内加载指在 Agent prompt 中要求 Agent 自行调用 Skill tool。

迭代增强依赖（参数控制）:

核心架构

用户输入 (任务表述)
    │
    ▼
┌─────────────────────┐
│ Stage 1: Prompt 优化  │  --no-prompt 跳过
│   调用 /prompt 技能    │
└─────────┬───────────┘
          │ 优化后的任务表述
          ▼
┌─────────────────────┐
│ Stage 1.5: 需求探索   │  条件触发（3+ 不确定项时）
│   AskUserQuestion    │  参考 superpowers:brainstorming
└─────────┬───────────┘
          │ 明确后的任务表述
          ▼
┌─────────────────────┐
│ Stage 2: 深度思考     │  --think / --think-hard / --mermaid / --discuss
│   (可选预处理)        │  默认跳过，按需开启
└─────────┬───────────┘
          │ 深度分析结论
          ▼
┌─────────────────────┐
│ Stage 3: 确定性规划    │  --no-plan 跳过
│   EnterPlanMode(默认) │  --strict-plan 默认启用
│   + plan-quality 标准 │  --precise-plan 强制精确
│   planning-with-files │  --plan-dir 自定义目录
└─────────┬───────────┘
          │ task_plan.md / findings.md / progress.md
          ▼
┌─────────────────────┐
│ Stage 3.5: Plan Review│  --plan-review 启用（半自动）
│   独立 Agent 审查     │  --deep 时建议启用
│   (两个 Claude 模式)  │
└─────────┬───────────┘
          │ 审查报告 + 用户确认
          ▼
┌─────────────────────┐
│ Stage 3.6: 代码级细化 │  --code-plan 启用
│   superpowers:       │  需 flow-deep 依赖
│   writing-plans      │
└─────────┬───────────┘
          │ TDD 细化后的 plan
          ▼
┌─────────────────────┐
│ Stage 4: 并发执行     │  --no-multi 跳过(改为串行)
│   /multi-agent       │  含退回 Plan 协议
│   (异常→退回Stage3)  │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Stage 4.5: Agent 清理│  IN_TMUX 时执行
│   tmux + TaskStop    │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Stage 5: 完成验证     │  --no-verify 跳过
│   verification       │  默认启用
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Stage 5.5: 迭代优化   │  --iterate N 启用
│   auto-iterate       │  验证失败时触发
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Stage 5.7: Ralph Loop│  --ralph 启用（参数触发）
│   Stop Hook 强制持续  │  Stage 5.5 用完仍未达标时
└─────────┬───────────┘
          │
          ▼
      执行结果

Mermaid 输出规范: 输出 Mermaid 代码块后，应紧接着输出 ASCII 字符画版本。

轻量编排引擎。如需全量深度管道（含 superpowers 前置检查 + 强制深度思考），请使用 /flow-deep。

参数速查

/flow [options] <任务表述>

阶段控制:                          思考增强:
  --no-prompt   跳过 Stage 1         --think         Sequential Thinking (4K)
  --no-plan     跳过 Stage 3         --think-hard    Sequential Thinking (10K)
  --no-multi    跳过 Stage 4(串行)    --mermaid       Mermaid 图可视化
                                    --discuss       三角色讨论
Plan 质量:                          superpowers 技能:
  --strict-plan  Stage 3 进入       --code-plan   Stage 3.6 代码级细化
                 Plan Mode (默认开)  --tdd         Agent 注入 TDD
  --no-strict-plan 禁用 Plan Mode   --review      代码审查
  --precise-plan 强制精确 Plan       --compact     上下文 >60% 压缩
  --plan-review  Stage 3.5 审查
                 (两个 Claude 模式)
迭代增强:                           配置:
  --iterate N     Stage 5.5 迭代     --plan-dir <dir>  规划目录（多 feature 用 .plan-feat-<name>/）
  --guard <cmd>   迭代防回归         --agents <types>  Agent 类型
  --ralph         Stage 5.7 Ralph    --lang <zh|en>    输出语言
  --ralph-max N   Ralph 轮数(默认10) --dry-run         仅计划不执行
  --no-verify     跳过 Stage 5

预设 (互斥):
  --quick     ≡ --no-prompt --no-plan --no-multi
  --standard  完整三步流程（默认）
  --deep      ≡ --think --mermaid --discuss (+ 自动建议 --plan-review) (+ superpowers: dispatching-parallel-agents)

执行流程

前置处理

1. 解析参数: 从用户输入中提取 -- 参数和任务表述
2. 能力检测: 检查 ~/.claude/skills/auto-iterate/SKILL.md 是否存在，标记 iterate_available: true/false（影响 Stage 5.5 使用完整模式还是降级模式）
3. 确认任务: 向用户展示解析结果，确认任务范围和参数配置

/flow --think --plan-dir docs/plan 重构支付系统，支持多币种

解析结果:
  任务: 重构支付系统，支持多币种
  启用阶段: prompt优化 → 深度思考 → 规划 → 并发执行
  规划目录: docs/plan/
  思考模式: Sequential Thinking (4K)

Stage 1: Prompt 优化

调用: /prompt <任务表述>

输入: 用户的原始任务表述 输出: 优化后的任务表述（评分报告 + 优化版本）

行为:

• 使用 prompt 技能对任务表述进行评分和优化
• 将优化后的版本作为后续阶段的输入
• 如果评分 >= 8/10，提示用户原始表述已足够好，询问是否跳过

跳过条件: --no-prompt

Stage 1.5: 需求探索（条件触发）

触发条件: Stage 1 完成后，优化后的任务表述中存在 3+ 不确定项或明确度 < 7 的关键决策点。

完整协议（含触发条件、行为步骤、AskUserQuestion 示例）见 references/needs-exploration.md

核心行为: 识别不确定项 → 评分明确度 → 主动追问 → 合并结果 → 记录到 findings.md

追问要点: 问题要具体（"支持哪些币种？" 而非 "还有其他需求？"），每个问题提供 3-4 选项含推荐默认值。

跳过条件: 不确定项 < 3 或所有不确定项明确度 >= 7

Stage 2: 深度思考（可选）

输入: 优化后的任务表述

根据启用的参数执行不同的预处理：

--think / --think-hard

调用 Sequential Thinking MCP 进行结构化思考（6 个维度：任务分解、依赖分析、风险评估、资源需求、执行策略、Superpowers 技能匹配），完成后展示结论并记录到 findings.md。详见 references/stage2-details.md。

技能匹配确认钩子（第 6 维度完成后）:

• 如果第 6 维度匹配到 2+ 个 superpowers 技能，使用 AskUserQuestion 确认匹配结果
• 问题示例: "分析匹配到以下技能: TDD + 代码审查 + 并行分发。是否全部启用，还是选择性启用？"
• 用户可调整匹配结果后再进入 Stage 3

--mermaid

使用 mermaid 技能可视化任务结构（任务分解图 / 依赖关系图 / 执行流程图）。因终端无法渲染图形工具，输出遵循全局 CLAUDE.md Mermaid 图表规范（Mermaid 代码块 + ASCII 字符画双输出）。详见 references/stage2-details.md。

--discuss

三角色讨论模式，根据任务类型自动匹配角色，经两轮讨论后综合形成最佳方案，结果记录到 findings.md。详见 references/stage2-details.md。

Stage 3: 确定性规划

遵循: planning-with-files 模板格式 + references/plan-quality.md 质量标准

注意: --strict-plan 模式下，Plan Mode 内部无法调用 Skill tool，因此手动遵循 planning-with-files 的模板格式组织 plan 内容，而非调用该 skill。

--strict-plan 模式（默认启用）

核心理念: 进入 Claude Code 的 Plan Mode（只读沙箱），强制"先想后做"纪律。Plan Mode 中只能探索代码库和写 plan 文件，不能编辑代码，确保设计质量。

启用条件: 默认启用（--standard 和 --deep 预设自动包含） 跳过条件: --quick 预设 或 --no-plan

行为:

[Plan Mode 内部] — 调用 EnterPlanMode 进入只读沙箱:

1. 用 Glob/Grep/Read 探索代码库，理解现有结构
2. 基于优化后的表述和深度思考结论，设计实现方案
3. 将方案写入系统指定的 plan 文件（遵循 planning-with-files 模板 + plan-quality.md Checklist）

[Plan Mode 边界] — 调用 ExitPlanMode 提交 plan 供用户审批

[Plan Mode 外部] — 用户审批通过后:

1. 将审批通过的 plan 形式化为:

• task_plan.md — 分阶段任务计划（写入 --plan-dir 指定目录）
• findings.md — 研究发现
• progress.md — 执行进度追踪

1. 对生成的 plan 执行 plan-quality.md 中的 Quality Checklist 自检
2. 向用户展示质量评分，确认后进入 Stage 3.5

Plan Mode 的约束（系统级强制）:

• 可以: Read、Glob、Grep、AskUserQuestion、写 plan 文件
• 不可以: Edit、Write（项目文件）、Bash、修改代码库

为什么默认启用:

• Plan Mode 的审批环节（ExitPlanMode）确保 plan 质量，比单纯靠"自律"更可靠
• 只读沙箱防止"边想边改"的冲动，强制先完成设计再动手
• 用户可以在审批时直接修改 plan，比事后修正成本低得多

非 strict-plan 模式（--quick 时）

不进入 Plan Mode，直接用 planning-with-files 生成 plan 文件。适用于简单任务或已明确方案的场景。

规划要点（两种模式通用）:

• 每个 Phase 应标注可否并行
• Phase 间的依赖关系要明确
• 每个 Phase 要有明确的完成标准
• 确定性要求（--precise-plan 或 --deep 时强制）:
• 精确文件路径（创建/修改的具体文件）
• 行号范围或函数签名
• 变更内容描述（禁止 placeholder）
• 验证条件（命令 + 预期输出）
• 详见 references/plan-quality.md

质量评分: 生成 plan 后按 plan-quality.md 的评分标准自检，>= 8/10 合格

跳过条件: --no-plan

Stage 3.5: Plan Review — 两个 Claude 审查模式（可选）

触发条件: --plan-review 参数启用，或 --deep 时自动建议 参考文档: references/plan-review.md

核心理念: 用独立 Agent（全新上下文）审查 plan，消除"沉没成本偏差"——第一个 Claude 花了很多时间想方案，心理上不愿推翻，而审查 Agent 没有这个包袱。

行为（半自动模式）:

1. 读取 Stage 3 生成的 task_plan.md 全部内容
2. 启动一个独立 Agent（subagent_type: general-purpose, name: plan-reviewer）
3. Agent 以 Staff Engineer 角色审查 6 个维度:

• 架构合理性 / 遗漏边界情况 / 安全风险 / 性能影响 / Plan 假设验证 / 可执行性

1. Agent 返回审查报告（APPROVED / APPROVEDWITHNOTES / NEEDS_REVISION）
2. 暂停，向用户展示审查报告 ← 半自动: 等待用户确认
3. 用户决策:

• APPROVED → 继续 Stage 3.6
• APPROVEDWITHNOTES → 选择性采纳建议，更新 plan 后继续
• NEEDS_REVISION → 退回 Stage 3 修改 plan

1. 审查结果写入 findings.md 的 Plan Review 章节

自动建议条件（不自动执行，仅提示用户）:

• 改动影响 3+ 模块
• 涉及技术选型
• 有安全/数据风险
• plan 包含 5+ Phase

跳过条件: 不使用 --plan-review 参数且未接受建议

Stage 3.6: 代码级细化（可选）

触发条件: --code-plan 参数启用时 调用: superpowers:writing-plans 依赖声明: 读取 ~/.claude/skills/flow-deep/references/code-planning.md（agent_hint 格式、TDD 步骤模板）。需要用户已安装 /flow-deep skill，否则该功能不可用，应提示用户安装 flow-deep 后重试。

行为: 对每个含代码实现的 Phase 细化为 TDD 步骤（每步 2-5 分钟，含完整代码，无 placeholder）

默认: 跳过。仅 --code-plan 时启用。

Stage 4: 并发执行

调用: /multi-agent 技能（可选注入 superpowers 技能指令）

行为:

1. 读取 task_plan.md 中的任务分解
2. 识别可并行的子任务组
3. 为每个子任务分配合适的 Agent 类型
4. 按需注入技能指令（详细指令见 references/skill-routing.md）:

• --tdd: 代码实现 Agent 注入 TDD 工作流
• --review: 代码实现完成后触发审查
• --deep: 启用 dispatching-parallel-agents 并行分发

1. 生成可执行的 Agent Teams 方案
2. 并发启动 Agent 执行

Agent 分发方式（tmux 分屏优先，无 tmux 自动降级，全阶段通用）

完整规则（含 CRITICAL 检查清单、工具调用模板、Delegate 模式）见 references/agent-dispatch.md

首次分发前先跑 $TMUX 检测并显式写出判定行（跳过检测 ≠ NOTMUX）。核心约束: Agent(name) 唯一命名 + 同消息并行 ≤ 4 + Delegate 协议不变（TeamCreate/teamname 已废弃）| INTMUX 且 pane 正常 → 自动分屏可视化 + 即时清理 pane；NOTMUX 或 pane 故障 → 静默降级无分屏并发

串行替代: 当 --no-multi 时，在当前会话中按 task_plan.md 顺序逐步执行，每完成一个 Phase 更新 progress.md。

退回 Plan 协议（Stage 4 异常处理）

核心理念: 执行中遇到意外时，第一反应是"plan 哪里假设错了"，而不是"让我直接修"。

完整协议（含异常分类、Fallback 操作步骤、特殊情况处理）见 references/fallback-protocol.md

关键规则: 执行偏差 → 直接修复 | Plan 假设有误 → 触发 Plan Fallback（暂停→记录→分析→更新→确认→继续）| 同一 Phase 2 次 Fallback → 退回 Stage 2

跳过条件: --no-multi

Stage 4.5: Agent 与 Pane 清理

完整清理脚本（即时清理 + 孤儿清理 + 全局清理）见 references/cleanup-procedure.md

Stage 4 完成后执行三层清理: 即时清理（Agent completed → shutdown → kill pane）→ 孤儿清理（残留 pane）→ 全局清理（倒序 kill；TeamDelete 已废弃无需调用）

Stage 5: 完成验证

调用: superpowers:verification-before-completion（通过 Skill tool 加载完整技能）

完整验证协议（含行为步骤、铁律、证据要求）见 references/stage5-verification.md

铁律: No completion claims without fresh verification evidence. 禁止 "should work"、"probably"。

跳过条件: --no-verify

Stage 5.5: 迭代优化（条件触发）

触发条件（满足任一即触发）: --iterate N 参数 或 Stage 5 验证未达标（自动触发，默认 3 轮）

完整协议（含参数构造、渐进式 Guard、auto-iterate 集成、降级模式）见 references/stage55-iteration.md

调用: auto-iterate skill（如果可用）；否则使用内置降级模式（分析→变更→commit→验证→keep/revert）

跳过条件: 不使用 --iterate 参数且 Stage 5 全部达标

Stage 5.7: Ralph Loop 强制持续（参数触发）

触发条件: --ralph 参数启用 + Stage 5.5 迭代用完仍未达标 + Ralph Loop 插件已安装 调用: Ralph Loop 插件（Stop Hook 机制） 参考: ~/.claude/skills/flow-deep/references/ralph-integration.md

核心理念: Ralph Loop 通过 Stop Hook 拦截会话退出，注入一次性固定 prompt（含初始历史摘要 + 自主状态获取指令），在 auto-iterate 外层包裹"不达目的不罢休"的强制机制。

行为:

1. 检查 Ralph Loop 插件是否已安装（前置处理中已标记）
2. 不可用 → 提示用户安装 Ralph Loop 插件
3. 可用 → 构造一次性 prompt（含初始 TSV 历史 + "自行从 progress.md 读取最新状态"指令）
4. 调用 /ralph-loop 启动循环，使用 --completion-promise "FLOW_COMPLETE"
5. LLM 每轮自行读取 progress.md 获取最新迭代状态，执行 auto-iterate，运行 Stage 5 验证
6. 达标输出 <promise> 或到达 --ralph-max → 退出循环

参数:

• --ralph: 启用 Ralph Loop（flow 中为参数触发，非自动触发）
• --ralph-max N: Ralph 总轮数（默认 10）
• --no-ralph: 禁用（仅在与其他参数组合时有用）

跳过条件: 未使用 --ralph | Stage 5.5 全部达标 | Ralph Loop 插件未安装

1. tmux 全局清理（INTMUX 时）: shutdown 全部剩余 Agent → 倒序 kill 非 MAINPANE → 验证（TeamDelete 已废弃，无需调用）
2. 汇总所有 Agent 的执行结果
3. 更新 progress.md 和 task_plan.md 状态
4. 向用户展示最终结果和总结
5. 如有未完成的任务，提示后续步骤
6. 触发 Stage 5 完成验证（若 Stage 5 未执行则在此触发；--no-verify 可跳过）

使用示例

详细示例（标准流程 / 深度分析 / Plan Review 场景 / 常用参数组合）见 references/usage-examples.md

快速参考:

/flow --think --mermaid --plan-dir docs/plan 重构支付系统
→ Stage 1: 优化 → Stage 2: 思考+Mermaid → Stage 3: 规划 → Stage 4: 并发执行

通用参数行为

• `--compact`: 当上下文使用率 >60% 时，自动压缩中间结果（Sequential Thinking 输出摘要化、代码级计划保留 agent_hint 摘要）
• `--agents <types>`: 指定 Agent 类型（逗号分隔），覆盖 Stage 4 自动匹配的 subagent 类型。例如 --agents backend-developer,security-auditor
• `--lang <zh|en>`: 设置所有用户面向消息的输出语言。默认 zh
• `--dry-run`: 执行 Stage 1-3 后停止，不进入 Stage 4/5。用于预览计划输出
• `--no-strict-plan`: Stage 3 不进入 Plan Mode，直接用 planning-with-files 生成 plan（适用于简单任务或已明确方案的场景）

注意事项

• 每个阶段完成后，向用户展示简报并确认是否继续
• 如果某个阶段失败，不要自动跳过，而是报告错误并询问用户
• 三角色讨论中的角色选择应基于任务类型自动匹配，但允许用户调整
• Mermaid 图应聚焦于任务结构和依赖关系，不要过度美化
• 规划文件应使用 planning-with-files 的模板格式，保持兼容性
• Plan 质量: Stage 3 生成的 plan 应满足 references/plan-quality.md 的 Checklist，特别是 --precise-plan 或 --deep 时
• 退回 Plan 纪律: Stage 4 中遇到 Plan 假设有误时，不要"硬推"就地修复，而应触发 Fallback 协议（详见 references/fallback-protocol.md）
• Plan Review 半自动: 审查 Agent 只输出报告，不自动修改 plan。用户确认后才继续

平台兼容

非 Claude Code 环境（如 Codex / dsh）运行时，先读 references/codex-compat.md 获取机制映射与降级指令。Claude Code 环境忽略本节。