Workflows

Save a sequence of work for multiple agents and reuse it with new tasks.

A workflow tells Admiral which agents should work, in what order, what each one receives, and how to combine the results. Save it once and reuse it for similar tasks. It is different from an agent profile or a plan: it coordinates several runs, which you review before they start.

Use a built-in workflow

Clarvis includes audit, implement, and research. Select Admiral through /agent, then ask for the workflow by name:

Use the audit workflow to review the authentication changes. Explain the work and cost before
running it.

Before any leader starts, Clarvis asks you to review the rounds, agents, and number of parallel runs. Approval starts the first round only. After each round, Admiral receives a saved checkpoint and must decide whether to continue or stop.

The sequence below is a real one-leader release-review run in an isolated demonstration profile. It uses the same review and persistence path as the built-in workflows.

Step 1 — select Admiral. The header confirms that the current lead carries the workflow capability.

Step 2 — review before execution. No leader starts until you inspect the round, profile, number of parallel runs, and explicitly approve.

Step 3 — monitor the tree. The live sidebar keeps each leader, status, duration, and iteration count visible beside the manager result.

WARNING

Workflow execution always needs an interactive review. Headless print mode can explain a workflow but cannot approve and run it.

Author a workflow

Create this structure:

.clarvis/workflows/release-review/
├── WORKFLOW.md
└── briefs/
    └── inspect.md

Add .clarvis/workflows/release-review/WORKFLOW.md:

---
name: release-review
description: Review a release target through one evidence-gathering leader.
args:
  - target
rounds:
  - id: inspect
    title: Review {{args.target}}
    type: free
    profile: explorer
    over: once
    brief: briefs/inspect.md
---

Summarize the review for a human. Lead with blockers, then risks, then evidence that the target is
ready.

Add .clarvis/workflows/release-review/briefs/inspect.md:

Review {{args.target}} for release readiness.

Inspect manifests, release notes, public documentation, and the checks that cover the changed
surface. Return concrete blockers and risks with repository paths. Do not modify the workspace.

The workflow directory and frontmatter name must match. The first round must use over: once. Brief paths are relative to the workflow directory.

Run your workflow

Select Admiral and ask:

Use the release-review workflow for target candidate. Explain its cost before running it.

Arguments such as target are required when declared. /workflow is the run-history and agent-tree browser; it is not a workflow-definition editor or launcher. While a sequence is waiting, the workflow view and live Parallel work section show awaiting_manager, the checkpoint revision, and the proposed next round. A stale or repeated decision cannot launch the same round twice.

Step 4 — reopen the run. Use /workflow to inspect the persisted manager-to-leader tree after completion.

Step 5 — inspect evidence. Open a leader to read its complete stored result and resource totals instead of relying only on synthesis.

Add more rounds

Each round declares:

• a unique id;
• a type: discovery, findings, verdict, or free;
• an optional agent profile;
• an over selector;
• a short title; and
• a relative brief path.

Selectors are intentionally small:

• once runs one leader;
• each(scan.items) runs one leader per item;
• each(scan.items where needs_verification) filters truthy items;
• each(scan.items where severity = high) filters by value; and
• all(scan.items) sends the full collection to one leader.

Use fanout only for genuinely independent copies of a round. Repeated rounds can stop after no new results or at a configured budget boundary.

Control workflow resources

Optional settings apply to the whole workflow tree:

{
  "workflows": {
    "max_concurrency": 4,
    "max_total_leaders": 32,
    "budget_tokens": 640000000
  }
}

The concurrency default is 4 and the maximum is 20. max_total_leaders defaults to 32 and caps successful leader registrations across the whole manager lifetime; completed leaders do not refund a slot. The auxiliary workflow token budget defaults to 640000000; use null only when you intentionally want no workflow token ceiling. It covers the manager's in-process children plus every leader and leader sub-agent. The workflow manager itself uses its independent primary-run budget and does not consume this ledger.

How the budget is shared

Active model calls share the available token budget. A leader waiting for a concurrency slot reserves no tokens, and unused capacity returns when a call ends. This lets the manager's children, leaders, and their sub-agents reuse the remaining budget.

Before starting a round, Clarvis checks that the cumulative leader limit can fit the whole round. It does not start only part of an over-limit round. Running out of tokens still fails the affected leaders and the workflow; check all results in /workflow.

Workspace workflows replace same-named global or built-in workflows as a whole. A malformed override is ignored, leaving the valid lower-precedence definition available.

See also

• Agents
• Daily use
• Scopes and workspace trust
• Troubleshooting