Built-in workflows & orchestration patterns

Revka ships two libraries of ready-made orchestration so you don’t author everything from scratch: built-in workflow templates (declarative YAML you can run by name, duplicate, and edit) and multi-agent orchestration patterns (imperative MCP tools that coordinate several agents at once). Above both sit agent teams (spawn_team) and inter-agent chat rooms for ad-hoc coordination.

Use this page when you want to start from a working template instead of an empty file, or when a single agent isn’t enough and you need a reviewer, a critic, a fan-out, or a supervised committee. If you are still learning the YAML schema, read Your first workflow and the step types reference first. The patterns here run on the Operator MCP server, so make sure the sidecars are installed (see Install the Python MCP sidecars).

Built-in workflow templates

The operator ships 21 prebuilt workflow YAML definitions covering common development and content patterns. They are embedded in the revka binary at build time and seeded into your workspace, so you do not need the Python operator checked out to use them. Reference any of them by name in run_workflow(workflow="<name>", ...) or via POST /api/workflows/run/{name}.

Workflow	What it does	Key inputs
code-review	Coder implements, reviewer checks, produces a fix if rejected	task, cwd
code-review-advanced	Enhanced code-review flow	task, cwd
bug-fix	Researcher investigates, coder fixes, tester verifies	bug_description
spec-to-impl	Architect designs, coder implements, reviewer verifies	task
refactor	Researcher analyzes, architect plans, coder implements, reviewer approves	target
multi-module-review	Parallel review across multiple modules	—
research-only	Pure research workflow	—
data-pipeline-ingest	Ingest and analyze data, produce a report entity	task, cwd
data-pipeline-distribute	Distribute pipeline results	—
data-pipeline-summarize	Summarize pipeline outputs	—
revka-agentops-a2a	IT incident-response control plane with a human_approval gate	incident_id, alert_payload, cwd
revka-workflow-composer	Meta-workflow for composing new workflows	—
architecture-discussion	Group chat for architecture decisions	—
novel-writing	Creative writing workflow	—
cold-outreach	Outreach content generation	—
canonworks-serial-episode-factory	Serialized story episode generation	—
canonworks-serial-canon-state-sync	Canon-state synchronization for serial fiction	—
quantum-soul-arc-room	Arc-planning production room for the Quantum Soul serial	—
quantum-soul-episode-room	Episode production room	—
quantum-soul-production-room	Final production room	—
smoke-test-all-steps	Integration test exercising every step type	—

Built-in definitions are a good place to copy from. For example, code-review chains an agent (coder) → agent (reviewer) → conditional (verdict check) → agent (fix) → output, branching on whether the reviewer’s text contains APPROVED:

steps:
  - id: review
    type: agent
    depends_on: [implement]
    agent:
      agent_type: codex
      role: reviewer
      prompt: |
        Review the changes. Say APPROVED if good,
        else NEEDS_CHANGES with specific feedback.
  - id: check_verdict
    type: conditional
    depends_on: [review]
    conditional:
      branches:
        - condition: "${review.output} contains APPROVED"
          goto: summary
        - condition: default
          goto: fix

Note

Built-in workflows appear in the dashboard with source: builtin and cannot be edited or deleted — only duplicated. Use Duplicate to get an editable custom copy. The revka-agentops-a2a template is the canonical example of a human-in-the-loop approval gate (see Runs, approvals & checkpoints).

revka workflows — list and sync templates

The built-in YAMLs live in your workspace at operator_mcp/workflow/builtins/, which is the lowest-priority discovery location (see Your first workflow for the full override order). The revka workflows subcommand manages that on-disk copy.

revka workflows list            # list the templates embedded in this binary
revka workflows sync            # seed templates into the workspace (skips existing)
revka workflows sync --force    # overwrite existing template files

Command	Flags	Behavior
revka workflows list	—	Prints the workflow templates compiled into the running binary.
revka workflows sync	--force	Copies the embedded YAMLs into <workspace>/operator_mcp/workflow/builtins/. Existing files are left alone unless --force is passed.

Onboarding seeds these templates automatically; run revka workflows sync later to pick up new templates after a Revka upgrade. Because sync only writes missing files by default, your edits to other workflows are never clobbered — pass --force only when you want the shipped versions restored.

Tip

The destination directory must match what the gateway and cron scheduler scan, so always sync into the active workspace. After upgrading Revka, revka workflows sync --force is the clean way to refresh the built-ins to their latest shipped form.

Workflow presets (imperative)

Presets are a lighter-weight cousin of YAML workflows: reusable orchestration patterns defined in code rather than YAML. A preset is a list of steps, each with a role, an agent_type, optional depends_on edges (by step index), and an optional review_loop flag. Presets like code-review, spec-to-impl, and bug-fix are available as imperative MCP tools and can be previewed before you commit to a multi-agent run.

Tool	Purpose
list_workflow_presets(tag?)	List built-in and custom presets; filter by tag (e.g. review, testing).
save_workflow_preset(name, description, steps, tags?)	Save a custom preset for reuse.
get_workflow_plan(preset)	Preview a preset’s execution plan — steps, waves, and dependencies — without running it.

