SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmaestro-swarm-workflow

maestro-swarm-workflow

Office & productivity

View repository

Updated 10-15 20:11

About this skill

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: a step in the ralph chain can specify swarm-workflow as an accelerated executor
  • Chained: the output JSON can be consumed by downstream commands via --from consumption

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 interface
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? }

<state_machine>

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_question

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

A_PARSE_ARGS

  1. Extract flags (--script, --dims, --roles, --count, --tier, --resume)
  2. Remaining text as intent
  3. If there is --resume, record resumeRunId

A_ROUTE_SCRIPT

Intent-to-script routing (match by keyword, --script has highest priority):

Keywords Script
analyze / 分析 / explore / 探索 / architecture / 架构 / complexity / 复杂度 / risk / 风险 wf-analyze
brainstorm / 头脑风暴 / proposal / 方案 / design / 设计 / evaluate / 评估 / multi-perspective / 多角度 wf-brainstorm
review / 审查 / code review / 代码审查 / quality / 质量 wf-review
verify / 验证 / check / 检查 / antipattern / 反模式 wf-verify
grill / 拷问 / stress-test / 压力测试 / challenge / 挑战 wf-grill
plan / 规划 / task decomposition / 任务分解 / decompose / wave / 分波 wf-plan
execute / 执行 / implement / 实现 / develop / 开发 wf-execute
milestone-audit / 里程碑审计 / integration / 集成检查 wf-milestone-audit

Multiple matches → ask_question to let the user choose.

A_ASSEMBLE_CONTEXT

Assemble the args payload according to the target script:

wf-analyze:

  1. Read .workflow/state.json Get the current phase/milestone information
  2. target = the target description in the intent
  3. scope = infer the file scope from the intent, or read the roadmap to get the phase scope
  4. context = concatenate the relevant context (upstream artifact summary, specs)
  5. dimensions = the --dims parsing result (optional)

wf-brainstorm:

  1. topic = the intent text
  2. context = read the summaries of relevant code files + existing specs
  3. count = --count or default 3
  4. roles = the --roles parsing result (optional)

wf-review:

  1. target = read git diff to describe the change scope
  2. scope = the list of changed files
  3. tier = --tier or "standard"
  4. dimensions = the --dims parsing result (optional)

wf-verify:

  1. goals = read the most recent plan artifact to extract the target list
  2. plan_dir = locate the most recent plan scratch directory
  3. scope = the file scope involved in the plan
  4. skip_tests / skip_antipattern = extract from flags

A_DISPATCH_WORKFLOW

  1. Determine scriptPath = ~/.maestro/workflows/swarm/{script}.js(expand to an absolute path)
  2. Build the Workflow call: 
    Workflow({
  scriptPath: absoluteScriptPath,
  args: assembledArgs,
  resumeFromRunId: resumeRunId  // 若有
})
  3. Wait for the Workflow to return a result
  4. Record runId for a potential subsequent resume

A_INGEST_RESULTS

After the Workflow returns JSON:

  1. Summary output: format key metrics by script type (including adversarial decision results)

    • 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 write(optional):

    • If currently in a ralph session (detect .workflow/.maestro/ralph-*/status.json status is running): write the result to the scratch directory of the corresponding step, in a format compatible with command output
    • Otherwise write to .workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/results.json

  3. Ralph-compatible output：

    • analyze → analysis.md + context.md（decisions）+ conclusions.json + adversarial-debate.json
    • brainstorm → guidance-specification.md + proposals-competition.json
    • review → review.json(including adversarial_verdict + 3-vote tally)
    • verify → verification.json(including adversarial_outcome: prosecutor/defender debate)
    • grill → grill-results.json(including meta-challenge + 3-vote verdict)
    • plan → plan.json(including competition scores + critic feedback)
    • execute → execution-report.json(including convergence_checks + 3-vote status)
    • milestone-audit → audit-report.json(including dimension challenges + 3-vote verdict)

  4. RunId prompt: display Resume: /maestro-swarm-workflow --resume {runId} Used for incremental re-runs

</state_machine>

Integration with Ralph

Ralph can mark the execution method of certain steps in A_BUILD_STEPS as swarm-workflow：

{
  "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 normally loads and executes through maestro ralph next , and swarm-workflow internally calls the Workflow tool.

Output example

┌─ 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_question
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