Multi-Agent Workflows
This guide is about workflow records — durable JSON files under Saved/ClaudusBridge/MultiAgentWorkflows/ that track a multi-step collaboration between Claude, Codex, Cursor, Windsurf, the Claudus native agents, and any other peer executor. Each record has participants, steps, action ids, status, results, notes, and evidence.
This is different from the per-session event bus described in Multi-Agent Coordination. That guide covers subscribe_events / poll_editor_events / publish_agent_event — the messaging primitives multiple agents use to communicate in real time. This guide covers the persistent ledger of who is doing what on a longer-running task.
| Need | Use |
|---|---|
| "Notify a peer that I just changed an actor" | Event bus (publish_agent_event) |
| "Track a 5-step refactor where Codex handles file edits and Claudus drives the editor" | Workflow record (this page) |
| "Capture milestones for the audit trail" | Workflow Checkpoints |
| "See what happened across sessions" | Auto-Observations |
The tools
| Tool | Purpose |
|---|---|
claudus_start_multi_agent_workflow | Create a new workflow record |
claudus_list_multi_agent_workflows | Enumerate active and completed workflows |
claudus_get_multi_agent_workflow | Read a single record (full content) |
claudus_update_multi_agent_workflow | Set step status / result / evidence / notes; transition the workflow's own status |
claudus_cancel_multi_agent_workflow | Mark a workflow as cancelled with a reason |
claudus_workflow_timeline | Return an ASCII Gantt rendering + a structured rows[] for one workflow |
claudus_list_workflow_templates | Built-in catalog of repeatable Unreal patterns |
claudus_instantiate_workflow_template | Create a workflow from one of those templates |
claudus_smart_start | Score an intent against the template catalog and instantiate the best match — day-1 onboarding tool |
Quick start
# Create a workflow from a template
cb call claudus_instantiate_workflow_template '{
"template_id": "material_pipeline",
"title": "Holographic material refresh — May",
"objective": "Update M_Holo and 3 instances to use the new emissive curve",
"target_asset": "/Game/Materials/Holographic/M_Holo"
}'
# Or, smart-start from a free-text intent
cb call claudus_smart_start '{
"intent": "I want to make a new material with pulsing emission"
}'
# Check what's running
cb call claudus_list_multi_agent_workflows
# Drive a step forward
cb call claudus_update_multi_agent_workflow '{
"workflow_id": "maw-holo-material-refresh-...",
"step_id": "S02",
"status": "done",
"evidence": "Recompile succeeded; visual watcher confirmed emissive pulse at ~1 Hz."
}'
# Render the timeline
cb call claudus_workflow_timeline '{ "workflow_id": "maw-holo-material-refresh-..." }'
Workflow record shape
Saved/ClaudusBridge/MultiAgentWorkflows/maw-<slug>-<timestamp>.json:
{
"schema": "claudus.multi_agent_workflow.v1",
"workflow_id": "maw-holo-material-refresh-20260515-074203",
"title": "Holographic material refresh — May",
"objective": "Update M_Holo and 3 instances to use the new emissive curve",
"status": "active",
"mode": "shared",
"lead": "provider_peer",
"lead_prompt_hint": "You are the lead orchestrator. Plan steps; delegate to followers.",
"follower_prompt_hint": "You are a follower. Execute the step assigned to you and report evidence.",
"participants": ["claude", "codex", "claudus-native-vision"],
"target_asset": "/Game/Materials/Holographic/M_Holo",
"assets": [],
"steps": [
{
"step_id": "S01",
"title": "Snapshot baseline",
"owner": "claude",
"status": "done",
"action_id": "ck-holo-…",
"evidence": "Workflow checkpoint with 14 assets captured.",
"started_at": "2026-05-15T07:42:03Z",
"ended_at": "2026-05-15T07:42:04Z"
},
{
"step_id": "S02",
"title": "Recompile M_Holo with new emissive curve",
"owner": "claude",
"status": "in_progress",
"started_at": "2026-05-15T07:42:30Z"
},
/* ... */
],
"created_at": "2026-05-15T07:42:00Z",
"updated_at": "2026-05-15T07:42:30Z",
"created_by_model": "claude-opus-4-7[1m]",
"created_by_provider": "Claude"
}
The plugin treats workflow_id as the canonical handle. Every tool that operates on a workflow takes workflow_id; every auto_observation entry tied to a workflow includes that id as a tag.
Templates — the built-in catalog
claudus_list_workflow_templates returns the curated catalog. As of 0.6.x it includes (current count via the tool, since the list evolves):
material_pipeline— Author or update a Material + its instances with verification.gameplay_mechanic— Build a small gameplay feature end-to-end (Blueprint + components + verification).asset_refactor— Rename / reparent / re-path a set of related assets safely.unreal_onboarding— Day-1 walk-through for an agent connecting to a new project.bug_investigation— Triage a reported bug with reproduction + evidence + fix + verification.material_function_authoring— Create aMaterialFunctionwith proper inputs/outputs and a parent-material binding.
Each template carries a step list with owners, a default mode (shared / sequential), a default lead role (provider_peer, multi_agent_orchestrator, …), and matching keywords. Instantiate one with:
cb call claudus_instantiate_workflow_template '{
"template_id": "material_pipeline",
"title": "Free-text title for this run",
"objective": "Free-text objective",
"target_asset": "/Game/Materials/M_Holo",
"scope": "/Game/Materials/Holographic"
}'
The result is a normal workflow record — no new state to learn after instantiation.
Smart start — one call from intent to workflow
claudus_smart_start is the day-1 onboarding tool:
cb call claudus_smart_start '{
"intent": "I want to fix the bug where my character lands and the camera jitters"
}'
Behind the scenes:
- Score the intent against every template's keywords (free).
- Subtract any negative-keyword hits per template (e.g. words like
crash,bug,fixpushgameplay_mechanicandmaterial_pipelineaway — they belong tobug_investigation). - Track the runner-up.
- If the top-1 score is within 3 points of the runner-up (
score_gap < 3), or the top score is otherwise weak, escalate the classification to Haiku 4.5 via the mixed-tier delegation path. Otherwise pick the keyword winner directly. - Instantiate the chosen template with the user's intent as the title/objective.
The response includes chosen_template_id, classification_source (keyword / haiku / haiku_ambiguous / default), keyword_score, runner_up_template_id, runner_up_score, score_gap, escalated_to_haiku, and the full workflow handle. Operators can see exactly how the router decided.
Auto-link fallback (0.6.3) — provider style differences become harmless
Live verification across providers (Claude Opus 4.7 1M, ChatGPT 5.5, Gemini 3.1 Pro Preview) on identical workflows surfaced a real behavioural difference:
| Provider | After consuming the action result, calls claudus_update_multi_agent_workflow? |
|---|---|
| Claude Opus 4.7 1M | Yes — completes the step explicitly. |
| ChatGPT 5.5 | No — answers the user, but skips the bookkeeping tool call. |
| Gemini 3.1 Pro Preview | Yes — frequently emits another action_request to call the update tool, and over-completes the entire workflow. |
Same plugin, same prompts, different model dispositions. To prevent the user-visible UX from depending on which provider they happen to be using, the plugin now ships a fuzzy-match safety net inside AttachActionResultToWorkflows:
- Direct match (primary) — When a workflow has the action's
idin itsaction_ids[]array, the function updates the matching step exactly as before. Explicit links remain the precise path. - Fuzzy match (fallback) — If no workflow named the action, the function looks for the most recently updated active workflow with at least one pending /
in_progressstep, appends theaction_idto that workflow'saction_ids[], marks the first pending stepcompleted(orblockedon failure) with the action's result asevidence, and emits a[workflow-auto-link]system note in the transcript so the rescue is visible.
The rescued step records auto_completed_by_action_result: true so audit trails can distinguish a provider-driven completion from a system rescue. The workflow itself gets last_action_id, last_action_status, last_action_result, phase: "result_received" (or blocked), and an auto_linked_reason text explaining why the link exists.
This means the workflow record always reflects reality, regardless of whether the provider explicitly tracked the link. Users can compose multi-step plans, pick any provider, and trust that a stuck in_progress step is real (a true failure) — not a bookkeeping miss.
Driving steps forward
claudus_update_multi_agent_workflow is the workhorse:
cb call claudus_update_multi_agent_workflow '{
"workflow_id": "maw-…",
"step_id": "S02",
"status": "done", // pending | in_progress | done | blocked | cancelled
"owner": "claude", // optional reassign
"action_id": "ck-holo-…", // optional: tie this step to a checkpoint, action, etc.
"evidence": "Recompile succeeded; visual watcher confirmed emissive pulse at ~1 Hz."
}'
To advance the workflow itself rather than a single step:
cb call claudus_update_multi_agent_workflow '{
"workflow_id": "maw-…",
"status": "completed",
"result": "Material refreshed; 3 instances pulse correctly; baseline checkpoint preserved."
}'
When a workflow transitions to completed, an auto_observation entry fires with tags workflow_completed + <workflow_id> + mode:<mode> + lead:<lead> (see Auto-Observations). The next session sees the result without having to read the record file.
Role-pinning (advisory)
claudus_start_multi_agent_workflow accepts:
lead: <role-or-agent-id>— Who's orchestratingroles: { <role>: <agent_id>, ... }— Map each role in the workflow to a concrete agent
Plus two prose hints the provider can echo into its system context so simultaneous Claudes know which is orchestrating and which is executing:
lead_prompt_hint: "You are the lead orchestrator..."follower_prompt_hint: "You are a follower. Execute..."
This is advisory — the plugin doesn't enforce role behaviour. The hints exist so two AI clients connecting to the same workflow can settle "who is the lead?" via the persisted record instead of negotiating in chat.
Default lead is provider_peer for backward compatibility with workflows created before role-pinning shipped.
Timeline rendering
claudus_workflow_timeline(workflow_id) returns both an ASCII Gantt rendering and a structured rows[]:
S01 │ ██████████░░░░░░░░░░░░░░░░░░░░ Snapshot baseline (done — claude, 1 s)
S02 │ ░░░░░░░░░░██████████░░░░░░░░░░ Recompile M_Holo (in_progress — claude)
S03 │ ░░░░░░░░░░░░░░░░░░░░██████░░░░ Verify visual (pending — claudus-native-vision)
S04 │ ░░░░░░░░░░░░░░░░░░░░░░░░░░██░░ Notify team (pending — codex)
{
"rows": [
{ "step_id": "S01", "title": "Snapshot baseline", "status": "done", "owner": "claude", "started_at": "...", "ended_at": "...", "duration_s": 1 },
{ "step_id": "S02", "title": "Recompile M_Holo", "status": "in_progress", "owner": "claude", "started_at": "...", "ended_at": null, "duration_s": null },
{ "step_id": "S03", "title": "Verify visual", "status": "pending", "owner": "claudus-native-vision", "started_at": null, "ended_at": null, "duration_s": null },
{ "step_id": "S04", "title": "Notify team", "status": "pending", "owner": "codex", "started_at": null, "ended_at": null, "duration_s": null }
]
}
The ASCII renders cleanly in Slack/Notion/PR comments. The rows[] feed external dashboards.
The companion Slate live-timeline widget was on the 0.6.0 roadmap but was deferred because Slate UI work needs visual validation that can't run headless. The rows[] payload is the supported programmatic interface; the ASCII is the supported human paste-in. A native widget may revisit when there's a verification path that doesn't require human sign-off.
Cancelling a workflow
cb call claudus_cancel_multi_agent_workflow '{
"workflow_id": "maw-…",
"reason": "Replaced by maw-… after scope change. See that workflow for the new plan."
}'
Cancelled workflows stay in the record store (they don't get deleted), and the cancellation event fires as a regular workflow status transition. Don't delete the JSON file by hand — the next listing will show a stale entry until the editor restarts.
Task plans — a lighter alternative
For simpler work that doesn't need multi-agent coordination, the task plan tools cover a single-agent multi-step plan with the same JSON-backed durability:
claudus_create_task_plan— Create a plan with title, steps, optional ownerclaudus_list_task_plans— List active plansclaudus_get_task_plan— Read a planclaudus_update_task_plan— Set step status + evidence
Plans live under Saved/ClaudusBridge/TaskPlans/. They're appropriate when a single agent is working alone but wants a durable to-do list with evidence — e.g. "refactor this Blueprint in 4 steps, mark each step done as I finish it". Multi-agent workflows are the right call when multiple peers contribute to the same record.
Where to go next
- Multi-Agent Coordination — The real-time event bus that complements the persistent workflow ledger
- Workflow Checkpoints — Tie an asset-state snapshot to a workflow id
- Auto-Observations — Read back the
workflow_completed/workflow_checkpointentries - Cognition Tier overview — How workflows sit in the larger 0.6.x picture