A workflow.md file is the single definition of an agent run. It names a
runtime_key, a schema method, budgets, tools, sandbox, retries, review
policy, state-machine transitions, and optional provider settings. Cadence
validates it, reduces it, and owns the run.
Author-facing methods
Workflow authors use only these schema methods:
api, sdk, mcp, cli, desktop_app
Never put proof-suite taxonomy such as local_process or local_http in
workflow frontmatter. Those are test/evidence labels, not author-facing
selectors.
Runtime keys
How to author a workflow
- Pick the job shape: single agent, pair programming, reviewer panel, or a
state-machine workflow with several provider stages.
- Pick runtime keys by capability, not brand preference (see
Runtimes).
- Use
agent.single_agent for single-agent fixed, vendor-auto, or ordered
fallback routes.
- Use
participants, roster, pair_profiles, and state_machine for
multi-agent or nested workflows.
- Keep it declarative: no endpoint URLs, raw shell flags, SDK class names,
or provider-specific imperative code.
- Declare budgets, sandbox, tools, review consensus, retry, cache, and
lifecycle policy in frontmatter.
- Validate before dispatch.
- Dispatch through Cadence — never bypass it with a raw provider call for
production work.
Validated cross-provider example
This example is a policy document, not a script: Gemini researches, Anthropic
implements, OpenAI reviews, and Cadence gates completion — with ordered
fallback if a runtime is unavailable or rate-limited. It is validated against
the real workflow schema by a CI test.
Every frontmatter block here is real schema: selection with ordered fallback,
cross-provider pair profiles, provider-diverse review consensus, typed retry
fallbacks, per-provider Headroom budgets, and an explicit state machine with
loop caps. 
