maestro-flow 0.4.19 → 0.4.21

package/.agents/skills/maestro-grill/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: maestro-grill
+description: Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming
+argument-hint: "<topic|plan> [-y] [-c] [--from <source>] [--depth shallow|standard|deep]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Socratic stress-testing of a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time — challenging vague terminology against existing code, probing edge cases with concrete scenarios, and verifying assumptions with code evidence. Produces a verified context package (grill-report.md + terminology.md + context-package.json) for downstream brainstorm/analyze/roadmap consumption.
+
+Positioned BEFORE brainstorm in the pipeline: grill stress-tests and sharpens; brainstorm generates and elaborates.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/grill.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstream input.
+
+**Mode selection:**
+- **Interactive mode** (default): Topic text triggers full Socratic grilling with user Q&A
+- **Auto mode** (`-y`): Code exploration answers questions instead of the user
+- **Resume mode** (`-c` or `--session ID`): Continue from a previous grill session
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — CLI exploration replaces human answers
+- `-c` / `--continue`: Resume from last grill session
+- `--session ID`: Resume specific session
+- `--depth shallow|standard|deep`: Branch count 3/5/8 (default: standard)
+- `--from <source>`: Load upstream material (`blueprint:ID`, `@file`, or path)
+
+**Output directory**: `.workflow/scratch/{YYYYMMDD}-grill-{slug}/`
+**Produced files**: `grill-report.md`, `terminology.md`, `context-package.json`
+
+### Role Knowledge
+`maestro wiki search "{topic keywords}"` → load relevant entries before grilling.
+`maestro spec load --category arch` → load architecture constraints.
+</context>
+
+<interview_protocol>
+Grill the user relentlessly until every branch of the decision tree is walked. This is NOT a menu-driven interview — it is adversarial Socratic questioning. Active only in interactive mode; skip when `-y/--yes` or `-c/--continue`.
+
+Core protocol:
+- **One question per turn**. Each question probes ONE specific aspect. Never ask compound questions.
+- **Code-grounded**: Before asking, search the codebase for evidence. Use findings to sharpen the question or challenge the user's answer. Never ask what code can verify — search first, then confront.
+- **Escalating depth**: Start with scope boundaries, progress to data model, edge cases, failure modes. Each branch goes basic → specific → adversarial.
+- **Immediate writeback**: After each answered question, immediately append the Q&A + decision to `grill-report.md`. Do NOT batch — partial progress must be on disk before the next question.
+- **Challenge contradictions**: If an answer conflicts with code evidence or a prior answer, immediately surface the contradiction and demand resolution.
+- **Terminology enforcement**: When the user uses a term that conflicts with codebase naming, challenge it immediately. Propose the code-consistent alternative. Update `terminology.md` as terms crystallize.
+
+Question framing rules:
+- Reference specific code findings: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+- Use concrete scenarios: "What happens when a user does {action} while {condition} is true?"
+- Probe boundaries: "You said {X} is in scope — does that include {edge_case}, or is that separate?"
+- Challenge scale: "This touches `{table}` — at 10x current data volume, which query breaks first?"
+
+Branch walking order: Scope & Boundaries → Data Model & State → Edge Cases & Failure Modes → Integration & Dependencies → Scale & Performance → Security & Access Control → Observability & Operations → Migration & Rollback. Number of branches determined by `--depth`.
+
+Exit: When all depth-selected branches are fully walked (every question answered or explicitly deferred), finalize the report and generate context-package.json.
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/grill.md' completely.
+
+**Next-step routing on completion:**
+
+Standard routing:
+- Need multi-role elaboration → invoke_skill({ skill: "maestro-brainstorm", args: "{topic} --from grill:{artifact_id}" })
+- Need deep technical analysis → invoke_skill({ skill: "maestro-analyze", args: "{topic} --from grill:{artifact_id}" })
+- Scope is clear, ready for roadmap → invoke_skill({ skill: "maestro-roadmap", args: "--from grill:{artifact_id}" })
+- Need formal spec package → invoke_skill({ skill: "maestro-blueprint", args: "--from grill:{artifact_id}" })
+
+Resume routing:
+- More branches to walk → invoke_skill({ skill: "maestro-grill", args: "{topic} -c" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No topic/plan and no --from/--continue flag | Prompt user for topic text |
+| E002 | error | --session ID not found | Show available sessions |
+| W001 | warning | Codebase scan failed or returned empty | Continue without code grounding, note limitation |
+| W002 | warning | CLI exploration timeout in auto mode | Skip question, mark as open |
+| W003 | warning | Max branch depth reached without resolution | Force synthesis, offer continuation |
+</error_codes>
+
+<success_criteria>
+- [ ] Interactive mode: all depth-selected branches walked (shallow=3, standard=5, deep=8)
+- [ ] Each branch has >= 2 question-answer pairs with evidence or explicit user input
+- [ ] `grill-report.md` written with Branch Log table, all Q&A entries, synthesis section
+- [ ] `terminology.md` written with >= 5 terms, code references where applicable
+- [ ] Every locked decision has evidence (code reference or explicit user confirmation)
+- [ ] Contradictions between answers and code surfaced and resolved (or logged as risks)
+- [ ] Risk register captures all unresolved tensions
+- [ ] `context-package.json` generated with schema "context-package/1.0"
+- [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
+- [ ] Session sealed via finish-work
+</success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+</on_complete>

package/.agents/skills/maestro-plan/SKILL.md

@@ -75,6 +75,10 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/plan.md' completely.
 
+### P3 Agent Constraint (MANDATORY)
+
+Main flow **MUST** spawn a planner agent (Agent tool) for P3 planning — inline planning by main flow is FORBIDDEN. The agent produces both `plan.json` and `.task/TASK-*.json` files. Main flow only passes context and validates output.
+
 ### Codebase Docs Loading (P1 addition)
 
 During P1 Context Collection, after loading context files, load codebase documentation if available:

package/.agents/skills/maestro-ralph/SKILL.md

@@ -131,20 +131,20 @@ S_INFER:
 
 S_RESOLVE_SCOPE:
   → S_QUALITY_MODE  DO: A_RESOLVE_SCOPE_VERDICT
-                     GUARD: position ∈ {brainstorm, blueprint, init} → skip (scope_verdict = null)
+                     GUARD: position ∈ {grill, brainstorm, blueprint, init} → skip (scope_verdict = null)
 
 S_QUALITY_MODE:
   → S_PLANNING_MODE DO: A_DETERMINE_QUALITY_MODE
 
 S_PLANNING_MODE:
   → S_DECOMPOSE     DO: A_DETERMINE_PLANNING_MODE
-                     GUARD: lifecycle_position ∈ {brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
+                     GUARD: lifecycle_position ∈ {grill, brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
 
 S_DECOMPOSE:
   → S_BUILD_CHAIN   DO: A_DECOMPOSE_TASKS
                      GUARD: broad intent → MUST clarify boundary even if auto_confirm
                      GUARD: narrow intent → auto-derive, skip questions
-                     GUARD: position ∈ {brainstorm, blueprint, init} → skip decomposition
+                     GUARD: position ∈ {grill, brainstorm, blueprint, init} → skip decomposition
 
 S_BUILD_CHAIN:
   → S_CREATE_SESSION DO: A_BUILD_STEPS
@@ -244,6 +244,7 @@ resolve_milestone(phase_number):
 
 | Pattern | Position |
 |---------|----------|
+| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时跳过，直接 `brainstorm`**） |
 | brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
 | blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
 | broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
@@ -264,7 +265,7 @@ resolve_milestone(phase_number):
 | `phase_is_new == true` (新 phase) | `analyze` |
 | no milestones AND no roadmap.md AND has analyze macro artifact | `roadmap` |
 | no milestones AND no roadmap.md AND no analyze artifact | `analyze-macro` |
-| `phase == null` (brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
+| `phase == null` (grill/brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
 | phase 已存在 + 无任何 artifact | `analyze` |
 | phase 已存在 + 最新 artifact = analyze | `plan` |
 | phase 已存在 + 最新 artifact = plan | `execute` |
@@ -319,7 +320,7 @@ resolve_milestone(phase_number):
 
 | Condition | Mode | Reason |
 |-----------|------|--------|
-| lifecycle_position ∈ {brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
+| lifecycle_position ∈ {grill, brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
 | `phase_is_new == true` | `independent` | 新 phase 尚无里程碑上下文 |
 | intent 显式指定 phase 编号（如 "phase 2"、"P3"） | `independent` | 用户明确针对单个 phase |
 | milestone 仅含 1 个 phase（读 state.json） | `independent` | 统一无意义 |
@@ -382,7 +383,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 
 | Stage | invoke_skill(independent) | invoke_skill(unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
-| brainstorm | `maestro-brainstorm "{intent}"` | *(same)* | — | all |
+| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**skip when auto_confirm**) |
+| brainstorm | `maestro-brainstorm "{intent}" --from grill:{grill_id}` *(if grill ran)* / `maestro-brainstorm "{intent}"` *(otherwise)* | *(same)* | — | all |
 | blueprint | `maestro-blueprint "{intent}"` | *(same)* | — | all |
 | init | `maestro-init` | *(same)* | — | all |
 | analyze-macro | `maestro-analyze "{intent}"` | *(same)* | `post-analyze-scope` | all |
@@ -407,6 +409,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 1. **起点**：从 `session.lifecycle_position` 开始
 2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
+3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
 6. **终点硬约束**：chain 以 `milestone-complete` 结尾
@@ -743,7 +746,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Phase 先于 position 解析；phase_is_new 标记写入 session
 - [ ] D-007 反查：phase 数字 → `session.milestone`，禁止读 current_milestone；写入 step.milestone_id
 - [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
-- [ ] Intent overrides 识别 brainstorm / blueprint / analyze-macro
+- [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
+- [ ] auto_confirm=true 时 grill stage 跳过（交互式拷问不支持自动模式）
 - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
 - [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(phase)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
 - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路

package/.agents/skills/maestro-ralph-execute/SKILL.md

@@ -54,6 +54,7 @@ HARD RULES:
 6. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
 7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
 8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
+9. **CLI 输出禁止截断** — `maestro ralph next` 的 stdout 包含完整 skill prompt，必须全量捕获。**严禁** `| head`、`| tail`、`2>&1 | head -N` 等任何截断管道。Bash timeout 可加长但不可截断输出
 </invariants>
 
 <state_machine>
@@ -157,7 +158,7 @@ Write enriched args back to status.json.
 
 ### A_EXEC_STEP
 
-1. **Load** — `shell("maestro ralph next")`
+1. **Load** — `shell("maestro ralph next --session <session_id>")` — **必须全量捕获 stdout，严禁 `| head`/`| tail` 等截断管道**（stdout 含完整 skill prompt，截断会导致执行内容不完整）
    - 退出码 0 → 按 stdout 内联执行
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用

package/.agents/skills/maestro-swarm-workflow/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: maestro-swarm-workflow
+description: Parallel workflow accelerator — route intent to fixed Workflow scripts for multi-agent concurrent execution
+argument-hint: "<intent> [--script <name>] [--dims <d1,d2>] [--roles <r1,r2>] [--count N] [--tier quick|standard] [--resume <runId>]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - workflow
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Parallel accelerator layer for maestro commands. Routes user intent to pre-built Workflow scripts
+that leverage `parallel()` / `pipeline()` for multi-agent concurrent execution.
+
+Complements maestro-ralph (sequential decision chain) — ralph manages state + decisions,
+swarm-workflow provides parallel compute bursts within individual steps.
+
+Scripts: `~/.maestro/workflows/swarm/wf-*.js`
+
+| Script | Accelerates | Adversarial Pattern |
+|--------|-------------|---------------------|
+| `wf-analyze` | maestro-analyze | explore → 6-dim scoring → **skeptic cross-verify** → **3-way advocacy (go/no-go/conditional) + referee** |
+| `wf-brainstorm` | maestro-brainstorm | multi-role analysis → **3-specialist cross-review** → **3-proposal competition** → **arbitrator** |
+| `wf-review` | quality-review | 6-dim scan → **3-vote adversarial verify (prosecutor/defense/judge)** → **3-perspective report + arbitrated verdict** |
+| `wf-verify` | maestro-verify | 3-layer + antipattern + convergence → **prosecutor vs defender debate** → **judge verdict** |
+| `wf-grill` | maestro-grill | explore → parallel branch stress → **meta-skeptic challenge** → **3-vote verdict (optimist/pessimist/realist)** |
+| `wf-plan` | maestro-plan | parallel context → **3-strategy competing proposals** → **judge panel scoring** → **3-critic adversarial check** |
+| `wf-execute` | maestro-execute | wave-based parallel execution → **adversarial convergence spot-check** → **3-vote status determination** |
+| `wf-milestone-audit` | maestro-milestone-audit | parallel 3-dim audit → **adversarial dimension challenge** → **3-vote verdict (strict/lenient/objective)** |
+
+Integration modes:
+- **Standalone**: `/maestro-swarm-workflow "analyze auth module"` — direct invocation
+- **Ralph step**: ralph chain 中某个 step 可指定 `swarm-workflow` 作为加速执行器
+- **Chained**: 输出 JSON 可被下游命令通过 `--from` 消费
+</purpose>
+
+<context>
+$ARGUMENTS — intent text with optional flags.
+
+**Parse:**
+```
+--script <name>  → 强制指定脚本（wf-analyze, wf-brainstorm, wf-review, wf-verify）
+--dims <d1,d2>   → 限定分析维度（analyze: architecture,complexity,patterns,risk,testability,performance）
+--roles <r1,r2>  → 限定角色（brainstorm: system-architect,product-manager,test-strategist,ux-expert,security-analyst,data-architect）
+--count N        → 角色数量（brainstorm 默认 3）
+--tier <level>   → review 层级（quick=2 维度, standard=4 维度）
+--resume <runId> → 从之前的 workflow 运行恢复（增量重跑）
+Remaining        → intent
+```
+
+**Script inventory** (`~/.maestro/workflows/swarm/`):
+
+| Script | args 接口 |
+|--------|-----------|
+| `wf-analyze` | `{ target, scope, context, phase?, dimensions? }` |
+| `wf-brainstorm` | `{ topic, context, count?, roles? }` |
+| `wf-review` | `{ target, scope, specs?, tier?, dimensions? }` |
+| `wf-verify` | `{ goals, plan_dir?, scope?, task_files?, must_haves?, skip_antipattern? }` |
+| `wf-grill` | `{ topic, context?, depth?: "shallow"\|"standard"\|"deep" }` |
+| `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
+| `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
+| `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE        — 解析参数和意图                    PERSIST: —
+S_ROUTE        — 路由到目标脚本                    PERSIST: —
+S_CONTEXT      — 组装 context payload             PERSIST: —
+S_DISPATCH     — 调用 Workflow 工具                PERSIST: —
+S_INGEST       — 处理返回结果                      PERSIST: —
+S_FALLBACK     — 无法路由                         PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_ROUTE     WHEN: intent parsed                DO: A_PARSE_ARGS
+  → S_FALLBACK  WHEN: no intent
+
+S_ROUTE:
+  → S_CONTEXT   WHEN: script resolved              DO: A_ROUTE_SCRIPT
+  → S_FALLBACK  WHEN: ambiguous intent              DO: ask_user
+
+S_CONTEXT:
+  → S_DISPATCH  DO: A_ASSEMBLE_CONTEXT
+
+S_DISPATCH:
+  → S_INGEST    WHEN: workflow completed            DO: A_DISPATCH_WORKFLOW
+  → S_FALLBACK  WHEN: workflow failed
+
+S_INGEST:
+  → END         DO: A_INGEST_RESULTS
+
+S_FALLBACK:
+  → S_PARSE     WHEN: user provides input
+  → END         WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_PARSE_ARGS
+
+1. 提取 flags（--script, --dims, --roles, --count, --tier, --resume）
+2. 剩余文本作为 intent
+3. 若有 --resume，记录 resumeRunId
+
+### A_ROUTE_SCRIPT
+
+Intent-to-script routing（按关键词匹配，--script 优先级最高）：
+
+| Keywords | Script |
+|----------|--------|
+| 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
+| 头脑风暴 / brainstorm / 方案 / 设计 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
+| 审查 / review / 代码审查 / code review / 质量 / quality | `wf-review` |
+| 验证 / verify / 检查 / check / 反模式 / antipattern | `wf-verify` |
+| 拷问 / grill / 压力测试 / stress-test / 挑战 / challenge | `wf-grill` |
+| 规划 / plan / 任务分解 / decompose / 分波 / wave | `wf-plan` |
+| 执行 / execute / 实现 / implement / 开发 / develop | `wf-execute` |
+| 里程碑审计 / milestone-audit / 集成检查 / integration | `wf-milestone-audit` |
+
+多命中 → ask_user 让用户选择。
+
+### A_ASSEMBLE_CONTEXT
+
+根据目标脚本组装 args payload：
+
+**wf-analyze:**
+1. Read `.workflow/state.json` 获取当前 phase/milestone 信息
+2. `target` = intent 中的目标描述
+3. `scope` = 从 intent 推断文件范围，或读 roadmap 获取 phase scope
+4. `context` = 拼接相关上下文（上游 artifact 摘要、specs）
+5. `dimensions` = --dims 解析结果（可选）
+
+**wf-brainstorm:**
+1. `topic` = intent 文本
+2. `context` = 读取相关代码文件摘要 + 已有 specs
+3. `count` = --count 或默认 3
+4. `roles` = --roles 解析结果（可选）
+
+**wf-review:**
+1. `target` = 读 git diff 描述变更范围
+2. `scope` = 变更文件列表
+3. `tier` = --tier 或 "standard"
+4. `dimensions` = --dims 解析结果（可选）
+
+**wf-verify:**
+1. `goals` = 读最近的 plan artifact 提取目标列表
+2. `plan_dir` = 定位最近的 plan scratch 目录
+3. `scope` = plan 涉及的文件范围
+4. `skip_tests` / `skip_antipattern` = 从 flags 提取
+
+### A_DISPATCH_WORKFLOW
+
+1. 确定 scriptPath = `~/.maestro/workflows/swarm/{script}.js`（展开为绝对路径）
+2. 构建 Workflow 调用：
+   ```
+   Workflow({
+     scriptPath: absoluteScriptPath,
+     args: assembledArgs,
+     resumeFromRunId: resumeRunId  // 若有
+   })
+   ```
+3. 等待 Workflow 返回结果
+4. 记录 runId 用于潜在的后续 resume
+
+### A_INGEST_RESULTS
+
+Workflow 返回 JSON 后：
+
+1. **摘要输出**：按脚本类型格式化关键指标（含对抗决策结果）
+   - analyze: overall_score, scope_verdict, adversarial_outcome (go/no-go/conditional advocacy + referee), scores_challenged count
+   - brainstorm: role count, conflict/synergy count, 3-proposal competition result, arbitration notes
+   - review: verdict (APPROVE/REQUEST_CHANGES/BLOCK), 3-vote tally, confirmed vs false-positive count, adversarial_verdict
+   - verify: overall_status, prosecutor vs defender confidence, adversarial_outcome, gap count
+   - grill: overall_verdict, meta-skeptic quality rating, 3-vote verdict tally, overblown findings count
+   - plan: selected_strategy (breadth/depth/risk), judge panel scores, 3-critic adversarial check verdict
+   - execute: 3-vote status (DONE/DONE_WITH_CONCERNS/NEEDS_RETRY), convergence trust %, discrepancy count
+   - milestone-audit: 3-vote verdict, dimensions_overturned count, next_step
+
+2. **Artifact 写入**（可选）：
+   - 若当前在 ralph session 中（检测 `.workflow/.maestro/ralph-*/status.json` 状态为 running）：
+     将结果写入对应 step 的 scratch 目录，格式兼容命令产出
+   - 否则写入 `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/results.json`
+
+3. **Ralph 兼容产出**：
+   - analyze → `analysis.md` + `context.md`（decisions）+ `conclusions.json` + `adversarial-debate.json`
+   - brainstorm → `guidance-specification.md` + `proposals-competition.json`
+   - review → `review.json`（含 adversarial_verdict + 3-vote tally）
+   - verify → `verification.json`（含 adversarial_outcome: prosecutor/defender debate）
+   - grill → `grill-results.json`（含 meta-challenge + 3-vote verdict）
+   - plan → `plan.json`（含 competition scores + critic feedback）
+   - execute → `execution-report.json`（含 convergence_checks + 3-vote status）
+   - milestone-audit → `audit-report.json`（含 dimension challenges + 3-vote verdict）
+
+4. **RunId 提示**：显示 `Resume: /maestro-swarm-workflow --resume {runId}` 用于增量重跑
+
+</actions>
+
+</state_machine>
+
+<invariants>
+1. **只做并行加速，不做状态决策** — 不修改 ralph status.json，不推进 step
+2. **args 预编译** — 所有 FS 读取在 A_ASSEMBLE_CONTEXT 完成，脚本内 agent 通过工具自行读取补充
+3. **产出格式兼容** — 写入的 artifact 格式必须与对应命令（analyze/brainstorm/review/verify）的产出一致
+4. **resume 透传** — resumeFromRunId 直接透传给 Workflow 工具，利用内置缓存机制
+5. **脚本只读** — 路由命令不修改 `~/.maestro/workflows/swarm/wf-*.js` 脚本文件
+6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
+</invariants>
+
+<appendix>
+
+### 与 Ralph 集成
+
+Ralph 可以在 A_BUILD_STEPS 中将某些 step 的执行方式标记为 `swarm-workflow`：
+
+```json
+{
+  "index": 2,
+  "skill": "maestro-swarm-workflow",
+  "args": "--script wf-analyze {phase}",
+  "stage": "analyze",
+  "command_scope": "project",
+  "command_path": "<resolved by maestro ralph skills>"
+}
+```
+
+ralph-execute 正常通过 `maestro ralph next` 加载并执行，swarm-workflow 内部再调 Workflow 工具。
+
+### 输出示例
+
+```
+┌─ wf-analyze ──────────────────────────────────────┐
+│  Explore  [████████████████████] 6/6 dimensions    │
+│  Synthesize  [████████████████] done               │
+├────────────────────────────────────────────────────┤
+│  Score: 7.2/10  Scope: medium  Verdict: go         │
+│  Findings: 23 total (2 critical, 5 high)           │
+│  Cross-cutting: 3 themes                           │
+│  Decisions: 4 locked, 2 free, 1 deferred           │
+├────────────────────────────────────────────────────┤
+│  Output: .workflow/scratch/20260530-swarm-analyze/  │
+│  Resume: /maestro-swarm-workflow --resume wf_abc123 │
+└────────────────────────────────────────────────────┘
+```
+
+### Error Codes
+
+| Code | Description | Recovery |
+|------|-------------|----------|
+| E001 | No intent and no --script | Prompt for intent |
+| E002 | Ambiguous routing | ask_user |
+| E003 | Script file not found | Check .claude/workflows/ |
+| E004 | Workflow execution failed | Show error, suggest --resume |
+| E005 | Result ingestion failed | Write raw JSON to scratch |
+
+</appendix>