marshal-workflow
Author and run declarative YAML workflows on the Marshal fleet - reusable orchestration recipes (fan a goal out across clients, collect the diffs, then merge the good ones) that you run by name instea
SKILL.mdskills/marshal-workflow/SKILL.md
GitHubRunning Marshal workflows
A workflow is a named recipe stored as YAML under <repo>/workflows/. It captures an
orchestration you'd otherwise rebuild by hand each time: fan a goal out across several clients,
surface the resulting diffs, and (optionally) merge them. You run it by name with inputs; Marshal
executes the phases in order.
This is the repeatable cousin of marshal-orchestrate. Reach for a workflow when the shape is stable and only the target changes ("review X", "implement Y across these models"). Reach for marshal-orchestrate when the decomposition is bespoke to this one goal.
The safety model (read this first)
A workflow adds no new execution path. Each phase is exactly a call you could make yourself -
run_many / run_agent / collect_run / integrate - so every run still gets an isolated git
worktree, a hard timeout + kill, and a usage-ledger entry. Integration is gated off by default:
an integrate phase with auto: false (the default) does not merge - it returns the candidate
runs in next_actions for you to review and merge yourself. succeeded is not correct; the merge
decision stays human.
1. Discover & validate
list_workflows(MCP) returns{workflows, errors, workspace}— each recipe's name, inputs, and phases; malformed files land inerrors.marshal workflows(CLI) lists them and validates each against yourfleet.config.yaml- unknown client names, missing inputs, and unresolvable phases fail here, before any agent spawns.
2. The recipe schema
name: review
description: Review a target across two clients; surface diffs to merge.
inputs: [target] # names usable as {target} in goals; must be supplied at run time
phases:
- name: review
run: fan_out # one run per client, in parallel
clients: [reviewer-a, reviewer-b]
goal: "Review {target} for bugs; apply fixes scoped to {target}."
- name: gate
run: collect # read-only: gather the prior phase's diffs
- name: merge
run: integrate # auto: false (default) -> report candidates, never auto-merge
Phase kinds:
fan_out-goalacrossclients(parallel).agent-goalon oneclient.collect- surface a prior generative phase's diffs (read-only; never stops the run).integrate- merge succeeded runs only ifauto: true; default reports candidates.
collect/integrate source the most recent preceding fan_out/agent phase, or set
from_phase: <name> to point at a specific earlier named phase. Goals substitute {input} tokens
only (literal braces must be doubled: {{).
3. Run it
run_workflow(name, inputs) - e.g. run_workflow("review", {"target": "src/auth.py"}). It validates
the whole recipe first, then runs each phase. The result carries workflow_run_id, per-phase
records/diffs, a status, and next_actions.
4. Read the gate, then merge
status:completed(nothing left),awaiting_review(diffs and/or gated integrate candidates to act on), orerror(the workflow did not do what it was asked - an agent run failed or timed out, its work could not be read, or an auto-integrate hit a state needing a human).completedmeans every phase did its job: a run that failed makes the workflow anerror, never a quiet success.- Work the
next_actionslist. For each candidate, read its diff (collect_run) - you are the reviewer - thenintegrate(run_id)the ones worth keeping, one at a time. Reject the rest by simply not integrating; their worktrees stay isolated and main is untouched. - A fan_out shares one
task_idper phase, soreport(task_id)/usage()compare what each client cost on the same task.
Authoring tips
- Keep clients in a
fan_outworking on the same target - they're alternatives to compare, or a review you'll merge once. Independent parallel edits to different files belong in marshal-orchestrate (or separate phases), to avoid merge collisions. - Start templates from
examples/workflows/(review.yaml,compare.yaml); copy into<repo>/workflows/and swap in your client names. - Default to gated integrate. Only set
auto: truewhen the recipe is trusted and the runs are genuinely independent - and even then, expectawaiting_reviewon any conflict/blocked outcome.