maestro-universal-workflow

<purpose>
Dynamic workflow generator: scan library for matches or generate task-specific Workflow scripts
on-the-fly with adversarial patterns. Scripts persist at `~/.maestro/workflows/dynamic/uwf-*.js`.
</purpose>

<context>
$ARGUMENTS — intent text with optional flags.

**Parse:**
```
--name <slug>     → 指定生成脚本名（默认从 intent 自动生成）
--depth <level>   → shallow | standard | deep（默认 standard）
--dry-run         → 只生成脚本，不执行
--from <script>   → 基于已有脚本进行修改（uwf-xxx 或 wf-xxx）
--resume <runId>  → 恢复之前的运行（透传给 Workflow）
Remaining         → intent
```

**Library locations:**
- Fixed scripts: `~/.maestro/workflows/swarm/wf-*.js`
- Dynamic scripts: `~/.maestro/workflows/dynamic/uwf-*.js`
</context>

<state_machine>

<states>
S_PARSE       — 解析参数和意图                     PERSIST: —
S_SCAN        — 扫描现有 workflow 库匹配            PERSIST: —
S_DECIDE      — 用户选择：复用现有 / 生成新脚本       PERSIST: —
S_DESIGN      — 分析任务、设计工作流结构              PERSIST: —
S_GENERATE    — 生成脚本 → 写入文件 → node --check 验证  PERSIST: uwf-{slug}.js
S_EXECUTE     — 调用 Workflow 工具执行               PERSIST: —
S_PERSIST     — 保存脚本到 dynamic/ 目录              PERSIST: —
</states>

<transitions>

S_PARSE:
  → S_SCAN      WHEN: intent parsed                 DO: A_PARSE_ARGS
  → END         WHEN: no intent

S_SCAN:
  → S_DECIDE    WHEN: matches found                 DO: A_SCAN_LIBRARY
  → S_DESIGN    WHEN: no matches                    DO: A_SCAN_LIBRARY

S_DECIDE:
  → S_EXECUTE   WHEN: user picks existing script    DO: —
  → S_DESIGN    WHEN: user wants new script         DO: —
  → S_DESIGN    WHEN: --from specified              DO: —

S_DESIGN:
  → S_GENERATE  DO: A_DESIGN_WORKFLOW

S_GENERATE:
  → S_EXECUTE   WHEN: Write + node --check pass AND NOT --dry-run  DO: A_GENERATE_SCRIPT
  → S_PERSIST   WHEN: --dry-run (file already written)             DO: A_GENERATE_SCRIPT
  → S_GENERATE  WHEN: node --check fails (retry ≤2)               DO: A_GENERATE_SCRIPT (fix & retry)
  → END         WHEN: node --check fails after 2 retries          DO: report E003

S_EXECUTE:
  → S_PERSIST   WHEN: workflow completed             DO: A_EXECUTE_WORKFLOW
  → END         WHEN: workflow failed

S_PERSIST:
  → END         DO: A_PERSIST_SCRIPT

</transitions>

<actions>

### A_PARSE_ARGS

1. 提取 flags: `--name`, `--depth`, `--dry-run`, `--from`, `--resume`
2. 剩余文本作为 intent
3. depth 默认 `standard`
4. 若有 `--resume`，跳到 S_EXECUTE（直接恢复）
5. 若有 `--from`，定位源脚本路径

### A_SCAN_LIBRARY

扫描两个目录，读取每个 `.js` 文件的 `meta` 块提取 `name`、`description`、`whenToUse`：

1. **Fixed scripts**: 展开 `~/.maestro/workflows/swarm/wf-*.js` 为绝对路径
   - Glob 查找所有匹配文件
   - 读取每个文件前 10 行，提取 `meta.name`、`meta.description`、`meta.whenToUse`
2. **Dynamic scripts**: 展开 `~/.maestro/workflows/dynamic/uwf-*.js`
   - 同上
3. **匹配评分**：对每个脚本，评估其 description/whenToUse 与 intent 的语义相关度
4. **输出**：
   - 匹配度 > 70% 的脚本列表（最多 3 个）
   - 每个列出：name、description、scriptPath、匹配理由
   - 无匹配则直接跳 S_DESIGN

若有匹配，用 AskUserQuestion 让用户选择：
- 选项 1-3: 使用现有脚本（附 preview 显示脚本 meta）
- 最后选项: "生成全新脚本"

