Workflow Schema Reference

This is the exact contract Cadence validates workflow.md frontmatter against — generated from the same JSON Schema the validator loads, so it cannot drift. Use it like --help for workflow authoring: every field, type, required flag, enum, and constraint below is enforceable truth. Numeric and boolean fields also accept {{var}} template strings, resolved from workflow arguments at dispatch time.

Top-level fields

Field	Type	Required	Constraints
`id`	string	yes	non-empty
`version`	string	yes	non-empty
`aliases`	array of string	no	—
`applies_to`	object	no	—
`library`	object	no	—
`agent`	object	no	—
`participants`	array of object	no	—
`pair_profiles`	object	no	—
`context`	object	no	—
`channel`	object	no	—
`budget`	object	no	—
`sandbox`	object	no	—
`tools`	object	no	—
`tool_policy`	`read-only` \| `edit` \| `full` \| `network`	no	—
`sandbox_profile`	`read-only` \| `edit` \| `full` \| `network`	no	—
`cadence`	object	no	—
`review_consensus`	object \| `false`	no	—
`retry`	object	no	—
`merge_admission`	object	no	—
`workpad`	object	no	—
`cache_policy`	object	no	—
`hot_reload`	boolean \| object	no	—
`state_machine`	object	no	—
`arguments`	object	no	—
`roster`	array of object	no	—
`adherence`	array of string	no	—
`attestations_required`	array of string	no	—
`triggers`	array of string \| unknown	no	—
`execution`	object	no	—
`workspace_mode`	`full_worktree` \| `workleaf_readonly`	no	—
`max_full_worktrees_per_run`	integer	no	min 0
`mutating_parallel_branches`	boolean	no	—

`applies_to`

Field	Type	Required	Constraints
`labels`	array of string	no	—
`pair_state`	array of string	no	—
`plugins`	array of string	no	—

`library`

Field	Type	Required	Constraints
`selectable`	boolean	no	—
`family`	string	no	non-empty
`product_mode`	`single` \| `pair` \| `collab`	no	—
`display_name`	string	no	non-empty
`description`	string	no	—
`maturity`	`stable` \| `experimental` \| `hidden` \| `deprecated`	no	—
`recommended_for`	array of string	no	—
`locks_after`	`cadence_claim` \| `dispatch` \| `never`	no	—

`agent`

Field	Type	Required	Constraints
`runtime_key`	string	no	non-empty
`provider`	string	no	—
`model`	string	no	—
`role`	string	no	—
`task_template`	string	no	—
`max_turns`	integer (or `{{var}}` template)	no	—
`max_concurrent_agents`	integer (or `{{var}}` template)	no	—
`reasoning_effort`	string	no	—
`thinking`	object	no	—
`cache_policy`	object	no	—
`budget`	object	no	—
`display_name`	string	no	—
`naming_mode`	`first-and-last` \| `first-only` \| `last-only`	no	—
`routing_strategy`	`pair_programming` \| `single_agent_routine`	no	—
`single_agent`	object	no	—
`agent_tier`	`opus` \| `sonnet` \| `haiku`	no	—
`dispatch_path`	`local` \| `cloud_managed` \| `auto`	no	—

`agent.thinking`

Field	Type	Required	Constraints
`type`	`enabled` \| `disabled` \| `adaptive`	no	—
`budget_tokens`	integer (or `{{var}}` template)	no	—

`agent.cache_policy`

Field	Type	Required	Constraints
`enabled`	boolean	no	—
`strategy`	`auto` \| `explicit`	no	—
`ttl`	`provider_default` \| `5m` \| `1h` \| `24h`	no	—
`min_tokens`	`enforce` \| `best_effort`	no	—
`key_scope`	`workflow` \| `project` \| `conversation` \| `issue` \| `lane`	no	—
`cached_content_id`	string	no	—

`agent.budget`

Field	Type	Required	Constraints
`tokens`	integer (or `{{var}}` template)	no	—
`wall_clock_minutes`	integer (or `{{var}}` template)	no	—
`minutes`	integer (or `{{var}}` template)	no	—

`agent.single_agent`

