Run A Coordinator Directed Worker Team - alexherrero/crickets GitHub Wiki

How to run a coordinator-directed worker team

Note

Goal: Run the full coordinator loop as one operator — take a brief through research, plan-authoring, isolated execution, integration, and a queue read — using the role roster as personas over the phase commands you already have. This is the capstone that ties the four V5-10 worker-team siblings together. Prereqs: the development-lifecycle plugin installed (Install crickets plugins) at 0.8.0 or later (the version that ships the role roster); a clean main working tree; a brief — the thing you want built. Read Coordinator roles first for what each role wraps and which are read-only.

You are the coordinator. The roster gives you four personas — researcher, tech-lead, worker, and project-manager — that are thin skins over the shipped phase commands (Coordinator roles), and this page walks through them once, in order, cross-linking each step's own recipe. Each role wraps a command you can also run bare; the roster just names the persona doing it.

Steps

  1. Research the brief (researcher). Front the loop with the read-only researcher role to scope the work before any plan exists. It wraps explorer for an in-repo fan-out ("where does X live / what tests cover Z") and runs its own WebFetch for a few targeted web lookups (a spec / API / changelog check). For deeper multi-source research it forward-references the operator's global research agent (e.g. a personally-installed memory-idea-researcher). It composes with that agent when one is present, and never vendors or ports it. When none is installed, it degrades gracefully to explorer plus its own WebFetch. Adopt the researcher persona (or paste its def from src/development-lifecycle/agents/researcher.md) and ask your scoping question; it returns a structured finding — a 1–3 sentence answer, the file:line / web sources backing it, and the open questions a planner needs. The output is a scoped brief, not a plan; because the role is read-only it makes no edits.

  2. Author the plan (tech-lead). Hand the scoped brief to the active tech-lead role — the brief-to-plan authoring persona (full tool access). For a brief that warrants the fuller design-doc treatment, run /design first (author → translate → sequence, shipped); otherwise its floor is /plan directly. Author a named plan and stage it into the inactive tier, then promote it when you are ready to run it: /plan --name <slug> (or --stage <slug> to park it in queued-plans/, invisible to /work and /queue-status-lite), then /plan --activate <slug> to promote the staged plan to the active PLAN-<slug>.md (no-clobber guarded). Staging then activating lets you queue several plans and turn them on one at a time without singleton collisions. See Run a named plan for the full staging / activation surface.

  3. Run /work — it spawns the worker's worktree for you. With isolation.mode: worktree-per-plan set in .harness/project.json (or an explicit operator instruction), running /work against the activated named plan auto-spawns the worktree at step 1.5, using the host's own worktree primitive — Claude Code's EnterWorktree, or Antigravity's New-Worktree-Mode / invoke_subagent. The worktree lands at .claude/worktrees/<name> on a branch named worktree-<name>, and worktree_marker.py writes the worktree-local .harness/active-plan marker that binds it to the plan, plus a .harness/worktree-for-<slug> pointer in the original root so a later session can find its way back. There's no separate spawn command — worktrees are still authority-gated (an explicit operator instruction or the durable config opt-in, never autonomous), just via /work itself rather than a dedicated command. Full recipe: Run a named plan.

  4. Execute the plan (worker). The active worker role is the persona of this /work session. One worker runs per worktree, works its plan's full task list autonomously, and stays single-threaded. Each task is gated by the per-task safety pre-check — it works straight through and only stops to ask on a hard-to-reverse, ambiguous, scope-drifting, or unverifiable task. It gates green before every [x], commits one task per commit, and updates PLAN-<name>.md + progress-<name>.md as it goes. It never fans out parallel implementers — single-threaded execution is the safety constraint the whole loop rests on. Several workers can run concurrently, each in its own worktree bound to its own plan, without colliding.

  5. /work closes the loop itself, on the plan's final task. finalize_unit.py pushes the worktree's branch, opens a PR carrying the plan's close-out summary as its description, and arms gh pr merge --auto --squash. The PR merges once its required checks — the full deterministic battery, gated by branch protection — go green, with no further operator invocation; a red check simply blocks the merge, so there's nothing to roll back by hand. /work then runs ExitWorktree keep, since the branch still has an open PR against it. A periodic sidecar, worktree_shepherd.py, reclaims worktrees left behind after their PR merges and rebases any PR GitHub reports as BEHIND its base.

  6. Read the queue (project-manager). At any point, adopt the read-only project-manager role to look over the whole queue. It wraps /queue-status-lite, which lists every active plan — its binding, its latest progress line, and the state of any worker worktree, read through the doctor_worktrees.py probe. The role only shows you that render; it changes nothing on disk. It is a glance, not a gate: merge order stays a human decision (LC-5), so what to /work next is your call. crickets #41 (github-projects board-sync — a synced board view) has landed and composes with this glance; V5-11 (the chief-of-staff intelligence layer — /standup, readiness signals, integration-order advisory, still advisory) remains forward-referenced. Full recipe: See every active plan.

Verify

  • Each step's verify is the verify of the command it drives — see the per-step how-tos linked above.
  • After step 2, /plan --activate <slug> leaves an active PLAN-<slug>.md; after step 3, the worktree-<name> worktree exists with a .harness/active-plan marker holding the bare slug.
  • The whole loop is complete when the plan's PR merges (the full gate battery passing as the required check on the merge), and a fresh project-manager glance via /queue-status-lite shows the plan dropped from the active queue.

Troubleshooting

  • /work can't find a plan inside the worktree. The .harness/active-plan marker binds it — confirm you're inside the worktree /work's auto-spawn step created, not back on main. Run /work bare there; do not pass --name.
  • A resumed session is running in the main clone, not the plan's worktree. Step 1.5's re-entry branch reads .harness/worktree-for-<slug> in the original root; run /work --name <slug> and it re-enters on its own. If it reports a stale pointer, the recorded worktree is gone, deregistered, or now bound to another plan — the session carries on in the main clone rather than stopping, and worktree_marker.py clear <slug> drops the pointer once you've confirmed the worktree really is gone. If it reports no pointer at all, that plan predates the pointer or was spawned by hand: enter the worktree yourself once, and the next close-out leaves things consistent.
  • The plan's PR won't merge. The gate battery is a required status check on the PR — a red run simply blocks the merge until it's fixed. Fix the failure in the worker's worktree, push again, and let the check re-run; there's no separate rollback step, since nothing merged in the first place.
  • project-manager shows a stale or orphaned plan. The PM only reads; it never prunes. Use the doctor_worktrees.py probe / See every active plan to spot an orphaned worktree — worktree_shepherd.py reclaims it automatically once it's old enough and provably safe, or clean it up by hand through the worker lifecycle. The PM will not do it for you.
  • Per-command failure modes (spawn guards, PR-merge gating) live on each step's how-to; this page only sequences them.

Related

  • Coordinator roles — the roster: what each role wraps, read-only vs active, tool allowlists, and the forward-references.
  • Run a named plan — the write-side recipe behind step 2: authoring + staging + activating a named plan, and the auto-spawn / auto-close-out flow behind steps 3 and 5.
  • See every active plan — step 6: the read-only glance over the plan queue.
  • Named plans — the command surface the whole loop rides.
⚠️ **GitHub.com Fallback** ⚠️