模式2：润色成 Workflow 编排规格

这个模式在做什么

产出一份 workflow-spec/v1——规格，不是可运行的 JS。运行时的 Claude 拿着它、面对真实仓库和当前 budget，把它编译成 pipeline() / parallel() 脚本。

为什么不让本模式直接吐 JS：

1. meta 必须是 PURE LITERAL（不能写 phases: WORK_ITEMS.map(...)），生成 JS 就得在润色时刻把工作清单烤死进 meta——而清单恰恰是润色阶段还不知道的东西，方向反了。
2. 中文里的 `、${、\ 拼进模板字符串会断串、进插值、或静默变转义（\d 变成 d）。本机 12 个真实 workflow script 全是 agent(\${COMMON}...${w.prompt}`)` 这个形态。
3. 规格 + 脚本 = 两份真相，改一份就漂移。

字段顺序 = 执行顺序，所以 Claude 的编译退化成填空，不是翻译。规定顺序，而不是生成代码。

1. 取原文（三路，依次尝试）

1. 有参数 → 直接用参数（$ARGUMENTS 逐字保留换行、引号、反引号）
2. 无参数但输入以 @ 开头 → cat 该路径
3. 都没有 → pbpaste

三者皆空则打印用法后退出，不要 pbcopy。

2. 幂等

产物第一行固定：<!-- polished-by: prompt-polish mode=flow v1 -->

输入已含此行 → 不重写、不碰剪贴板，只输出「已符合 v1 规格，差异如下：」+ 逐条差异。 没有这个标记，模型无法区分「待润色的原始需求」和「我上次吐的 spec」，结果是 spec 外面再包一层 spec。

3. 语言镜像

输出语言 = 输入语言。YAML 的 key 固定英文（机器消费，下游脚本按 key 取值），value 跟随输入语言。

4. 改写规则

• 保留用户原话里的每一条祈使/否定句（要/必须/不要/禁止/先…再…/别/未经允许不要），逐字搬运，搬进 non_goals 或对应 work item 的 prompt。
• 不发明用户没提的需求。 唯一合法的四种填空：目标文件路径 / 技术栈 / 测试命令 / 验收阈值。
• 形容词 → 可观察动作。 黑名单：优化 完善 改进 提升 更好 合理 优雅 高效 简洁 干净 清晰 健壮 稳定 成熟 最佳 完美 流畅 全面 彻底 深入 系统性地 梳理 治理 收敛 尽量 尽可能 适当 酌情 视情况 建议 尝试 探索 / clean elegant idiomatic robust scalable optimal better properly correctly thoroughly polished comprehensive sensible reasonable appropriate seamless
• 验证命令不得依赖工作区初始干净。「git diff → 无输出」式期望在脏工作区必挂（让它为空的唯一办法是回滚）。改用基线对比（开工先贴基线，写「与基线逐行一致」；只用于输出稳定的命令）或计数形式（wc -l 输出为 0）。
• 规模自适应：输入本身是单人可完成的动作 → 见 §8 降级。输入已隐含多角度（"调研"、"全面审查"、"对比几种方案"）才走本模式。

5. 输出：workflow-spec/v1

产物 = 幂等标记行 + 裸 YAML。不要 yaml 围栏——围栏本身就是反引号，撞 §7 禁令。下面这块围栏只是本文件的展示，不是产物的一部分。

<!-- polished-by: prompt-polish mode=flow v1 -->
# workflow-spec/v1

goal: |                     # 一句话目标
shared_brief: |             # ≤200 字；编排器必须【逐字】prepend 到每个 work item，禁止 agent 自行重建背景
non_goals:                  # inline 进每一个 work item
  - 不做架构重构
  - 不改 API 契约

args:                       # 全局；same script + same args → 100% cache hit
  as_of: "2026-10"          # 沙箱无 Date.now()/Math.random()，时间截止必须显式传
  coverage_cap: 18

phases: [枚举, 深读, 对抗校验]   # = stages[].name 按顺序，再加 verification 的阶段名（mode 为 none 时省略）；与 meta.phases[].title 逐字一致

stages:                     # 线性 stage 链（不用 DAG，见 §6）。stage 之间默认 barrier
  - name: 枚举              # → meta.phases[].title 与 agent({phase})，两处同名
    effort: low             # 本 stage 全部 item 的默认 effort
    items:                  # 静态清单。与 items_from 二选一
      - id: scan-oss        # → opts.label；也是去重键
        effort: low         # 覆盖 stage 级
        isolation: worktree # 仅当与同批并行 item 会改同一批文件时才写
        prompt: |           # → agent() 第一参数，必须自包含
        schema:             # → agent({schema})，真 JSON Schema：根 type:'object'，required ⊆ properties
          type: object
          properties: { items: { type: array, items: { type: object } } }
          required: [items]
  - name: 深读
    items_from: 枚举        # 动态扇出：上游每个产物出一个 agent，上游收齐后才开跑
    prompt: |               # 模板；编排器把该候选的 JSON 追加到末尾，再交给 agent()
    schema:                 # 写在 stage 级，本 stage 全部 item 共用
      type: object
      properties: { notes: { type: string } }
      required: [notes]

verification:               # 编排器写成脚本控制流，不是 prompt 文本
  mode: adversarial         # none | judge-panel | adversarial
  lenses: [正确性, 可复现性]
  pass_rule: 至少 1 个 lens 判 REFUTED/UNCERTAIN → 该断言降级为「未经证实」，从报告中移除

stop_conditions:            # 计数型，不是时间型；编排器写成早退分支
  - 合并后候选清单为空 → 立即返回 report_md 为「未找到」且 items 为空数组，跳过后续阶段
  - 候选清单 > coverage_cap → 取前 N，并 log 丢弃的个数与名字；静默截断视为规格违规

budget: {agents_max: 40}    # 规模上限。编排器用普通 JS 计数器守——budget 是 token 预算，不是 agent 数

output:                     # → 脚本 return 的形状
  report_md: string
  dropped_count: number     # 被截断丢弃的条目数；>0 时必须在报告末尾声明

6. 字段准入规则

每个字段必须落在三类之一，三类都不是 → 删。

1. 映射到一个 Workflow 原语：prompt → agent() 第一参数；id → opts.label；effort → agent({effort})；isolation → agent({isolation})；schema → agent({schema})；args → 脚本的 args 全局。
2. 编排器必须逐字 inline 进 agent prompt 的文本：shared_brief、non_goals、prompt 模板正文。
3. 编排器必须写成的脚本控制流：verification（多 lens 投票与 pass_rule 的分支）、stop_conditions（早退分支）、budget.agents_max（普通 JS 计数器守卫）、output（return 的形状）。

扇出形态由 items / items_from 二选一决定，没有第三个字段：

• items: 静态清单——工作项现在就知道，逐项写自包含的 prompt。
• items_from: <上游 stage 名>——工作项由上游产物决定（这正是不出 JS 的理由）。上游收齐后逐项扇出；prompt 写在 stage 级当模板，编排器把该候选的 JSON 追加到末尾。
• 合成步（fan-in）走 items 的静态单 item。「把上游全部产物收拢成一份结论」不是逐项扇出——items_from 给每个上游产物各开一个 agent，表达不了收拢。写成单 item，prompt 里写明「编排器把上游 <stage 名> 的全部产物逐条追加到本 prompt 末尾」，上游 stage 的 barrier 保证收齐。

stage 之间默认 barrier（await 完上一个再进下一个）。只有相邻两个 stage 的 items 一一对应时，编排器才可以把它们合成一个 pipeline(items, s1, s2) 省掉 barrier——pipeline 是跨 stage 共享同一批 items 的组合子，不是单个 stage 的形状。

stages[].name 就是 phase 名：必须出现在 phases 列表里，且与 meta.phases[].title 逐字一致。编排器在 agent() 上写 opts.phase = stage.name，不要用全局 phase()——pipeline() / parallel() 内部调用全局 phase() 有竞态。

effort 只有五个取值：low | medium | high | xhigh | max。机械阶段用 low，verify / judge 阶段才上高档。写在 stage 级是默认，item 级可覆盖。

isolation: worktree 的触发条件：本 item 与同批并行的其它 item 会改同一批文件、不隔离就冲突。只写文件但不冲突，或全 stage 只有一个写文件的 item，都不要写——每个 worktree 是 200–500ms 加一份磁盘。

只用线性 stages，不用 DAG。 运行时只有两个组合原语：pipeline（跨 stage 共享同一批 items，stage 间无 barrier）和 parallel（barrier）。带 fan-in 的 DAG（A→C、B→C）在这两个原语里不可表达——写成 DAG 只会让 Claude 悄悄线性化，静默丢掉全部并行度。所以 depends_on 这个字段不存在，stage 之间就是线性推进。

明确不收的字段：shape（items/items_from 已经把形态说完了，这个字段信息量为零还误导编译）、逐 item 的 model（强制编排器二次判断一个本该继承的值；文档原话 "Default to omitting it"）、逐 item 的 agentType（把 agent 注册表泄漏进规格）、depends_on（见上）、timeline / milestones / owner / risk / rollback / persona / tone / success_metrics（折叠进 stop_conditions）、code_skeleton / template、open_questions（折叠进 stop_conditions 第一条：非空即 blocked_on，不要开跑，先问用户）。

7. 硬禁令：反引号、${、反斜杠

产物正文内不得出现 `、${、\。需要代码片段写进「」；路径用正斜杠；正则用字符类（用 [0-9] 代替 \d）。

理由：prompt 原文会被拼进 Workflow 脚本。模板字面量里 ` 断串、${ 进插值、\ 变转义——\d 静默变成 d，比语法错误更难发现。产物也不要 yaml 围栏，围栏本身就是反引号。

自检就是 §9 里的 grep 那一行。它有输出就先改产物，不要带着禁用字符复制。

8. 单人任务降级

识别：估算出的 work item ≤1，或输入动词是单人可完成的动作（改个 typo、调个参数、补一行日志）。

行为：输出模式1 的产物（照 ${CLAUDE_PLUGIN_ROOT}/skills/goal/SKILL.md §5 的骨架构造，用它的 §7 校验并复制），前置一行说明：

这个任务不需要扇出（估算 work item = 1），已降级为 /goal 格式。

不输出 yaml 规格，产物按 mode=goal 标记。§7 的禁令不适用于降级产物——反引号是 goal 的判据锚点。避免「把一句话膨胀成八段文档」——执行者读 60 行才发现要做一件事。

9. 校验并复制（顺序不可颠倒）

Bash 工具不跨调用保留变量，$SPEC 这类名字不存在——必须在同一条命令里用 heredoc 赋值，再自检、复制：

SPEC=$(cat <<'PPEOF'
<!-- polished-by: prompt-polish mode=flow v1 -->
# workflow-spec/v1
（产物全文，照 §5 的字段顺序）
PPEOF
)
grep -n '`\|\${\|\\' <<< "$SPEC" && { echo "有禁用字符，修掉再复制"; exit 1; }
pbcopy <<< "$SPEC"

定界符 PPEOF 在产物里出现就换一个。grep 有输出说明 §7 的禁令被破了，先改产物再回来。

只回一行：

已复制 N 字到剪贴板（workflow-spec/v1）。下一步：让 Claude 照这份规格编译成 Workflow 脚本。