Field	Type	Required	Constraints
`select`	`fixed` \| `vendor_auto` \| `ordered`	yes	—
`runtime_key`	string	no	non-empty
`method`	`api` \| `sdk` \| `mcp` \| `cli` \| `desktop_app`	no	—
`dispatch_path`	`local` \| `cloud_managed`	no	—
`candidates`	array of object	no	—
`fallback_on_credit_exhausted`	boolean	no	—

`agent.single_agent.candidates[]`

Field	Type	Required	Constraints
`runtime_key`	string	yes	non-empty
`method`	`api` \| `sdk` \| `mcp` \| `cli` \| `desktop_app`	yes	—
`dispatch_path`	`local` \| `cloud_managed`	yes	—

`participants[]`

Field	Type	Required	Constraints
`provider`	string	no	—
`runtime_key`	string	no	non-empty
`model`	string	no	—
`method`	`api` \| `sdk` \| `mcp` \| `cli` \| `desktop_app`	no	—
`harness`	`claude_code` \| `custom` \| `default`	no	—
`dispatch_path`	`local` \| `cloud_managed` \| `auto`	no	—
`mcp_server_config`	object	no	—
`cli_flags`	object	no	—
`cli`	object	no	—
`workspace_mode`	`full_worktree` \| `workleaf_readonly`	no	—
`participant_id`	string	yes	non-empty
`role`	string	no	—
`aliases`	array of string	no	—
`reasoning_effort`	string	no	—
`thinking`	object	no	—

`participants[].cli`

Field	Type	Required	Constraints
`profile`	string	no	non-empty
`binary`	string	no	non-empty
`startup`	object	no	—
`mcp`	object	no	—
`skills`	object	no	—
`hooks`	object	no	—
`routine`	object	no	—
`experimental`	object	no	—

`participants[].cli.startup`

Field	Type	Required	Constraints
`approval_mode`	`supervised` \| `auto` \| `plan` \| `dontAsk` \| `bypass`	no	—
`sandbox`	`read-only` \| `workspace-write` \| `danger-full-access`	no	—
`resume`	boolean	no	—

`participants[].cli.mcp`

Field	Type	Required	Constraints
`servers`	array of string	no	—
`allowed_tools`	array of string	no	—

`participants[].cli.skills`

Field	Type	Required	Constraints
`include`	array of string	yes	—

`participants[].cli.hooks`

Field	Type	Required	Constraints
`include`	array of string	yes	—

`participants[].cli.routine`

Field	Type	Required	Constraints
`trigger`	string	no	non-empty
`steerable`	boolean	no	—

`participants[].cli.experimental`

Field	Type	Required	Constraints
`raw`	object	yes	—

`participants[].thinking`

Field	Type	Required	Constraints
`type`	`enabled` \| `disabled` \| `adaptive`	no	—
`budget_tokens`	integer (or `{{var}}` template)	no	—

`context`

Field	Type	Required	Constraints
`mode`	`off` \| `brief`	no	—
`max_input_tokens`	integer	no	min > 0
`max_output_tokens`	integer	no	min > 0
`dynamic_budget_tokens`	integer	no	min 0
`context_pack_budget_tokens`	integer	no	min 0, max 3000
`governed_query_limit`	integer	no	min 0
`recent_thinkids_limit`	integer	no	min 0
`graph_focus_limit`	integer	no	min 0
`cat_recall_limit`	integer	no	min 0
`evidence_excerpt_budget_tokens`	integer	no	min 0
`raw_prior_output_policy`	`forbid` \| `digest_only` \| `allow`	no	—
`compression_policy`	`deterministic_digest` \| `none`	no	—
`provider_cache`	object	no	—

`context.provider_cache`

Field	Type	Required	Constraints
`stable_prefix`	boolean	no	—
`dynamic_suffix`	boolean	no	—

`channel`

