Coordinator Roles - alexherrero/crickets GitHub Wiki
Note
Status: implemented. The coordinator roster shipped as loose agents/ role-definitions in developer-workflows 0.8.0 (V5-10 sibling #4 โ role-agent-defs) โ that plugin has since renamed to development-lifecycle (AG Wave A; developer-workflows still resolves as a declared-both-names capability alias). All four roles live under src/development-lifecycle/agents/.
The coordinator roster is four loose role-definitions that compose onto the developer-workflows phase loop. They are thin skins over capabilities that already exist โ no new engine, and no net-new sub-agent. Each role names a persona in the operator-as-coordinator flow (research โ author a plan โ execute it in a worktree โ integrate it โ read the queue) and binds to the commands and agents that already drive that step. Each entry below states what the role wraps, whether it's read-only or active, its tool allowlist, and any forward-reference to a surface not built yet.
| Role | Kind | Mode | Wraps | Drives the loop step |
|---|---|---|---|---|
researcher |
role | read-only ยท Read ยท Glob ยท Grep ยท WebFetch
|
explorer + its own WebFetch + forward-ref to the operator's global research agent |
the brief-research front of the loop |
tech-lead |
role | active ยท full access |
/design โ /plan
|
turns a brief into queued / named plans |
worker |
role | active ยท full access |
/work (one per worktree) |
the autonomous executor |
project-manager |
role | read-only ยท Read ยท Glob ยท Grep ยท Bash
|
/queue-status-lite |
the coordinator's read-model over the queue |
Note
Read-only vs active. A read-only role's tool allowlist excludes Write, Edit, and any state-mutating Bash โ it surfaces and decides nothing it writes. An active role authors or executes work (no tools: line = full access). researcher and project-manager are read-only; tech-lead and worker are active.
These are roles โ thin layers that compose onto surfaces development-lifecycle (formerly developer-workflows) already ships. Each is a loose agents/ role-definition (a sub-agent definition under src/development-lifecycle/agents/, beside the existing explorer.md / evaluator.md) that names a persona and points at the phase commands and agents that already do the work. A role adds no new mechanism โ it wraps shipped surfaces:
-
researcherdispatches the shippedexplorer(codebase fan-out) and runs its ownWebFetchfor light web lookups, and forward-references the operator's global research agent for deep / multi-source work โ composing with it when present, never vendoring or porting it. It fronts those capabilities without adding a fan-out engine of its own. -
tech-leadis the authoring persona for the/design โ /planstep โ both shipped;/designis the upstream authoring step,/planthe floor it sequences down to (see below). -
workeris the persona of a/worksession โ one per worktree, bound to its plan by the worktree-local.harness/active-planmarker thatworktree_marker.pywrites once/work's own auto-spawn step has created the worktree, integrated back via the auto-merging PRfinalize_unit.pyopens at the plan's final task. -
project-managerwraps the shipped/queue-status-literead-model.
Because each role is a thin skin, the engine it rides is documented on the surface it wraps โ see Named plans for the command surface and Evaluator / the agent specs for the agents.
The brief-research front of the loop โ the persona that answers "what do we actually know before we plan this?" It is a thin skin owning no new engine: it composes two capabilities that already exist plus one forward-reference.
-
In-repo fan-out. For "where does X live / how does Y work / what tests cover Z,"
researcherdispatches the shippedexplorersub-agent (read-onlyRead ยท Glob ยท Grep) and consumes its structuredfile:linesummary; it does not re-implement codebase exploration. -
Light web lookups. For a quick spec / API / changelog check,
researcherfetches directly with its ownWebFetch, bounded to a few targeted lookups rather than a crawl. -
Deep or multi-source research.
researcherforward-references the operator's global research agent (e.g. a personally-installedmemory-idea-researcher), composing with it when present and never vendoring, porting, or reaching into its internals. That agent is operator-personal and out of scope for this public plugin, soresearchernames it generically. When none is installed,researcherdegrades gracefully toexplorerplus its ownWebFetchโ still useful, just shallower.
Its allowlist is Read, Glob, Grep, and WebFetch; it cannot write, edit, or run mutating Bash. Output is a structured research finding (1โ3 sentence answer + file:line / web sources + open questions), never raw tool output; findings flow to tech-lead (/plan) or worker (/work), never into the tree itself.
The brief-to-plan authoring persona (full tool access): it turns a brief into an executable plan a worker can pick up. Its working tool today is the shipped /plan phase command, including the named-plan surface:
-
/plan --name <slug>โ author toPLAN-<slug>.mdinstead of the singleton. -
/plan --stage <slug>โ stage a plan into the inactivequeued-plans/tier (invisible to/workand/queue-status-lite). -
/plan --activate <slug>โ promote a staged plan to the activePLAN-<slug>.md(no-clobber guarded).
This lets tech-lead queue several plans and activate them one at a time, feeding the worker pool without singleton collisions. After it stages and activates a named plan, running /work against it is what hands the plan to a worktree โ /work's own auto-spawn step creates the worktree via the host's native primitive when authorized (an explicit operator instruction, or the durable isolation.mode: worktree-per-plan config opt-in โ never autonomous, Developer safety design); tech-lead produces plans, it does not spawn worktrees itself.
Note
/design is the shipped upstream step. The richer author โ translate โ sequence authoring path (/design, src/design/commands/design.md) shipped at crickets v3.11.0 (2026-06-14). tech-lead authors via /design when a brief needs the fuller translate-and-sequence treatment, and drops straight to /plan (its original floor) for briefs that don't. /design's output is a topo-ordered set of named plans that /plan still feeds one at a time.
The autonomous executor (full tool access) โ the persona of a /work session, one per worktree, not a sub-agent dispatched inside the coordinator. It binds to its plan via the worktree-local .harness/active-plan marker that worktree_marker.py writes once the host has created the worktree: a /work session launched inside the worktree-<slug> worktree resolves its own PLAN-<slug>.md from the marker โ no --name needed.
- Runs
/workautonomously through the bound plan's full task list, single-threaded, with the per-task safety pre-check gating each task (stop-and-ask only on a hard-to-reverse / ambiguous / scope-drifting / unverifiable task). - Gates green before every
[x]; one task, one commit; updatesPLAN-<slug>.md+progress-<slug>.md. - Closes the loop on its own, at the plan's final task:
finalize_unit.pypushes the branch, opens a PR carrying the plan's close-out summary, and armsgh pr merge --auto --squashโ the PR merges once required checks go green, with no separate operator-invoked integrate step./workthen runsExitWorktree keep, since the branch still has an open PR against it.
Never fans out parallel implementers โ single-threaded execution is the safety constraint everything else leans on, and the per-task safety check sets the autonomy boundary.
The read-only coordinator glance โ the persona that answers "what's the state of every plan in flight?" It wraps the shipped /queue-status-lite read-model, surfacing across every active plan:
- the active-plan binding(s) โ singleton and/or named
PLAN-<slug>.md, - each plan's progress at a glance,
- worker-worktree state (via the read-only
doctor_worktrees.pyprobe).
Its allowlist is Read, Glob, Grep, and Bash, and the Bash is read-only by contract โ it runs the queue_status.py reader and the read-only probes, never anything that mutates. It shows you the read-model's render exactly as produced: it marks no task done, writes no progress file, activates no plan, and merges nothing. Merge order stays a human decision (LC-5) โ the project-manager gives you the picture and leaves the call to you.
Note
crickets #41 (github-projects board-sync) has shipped as src/github-projects/scripts/project_sync.py โ a synced board view on top of the local queue, composing with project-manager's read-model. (A project_sync.py idempotency bug is tracked separately in R2.3; it doesn't affect this factual correction.)
project-manager still forward-references one later surface, not built here: V5-11 โ the chief-of-staff intelligence layer (/standup, readiness / safe-parallelization analysis, integration-order advisory โ still advisory; LC-5 stands). It composes with this when it ships.
-
Named plans โ the command surface the roles wrap:
/work,/plan,/queue-status-lite, and the auto-spawn / auto-close-out worktree flow inside/work. - Run a coordinator-directed worker team โ the playbook that ties the roster together end to end.
-
Evaluator โ a companion read-only agent in
development-lifecycle/agents/; the same tight-allowlist pattern the read-only roles follow. -
Run a named plan ยท See every active plan โ the worker-lifecycle recipes the
workerandproject-managerroles drive.