### A_DESIGN_WORKFLOW

分析任务，确定工作流结构。这是核心设计步骤。

**Step 1 — 任务分解**

将 intent 分解为：
```
work_items: 需要完成的具体工作单元
  - { id, description, type: 'explore'|'analyze'|'create'|'verify'|'decide' }
decision_points: 需要做出判断的节点
  - { id, question, type: 'go-nogo'|'pass-fail'|'select-best'|'resolve-conflict'|'assess-quality' }
data_flow: 数据在工作单元间如何流动
  - { from, to, data_shape }
```

**Step 2 — 阶段编排**

将 work_items 组织为执行阶段：
```
phases: [
  { title, work_items[], parallel: true|false },
  ...
]
```

规则：
- 无依赖的 work_items 放同一阶段（parallel）
- 有依赖的放后续阶段
- 每个 decision_point 后紧跟一个对抗决策阶段

**Step 3 — 对抗模式选择**

根据 decision_point.type 和 --depth 选择对抗模式（参考 ADVERSARIAL_PATTERNS）：

| decision_type | shallow | standard | deep |
|--------------|---------|----------|------|
| go-nogo | 1 skeptic | 3-way advocacy + referee | cross-verify + 3-way advocacy + meta-skeptic |
| pass-fail | 1 challenger | prosecutor/defender/judge | cross-verify + prosecutor/defender + 3-vote |
| select-best | 1 critic | N proposals + judge panel | N proposals + judge + 3-critic challenge |
| resolve-conflict | 1 mediator | 3 philosophy proposals + arbitrator | 3 proposals + arbitrator + meta-skeptic |
| assess-quality | 1 skeptic | 3-vote (strict/lenient/objective) | cross-verify + 3-vote + meta-skeptic |

**Step 4 — Schema 设计**

为每个 agent 调用设计 JSON Schema：
- 工作 agent: 任务特定 schema
- 对抗 agent: 使用标准对抗 schema（见 ADVERSARIAL_PATTERNS）

**Step 5 — 产出蓝图**

```
blueprint: {
  name: 'uwf-{slug}',
  description: string,
  phases: [{ title, detail }],
  agents: [{ id, prompt_outline, schema_name, agentType?, phase }],
  adversarial_gates: [{ decision_id, pattern, agents[] }],
  estimated_agent_count: number,
}
```

向用户展示蓝图摘要，包含预估 agent 数量。
若 `--dry-run` 则在 S_GENERATE 后停止。

### A_GENERATE_SCRIPT

根据蓝图生成完整的 JavaScript 脚本。**先写文件，再通过 scriptPath 执行**（避免内联 script 字符串的编码/转义问题）。

若 `--from` 指定了基础脚本，先 Read 源脚本，然后在其基础上修改。

**脚本结构模板：**

```javascript
export const meta = {
  name: '{blueprint.name}',
  description: '{English description}',
  whenToUse: '{English usage scenario}',
  phases: [
    { title: '{EnglishTitle}', detail: '{English detail}' },
  ],
}

// --- Schemas (top-level constants, never inline) ---
const WORK_SCHEMA = { type: 'object', properties: { ... }, required: [...] }
const CHALLENGE_SCHEMA = { ... }

// --- Args ---
const target = args?.target || 'default'

// --- Phase 1: {title} ---
phase('{title}')
const results = await parallel([
  () => agent('prompt text', { label: 'work:1', phase: '{title}', schema: WORK_SCHEMA }),
])

// --- Phase 2: Adversarial Gate ---
phase('{adversarial_phase_title}')
// 对抗模式代码 — 从 ADVERSARIAL_PATTERNS 模板生成

return { ... }
```

**生成规则（必须全部遵守）：**

| # | 规则 | 原因 |
|---|------|------|
| 1 | **纯 JavaScript** — 无 TypeScript 类型注解（`: string`、`interface`、泛型） | 解析器不支持 TS |
| 2 | **meta 块全英文** — `name`、`description`、`whenToUse`、`phases[].title/detail` 只用 ASCII 字符 | 中文在 script 字符串序列化时触发 `\uXXXX` 解析错误 |
| 3 | **禁用 API** — 不用 `Date.now()`、`Math.random()`、无参 `new Date()` | 破坏 resume 缓存匹配 |
| 4 | **Schema 独立声明** —