Skip to content

Coordinator

The coordinator scopes a task, designs a DAG of agent tasks, gets your approval, then executes it in waves by spawning subagents. It is deliberately lightweight: there is no runtime, no long-running server, and no execution engine of its own — it rides the editor's native subagent spawning and tracks the graph over MCP. See Why Angelo, not a framework.

The flow

  1. Scope the task (no subagent) — affected files, complexity, tests, risk.
  2. Design a task graph from the agent roster at a chosen rigor level, selecting checkers by what the change touches (see Choosing checkers).
  3. Approve — the graph is presented for sign-off.
  4. Execute in waves — claim tasks, spawn subagents in parallel, wait for the whole wave, handle failures via bounded extensions.
  5. Report and record outcomes to the memory tree.

A typical run is a small DAG executed in waves — one implementer, then the read-only checkers in parallel, then the memory agent last:

A task graph executing in waves: engineer, then reviewer/critic/tester in parallel, an appended fix cycle, then memory

One implementer runs first; the read-only checkers run in parallel; a failed review appends a bounded fix cycle; the memory agent records the outcome last.

Agent roster

Every task graph is built from a roster of agents, each with a role (implementer, planner, checker, meta) that fixes where it can sit in the graph. Coordinator-native agents (engineer, reviewer, critic, tester, memory) run from a persona on any host; Cursor built-ins (explore, bugbot, security-review) map to the editor's own subagents and fall back to a persona elsewhere. Custom agents live in .cursor/agents.yaml. See Agent roster for the full tables, roles, and host-native behavior.

Rigor: how hard a run tries

Every run has a rigor level (low / medium / high) that controls two levers at once:

  • Extension cycles — how many corrective re-runs a failed check may append before the coordinator escalates to you (max_extensions: 1 / 3 / 5).
  • Self-refinement passes — how many internal passes a checker makes on a single run.

Rigor is chosen during scoping and confirmed before the graph runs, so a risky, cross-cutting change can be told to try harder while a typo fix stays cheap. Failures are handled on-graph: a reviewer FAIL appends an [engineer, reviewer] fix cycle rather than silently patching, so every correction stays visible on the dashboard.

Choosing checkers

The roster carries five read-only checkers (reviewer, critic, tester, bugbot, security-review) and they overlap, so the coordinator does not run all of them on every task. Selection follows two independent axes: surface (what the change touches) decides which checkers are relevant, and rigor decides the inclusion threshold and effort. reviewer is the baseline; every other checker is earned by the surface. The selected panel — and any deliberately skipped — is shown with a one-line justification at graph approval, so you can veto or add one. See Choosing checkers for the full table, the critic vs bugbot distinction, and how verdicts are aggregated per wave.

How agents run in parallel

Because all subagents share one workspace, two implementers must never write the same path at once. The coordinator takes a path-scoped write lease from each task's declared writes: implementers with disjoint scopes run concurrently in the same wave, and only overlapping ones serialize. Read-only checkers (reviewer, critic, tester, bugbot, security-review) always run in parallel. This is the whole of angelo's concurrency model — no scheduler, no locks beyond the lease.

Watching a run

A live run is visible in the memory dashboard's Coordinator tab, drawn as the task graph at the tree node where it records output. Active runs update as waves advance; stale runs (whose process died) are flagged for manage_runs resume; completed runs keep their final graph.

The memory dashboard Coordinator tab: an active coordinator run with its task graph, plus stale and recently completed runs

The Coordinator tab — a live run's wave graph up top, with stale/stranded and recently completed runs below.

Commands

Natural-language phrasings that trigger the coordinator — say the thing, the agent runs it. See the full command cheatsheet.

Say this What runs
"coordinate this", "use the coordinator", "run the pipeline", "spin up agents for this" Scope → design a task graph → execute in waves (create_graph)
"run overnight", "let it cook", "independent run", "keep going while I'm away" An unattended run: keep-awake + pre-cleared approvals, higher rigor, no mid-run prompts
"be thorough", "high rigor", "red-team this" rigor="high" with a fuller checker panel and more extension cycles
"just do it", "low rigor", "quick and cheap" rigor="low" (or a solo engineer for trivial work)
"extract this corpus", "grounded extraction over these sources" create_extraction_graph
"resume that run", "pick the stranded run back up" manage_runs(action="resume")

Design notes

The decisions behind this, drawn as a slice of the memory tree.

  • D Path-scoped write coordination: per-path coordinator lease + per-box zettelkasten locksactive
    Replaced the coordinator's global one-implementer-at-a-time write lease with fine-grained path-scoped coordination.
  • A Coordinator must declare narrow per-task writes leases, not default to whole-workspace
    User preference (affects future coordinator runs): when spawning implementer tasks via create_graph/extend_graph, ALWAYS declare a narrow per-task writes scope (the actual files/dirs the engineer will touch) instead of…

Semantically related entries from the memory graph.