Use get_workflow_plan to sanity-check the wave structure (which steps run in parallel and which gate on others) before spending tokens. Presets are simpler than full YAML workflows: they describe an agent topology, not the full typed step grammar with shell, Python, conditionals, and triggers.

Multi-agent orchestration patterns

When one agent isn’t enough, the operator exposes six higher-level patterns as MCP tools. Each spawns and coordinates several agents and returns a structured result. They are also available as workflow step types (map_reduce, supervisor, group_chat, handoff) — see the step types reference.

review_fix_loop Reviewer parses a verdict (APPROVED / NEEDS_CHANGES / BLOCKED); a fixer applies changes; repeat.

refinement_loop Critique → refine with 0–100 quality scoring and trust-informed critic selection. The preferred replacement for review_fix_loop.

handoff_agent Transfer findings, files touched, and task state from one agent to another.

group_chat Moderated multi-agent discussion with turn-taking; returns transcript, summary, and conclusion.

supervisor_run Dynamic delegation — the supervisor picks the next specialist based on results so far.

map_reduce Fan out to N parallel mappers, then a reducer synthesizes all results.

review_fix_loop

Spawns a reviewer on a completed agent’s work, parses the verdict (APPROVED / NEEDS_CHANGES / BLOCKED), and — if changes are needed — spawns a fixer with the feedback, repeating up to max_rounds.

review_fix_loop(coder_agent_id, cwd, task?, reviewer_type?, fixer_type?,
                max_rounds?, review_focus?, timeout?)

Parameter	Default	Meaning
coder_agent_id	— (required)	Completed agent whose work to review.
cwd	— (required)	Working directory for reviewer and fixer.
reviewer_type	codex	Agent type for the reviewer.
fixer_type	codex	Agent type for the fixer.
max_rounds	2 (max 5)	Review → fix iterations.
review_focus	—	Extra guidance, e.g. focus on security.
timeout	300	Per-agent timeout in seconds.

refinement_loop

The structured successor to review_fix_loop. It runs critique → refine cycles with a 0–100 quality score, trust-informed critic selection (auto-switches the critic if its trust score drops below 0.7), and a fallback ladder (creator → dedicated fixer → escalate).

refinement_loop(creator_agent_id, cwd, task?, creator?, critic?, model?,
                max_rounds?, threshold?, review_focus?, timeout?)

Parameter	Default	Meaning
creator_agent_id	— (required)	Agent whose work to review and refine.
cwd	— (required)	Working directory for critic and fixer.
creator	codex	Agent type used to apply fixes.
critic	claude	Agent type for the critic; auto-switches if trust < 0.7.
max_rounds	2 (max 5)	Critique → refine iterations.
threshold	70	Quality score (0–100) required to pass.
timeout	300	Per-agent timeout in seconds.

Tip

Prefer refinement_loop over review_fix_loop for new work — the numeric scoring and trust-based critic selection give you a clearer stop condition and adapt the critic to its track record. Trust scores are tracked per template (see get_agent_trust).

handoff_agent

Extracts findings, files touched, and task state from a source agent and injects them into a receiving agent’s prompt, tracking the handoff chain in Kumiho. Use it to pass a researcher’s findings to a coder, or a coder’s work to a tester, without re-deriving context.

handoff_agent(from_agent_id, reason, to_agent_type?, task?, cwd?, model?, timeout?)

Parameter	Default	Meaning
from_agent_id	— (required)	Agent whose work to hand off.
reason	— (required)	Why the handoff is happening.
to_agent_type	claude	Receiver agent type or pool template name.
task	—	Specific task for the receiver.
cwd	source agent’s cwd	Working directory for the receiver.
timeout	300	Per-agent timeout in seconds.

group_chat

Runs a moderated multi-agent discussion. Participants take turns (round_robin or moderator_selected), and a moderator synthesizes consensus at the end. Returns a transcript, a summary, and a conclusion.

group_chat(topic, participants, moderator?, strategy?, max_rounds?, cwd?, model?, timeout?)

Parameter	Default	Meaning
topic	— (required)	Discussion topic.
participants	— (required)	Agent types or pool template names (min 2).
moderator	claude	Moderator agent.
strategy	moderator_selected	Turn order: round_robin or moderator_selected.
max_rounds	8 (max 20)	Maximum speaking turns.
timeout	120	Per-turn timeout in seconds.

The architecture-discussion built-in workflow is a group-chat template; the step inspector shows the full transcript for each group_chat step.

supervisor_run

Dynamic delegation: a supervisor analyzes the task, delegates a subtask to the best available specialist, integrates the result, and repeats — choosing the next agent based on results so far. Unlike spawn_team (a static DAG), the topology is decided at run time.

supervisor_run(task, cwd, templates?, max_iterations?, supervisor_type?, model?, timeout?)

