Coro workflows are Markdown files with YAML front matter between --- fences. At runtime parseWorkflowConfig() (packages/runner/src/workflow-parser.ts) extracts the YAML; the prose sections become human-readable guidance for operators and model prompts.
Top-level keys
| Key | Meaning |
|---|
display_name | Dashboard / documentation label |
description | Short summary surfaced in tooling |
kind | Taxonomy hint (job, campaign, internal, …) |
initial_phase | First phase name executed when a job adopts this workflow |
initial_status | Runner job.status seed (defaults derive from YAML or queued) |
phases | Ordered list — see below |
overrides | Map of logical trigger keys (jira, …) → { initial_phase } tweaks |
Note: display_name, description, and kind are documentation / dashboard signals; the deterministic phase machine keys off initial_phase, initial_status, and phases.
Phase object
| Field | Meaning |
|---|
name | Stable identifier referenced by goto_phase |
agent | Path to Markdown instructions (agents/foo.md) or null for agent-less phases (coordinating, tracking) |
model (optional) | Alias key (planning) or concrete provider model string — beats tier resolution |
tier (optional) | Capability bucket (planning, coding, mini). Parser defaults omitted tiers to planning. Typical bindings: planning → high-capability model, coding → implementation model, mini → lightweight subagents (e.g. inline code review). spec-writing in STANDARD/DEEP uses coding, not mini. |
provider (optional) | Executor plugin id (anthropic, openai, …) |
status | Human-facing status slug stored on job.status |
subagents (optional) | Lightweight child conversations (see below) |
interactive_checkpoint | When true (and interactive jobs enabled), runner parks until approval before advancing |
tools (optional) | Explicit allowlist replacing the default union of SDK built-ins + every mcp__coro__* tool |
Subagent object
| Field | Meaning |
|---|
name | Key used by run_subagent / native Task dispatch |
agent | Markdown path (defaults handled in workflow prose) |
model / tier / provider | Same resolution semantics as phases but scoped to the subagent |
tools | Tighter allowlist for the side conversation |
Merge + override behaviour
- Workflow files from repo
.coro/ or tenant overlays can replace the base file path-for-path.
- Trigger-specific
overrides let one Markdown serve multiple entry points (CLI vs Jira) without duplicating the entire workflow.