Field	Type	Required	Constraints
`mode`	`off` \| `live`	no	—
`topology`	`human_pair` \| `pair` \| `small_team` \| `review_panel`	no	—
`transport`	`in_process` \| `local_socket`	no	—
`human_seat`	boolean	no	—
`max_participants`	integer	no	min > 0, max 5
`max_hops`	integer	no	min > 0, max 3
`idle_timeout_s`	integer	no	min > 0
`max_messages_per_stage`	integer	no	min > 0
`max_bounces_per_pair`	integer	no	min > 0
`message_budget_tokens`	integer	no	min > 0
`stage_digest_budget_tokens`	integer	no	min > 0
`transcript_policy`	`digest_only`	no	—
`artifact_policy`	`refs_only`	no	—
`redaction_policy`	`standard`	no	—
`per_channel_lifetime_tokens`	integer	no	min > 0
`per_channel_lifetime_cost_usd`	number	no	min > 0
`floor`	object	no	—
`external_a2a`	`false`	no	—

`channel.floor`

Field	Type	Required	Constraints
`order`	`fifo` \| `round_robin`	no	—
`turn_cap_seconds`	integer	no	min > 0
`chat_char_cap`	integer	no	min > 0
`audio_mode`	`speak` \| `quiet`	no	—
`broadcast_aliases`	array of string	no	—

`budget`

Field	Type	Required	Constraints
`tokens`	integer (or `{{var}}` template)	no	—
`wall_clock_minutes`	integer (or `{{var}}` template)	no	—
`minutes`	integer (or `{{var}}` template)	no	—

`sandbox`

Field	Type	Required	Constraints
`workspace_write`	boolean	no	—
`network`	boolean \| array of string	no	—
`filesystem`	object	no	—

`sandbox.filesystem`

Field	Type	Required	Constraints
`allow`	array of string	no	—
`deny`	array of string	no	—

`tools`

Field	Type	Required	Constraints
`required`	array of string	no	—
`optional`	array of string	no	—

`cadence`

Field	Type	Required	Constraints
`owner`	`cadence`	yes	—
`domains`	array of `wiki` \| `graph_memory_cat_thinkid` \| `agent_conversation` \| `magic_canvas` \| `computer_control` \| `release`	yes	—
`run_contract`	object	yes	—
`resource_lifecycle`	object	yes	—
`event_contract`	object	no	—
`existing_resource_policy`	`reuse_or_ask` \| `reuse_existing` \| `create_new`	no	—

`cadence.run_contract`

Field	Type	Required	Constraints
`goal`	string	yes	non-empty
`success_criteria`	array of string	yes	—
`done_when`	array of string	yes	—
`non_goals`	array of string	no	—

`cadence.resource_lifecycle`

Field	Type	Required	Constraints
`leases`	array of string	no	—
`release`	array of string	yes	—
`terminal_cleanup`	boolean	no	—

`cadence.event_contract`

Field	Type	Required	Constraints
`progress`	array of string	no	—
`completion`	string	yes	non-empty
`failure`	string	no	non-empty

`retry`

Field	Type	Required	Constraints
`max_attempts`	integer	no	min > 0
`backoff_ms`	integer	no	min 0
`retryable_runtime_failures`	array of string	no	—
`runtime_failure_fallbacks`	array of object	no	—
`stale_base_merge_retry`	boolean	no	—
`human_review_after_attempts`	integer	no	min > 0

`retry.runtime_failure_fallbacks[]`

Field	Type	Required	Constraints
`failure_class`	string	no	—
`from_provider`	string	no	—
`from_runtime_key`	string	no	—
`provider`	string	no	—
`runtime_key`	string	no	—
`agent_runtime_key`	string	no	—
`model`	string	no	—

`merge_admission`

Field	Type	Required	Constraints
`request_slot`	boolean	no	—
`stale_base_retry`	boolean	no	—
`required_axes`	array of string	no	—
`fail_codes`	array of string	no	—

`workpad`

Field	Type	Required	Constraints
`required`	boolean	no	—
`evidence_required`	boolean	no	—

`cache_policy`

Field	Type	Required	Constraints
`enabled`	boolean	no	—
`strategy`	`auto` \| `explicit`	no	—
`ttl`	`provider_default` \| `5m` \| `1h` \| `24h`	no	—
`min_tokens`	`enforce` \| `best_effort`	no	—
`key_scope`	`workflow` \| `project` \| `conversation` \| `issue` \| `lane`	no	—
`cached_content_id`	string	no	—

`state_machine`