Parameter	Default	Meaning
task	— (required)	Task to accomplish.
cwd	— (required)	Working directory.
templates	all in pool	Specialist pool template names to draw from.
max_iterations	5 (max 10)	Delegate → integrate cycles.
supervisor_type	claude	Supervisor agent.
timeout	300	Per-agent timeout in seconds.

map_reduce

Fans a task out to N parallel mapper agents over a list of splits (file paths, sections, subtasks), then a reducer synthesizes all results. Ideal for reviewing or analyzing many files at once.

map_reduce(task, splits, cwd, mapper?, reducer?, concurrency?, model?, timeout?, halt_on_failure?)

Parameter	Default	Meaning
task	— (required)	Overall task description.
splits	— (required)	Segments to process in parallel (min 2).
cwd	— (required)	Working directory.
mapper	claude	Mapper agent type or pool template.
reducer	claude	Reducer agent type or pool template.
concurrency	3 (max 10)	Maximum simultaneous mappers.
halt_on_failure	false	Stop remaining mappers if one fails.
timeout	300	Per-agent timeout in seconds.

Agent teams (spawn_team)

A team is a bundle of agent templates plus dependency edges, stored in Kumiho under Revka/Teams. The edges (REPORTS_TO, SUPPORTS, DEPENDS_ON) define a DAG topology, and spawn_team executes it in waves — agents with no unresolved dependencies run simultaneously, then the next wave fires once theirs complete. This is the static counterpart to the dynamic supervisor_run.

Tool	Purpose
create_team(name, description, member_krefs, edges?)	Create or update a team bundle (members and edges are replaced on update).
list_teams()	List all teams from Kumiho.
get_team(kref)	Full team detail, including members and edges.
search_teams(query)	Search teams by name or description.
spawn_team(team_kref, task, cwd?, dry_run?, halt_on_failure?, resume_from?)	Execute the team in waves.
get_spawn_progress(team_name?)	Per-wave progress, completions, and halt reasons.
lint_team(team_kref, task?)	Check role balance, naming, capability coverage, and edge completeness.

Edges are declared as {from_kref, to_kref, edge_type}:

{
  "name": "rust-dev-team",
  "description": "Implement + review Rust features",
  "member_krefs": ["kref://.../coder", "kref://.../reviewer"],
  "edges": [
    { "from_kref": "kref://.../reviewer", "to_kref": "kref://.../coder", "edge_type": "DEPENDS_ON" }
  ]
}

Key behaviors:

• dry_run: true validates the graph and returns the stage preview without spawning anything — pair it with lint_team before a real run.
• halt_on_failure defaults to true, stopping downstream stages when an upstream stage has failures. Set it to false to continue regardless.
• resume_from takes a checkpoint ID. When a spawn halts mid-run, the response includes a checkpoint_id; pass it back to resume from the failed wave instead of re-running everything.

For the broader agent and team model, see Agents, teams & swarms and Spawning & coordinating agents.

Inter-agent chat rooms

Chat rooms are named channels for async coordination between spawned agents. An agent posts a message, optionally @mentions other agents (which triggers a follow-up prompt to any mentioned agent that is currently idle), and reads the shared log. The session manager wires those mention-based interrupts automatically, so a room doubles as shared memory and a decision log for a team.

Tool	Purpose
chat_create(name, purpose?)	Create a room.
chat_post(room_id, content, sender_id?, sender_name?, mentions?, reply_to?)	Post a message; mentions triggers follow-up prompts to idle agents.
chat_read(room_id, limit?, since?)	Read recent messages (default 50; since filters to new ones by ISO timestamp).
chat_list()	List all active rooms.
chat_wait(room_id, timeout?)	Long-poll for a new message (up to 60,000 ms).
chat_delete(room_id)	Delete a room and its messages.

{ "name": "design-review", "purpose": "Review the auth module" }

Rooms persist for the lifetime of the agent session. The shipped operator-orchestrator.md skill describes the full “chat room as backbone” team-coordination pattern that combines rooms with spawn_team and the patterns above.

Note

Chat rooms require the optional Node.js session manager sidecar — it hosts the chat service and relays the mention interrupts. Without it, the live execution view and chat-driven coordination receive no events. See Install the Python MCP sidecars.

Choosing a pattern

You want to…	Use
Improve one agent’s output against a verdict	review_fix_loop
Improve one agent’s output against a quality score	refinement_loop
Pass context from one agent to another	handoff_agent
Reach a decision among several agents	group_chat
Let the system decide who works next	supervisor_run
Process many files/sections in parallel	map_reduce
Run a fixed, repeatable agent topology	spawn_team (or a YAML workflow)
Coordinate agents asynchronously by message	Inter-agent chat rooms

Where to go next

Step types reference The map_reduce, supervisor, group_chat, and handoff step types in YAML.

Your first workflow Author, save, and run a workflow from scratch.

Runs, approvals & checkpoints Approval gates, retry, and the run lifecycle.

Spawning & coordinating agents create_agent, lifecycle tools, teams, and the orchestration skills.

Operator MCP The Python sidecar that runs these workflows and patterns.

revka skills, workflows & SOP The CLI surface for templates, skills, and SOPs.