Field	Type	Required	Constraints
`type`	string	no	—
`start`	string	no	—
`stage_order`	array of string	no	—
`terminal_states`	array of string	no	—
`on_event`	object	no	—
`loop_caps`	object	no	—
`concurrency`	`sequential` \| `pipeline`	no	—
`states`	object	no	—
`loop`	object	no	—
`gate`	object	no	—

`state_machine.states.<name>`

Field	Type	Required	Constraints
`agent`	object	no	—
`output_schema`	object	no	—
`fan_out`	object	no	—
`gate`	object	no	—
`loop`	object	no	—

`state_machine.states.<name>.agent`

Field	Type	Required	Constraints
`runtime_key`	string	no	non-empty
`provider`	string	no	—
`model`	string	no	—
`role`	string	no	—
`task_template`	string	no	—
`max_turns`	integer (or `{{var}}` template)	no	—
`max_concurrent_agents`	integer (or `{{var}}` template)	no	—
`reasoning_effort`	string	no	—
`thinking`	object	no	—
`cache_policy`	object	no	—
`budget`	object	no	—
`display_name`	string	no	—
`naming_mode`	`first-and-last` \| `first-only` \| `last-only`	no	—
`routing_strategy`	`pair_programming` \| `single_agent_routine`	no	—
`single_agent`	object	no	—
`agent_tier`	`opus` \| `sonnet` \| `haiku`	no	—
`dispatch_path`	`local` \| `cloud_managed` \| `auto`	no	—

`state_machine.states.<name>.agent.thinking`

Field	Type	Required	Constraints
`type`	`enabled` \| `disabled` \| `adaptive`	no	—
`budget_tokens`	integer (or `{{var}}` template)	no	—

`state_machine.states.<name>.agent.cache_policy`

Field	Type	Required	Constraints
`enabled`	boolean	no	—
`strategy`	`auto` \| `explicit`	no	—
`ttl`	`provider_default` \| `5m` \| `1h` \| `24h`	no	—
`min_tokens`	`enforce` \| `best_effort`	no	—
`key_scope`	`workflow` \| `project` \| `conversation` \| `issue` \| `lane`	no	—
`cached_content_id`	string	no	—

`state_machine.states.<name>.agent.budget`

Field	Type	Required	Constraints
`tokens`	integer (or `{{var}}` template)	no	—
`wall_clock_minutes`	integer (or `{{var}}` template)	no	—
`minutes`	integer (or `{{var}}` template)	no	—

`state_machine.states.<name>.agent.single_agent`

Field	Type	Required	Constraints
`select`	`fixed` \| `vendor_auto` \| `ordered`	yes	—
`runtime_key`	string	no	non-empty
`method`	`api` \| `sdk` \| `mcp` \| `cli` \| `desktop_app`	no	—
`dispatch_path`	`local` \| `cloud_managed`	no	—
`candidates`	array of object	no	—
`fallback_on_credit_exhausted`	boolean	no	—

`state_machine.states.<name>.agent.single_agent.candidates[]`

Field	Type	Required	Constraints
`runtime_key`	string	yes	non-empty
`method`	`api` \| `sdk` \| `mcp` \| `cli` \| `desktop_app`	yes	—
`dispatch_path`	`local` \| `cloud_managed`	yes	—

`state_machine.states.<name>.output_schema`

Field	Type	Required	Constraints
`type`	`object` \| `array` \| `string` \| `number` \| `boolean`	no	—
`properties`	object	no	—
`items`	object	no	—
`required`	array of string	no	—

`state_machine.states.<name>.output_schema.items`

Recursive structure — same shape as __schema0 above.

`state_machine.states.<name>.fan_out`

Field	Type	Required	Constraints
`over`	string	yes	non-empty
`as`	string	yes	non-empty
`max_concurrency`	integer	no	min > 0
`background`	boolean	no	—

`state_machine.states.<name>.gate`

Field	Type	Required	Constraints
`human`	boolean	yes	—

`state_machine.states.<name>.loop`

Field	Type	Required	Constraints
`while_budget_remaining_gt`	integer	yes	min 0

`state_machine.loop`

Field	Type	Required	Constraints
`while_budget_remaining_gt`	integer	yes	min 0

`state_machine.gate`

Field	Type	Required	Constraints
`human`	boolean	yes	—

`roster[]`

Field	Type	Required	Constraints
`provider`	string	yes	non-empty
`runtime_key`	string	yes	non-empty
`model`	string	no	—
`method`	`api` \| `sdk` \| `mcp` \| `cli` \| `desktop_app`	no	—
`harness`	`claude_code` \| `custom` \| `default`	no	—
`dispatch_path`	`local` \| `cloud_managed` \| `auto`	no	—
`mcp_server_config`	object	no	—
`cli_flags`	object	no	—
`cli`	object	no	—
`workspace_mode`	`full_worktree` \| `workleaf_readonly`	no	—
`alias`	array of string	yes	—
`voice`	string	no	non-empty
`voice_name`	string	no	non-empty
`data_source`	object	no	—
`allowed_tools`	array of string	no	—
`context_budget_tokens`	integer	no	min > 0, max 200000

`roster[].cli`

Field	Type	Required	Constraints
`profile`	string	no	non-empty
`binary`	string	no	non-empty
`startup`	object	no	—
`mcp`	object	no	—
`skills`	object	no	—
`hooks`	object	no	—
`routine`	object	no	—
`experimental`	object	no	—

`roster[].cli.startup`

Field	Type	Required	Constraints
`approval_mode`	`supervised` \| `auto` \| `plan` \| `dontAsk` \| `bypass`	no	—
`sandbox`	`read-only` \| `workspace-write` \| `danger-full-access`	no	—
`resume`	boolean	no	—

`roster[].cli.mcp`

Field	Type	Required	Constraints
`servers`	array of string	no	—
`allowed_tools`	array of string	no	—

`roster[].cli.skills`

Field	Type	Required	Constraints
`include`	array of string	yes	—

`roster[].cli.hooks`

Field	Type	Required	Constraints
`include`	array of string	yes	—

`roster[].cli.routine`

Field	Type	Required	Constraints
`trigger`	string	no	non-empty
`steerable`	boolean	no	—

`roster[].cli.experimental`

Field	Type	Required	Constraints
`raw`	object	yes	—

`roster[].data_source`

Field	Type	Required	Constraints
`domain`	string	yes	non-empty
`symbols`	array of string	no	—

`execution`

Field	Type	Required	Constraints
`trigger_owner`	`cadence` \| `provider`	no	—
`provider_native_routine`	object	no	—

`execution.provider_native_routine`

Field	Type	Required	Constraints
`enabled`	boolean	yes	—

Validating

Validate before dispatch — Cadence rejects invalid frontmatter at load time. From an agent session, call the think_workflow_md_validate tool with your draft; it returns the same errors this schema produces.

​Top-level fields

​applies_to

​library

​agent

​agent.thinking

​agent.cache_policy

​agent.budget

​agent.single_agent

​agent.single_agent.candidates[]

​participants[]

​participants[].cli

​participants[].cli.startup

​participants[].cli.mcp

​participants[].cli.skills

​participants[].cli.hooks

​participants[].cli.routine

​participants[].cli.experimental

​participants[].thinking

​context

​context.provider_cache

​channel

​channel.floor

​budget

​sandbox

​sandbox.filesystem

​tools

​cadence

​cadence.run_contract

​cadence.resource_lifecycle

​cadence.event_contract

​retry

​retry.runtime_failure_fallbacks[]

​merge_admission

​workpad

​cache_policy

​state_machine

​state_machine.states.<name>

​state_machine.states.<name>.agent

state_machine.states.<name>.agent.thinking

state_machine.states.<name>.agent.cache_policy

state_machine.states.<name>.agent.budget

state_machine.states.<name>.agent.single_agent

state_machine.states.<name>.agent.single_agent.candidates[]

​state_machine.states.<name>.output_schema

state_machine.states.<name>.output_schema.items

​state_machine.states.<name>.fan_out

​state_machine.states.<name>.gate

​state_machine.states.<name>.loop

​state_machine.loop

​state_machine.gate

​roster[]

​roster[].cli

​roster[].cli.startup

​roster[].cli.mcp

​roster[].cli.skills

​roster[].cli.hooks

​roster[].cli.routine

​roster[].cli.experimental

​roster[].data_source

​execution

​execution.provider_native_routine

​Validating