ORCHESTRATION.md

September 20, 2026 · View on GitHub

Use when: hosts use evaluate / Jev as a supervisor primitive, or you are staffing more than one agent on this repo and need rungs, sprawl rules, and a lean roster.

House rules: ../AGENTS.md.
Concrete gates: VERIFICATION.md.
Product pattern source: ../docs/ROADMAP.md §23.

This is a single-binary MCP product, not a 45-bot studio. Most work is one implementer + observed task check. Multi-agent machinery exists so hosts can supervise workers with Jev — and so this repo stays lean when humans parallelize.

Jev as supervisor primitive (ROADMAP §23)

task
  ↓
worker selection        ← evaluate choice
  ↓
worker result
  ↓
result acceptance       ← evaluate noul / score
  ↓
rework / reviewer / specialist
  ↓
termination             ← evaluate noul

Useful questions (host asks → Jev answers → host executes):

Which worker should act next?
Can these tasks run independently?
Is this result sufficient?
Should a specialist review it?
Is the team done?

Jev does not spawn agents. Confidence is not a merge gate. task check / smoke / inspect still own landing safety (VERIFICATION.md).

Author questions from ../docs/jev/README.md. State = evidence only; never bake the answer into state.

Division of responsibility (product boundary — do not blur when staffing):

Host / generative agent  → research, plan, write, code, explain, delegate
evaluate / Jev           → classify, select, score, judge, route
Deterministic code/Task  → parse, enforce, execute, persist, prove

Resist new MCP tools per orchestration concern. evaluate already covers the judgment surface; host code runs the loop (ROADMAP expansion invariant).

When this repo needs more than one agent

Default: one scoped implementer, human or bot as verifier via Task.

Add a second agent only when context or parallelism actually splits:

Split	Why
Reproducer ‖ Implementer	Keep red path honest before a fix lands
Implementer ‖ Verifier	Proof owner does not author the diff
Setup specialist	Registration/rollback is its own blast radius
Docs	User-facing claims vs `tools.go` without blocking code

Before creating an agent: does an existing role only need a skills/ entry? New agents cost context forever. Two overlapping roles = sprawl this pack forbids.

Role shape (if you write one)

one ownership noun (roster/ templates)
tools/data it may use (task check, ./evaluate, docs/jev, tools.go)
approach (reproduce first; principle not incident)
human gates (keys, billing, destructive git, publish, product guesses)
source of truth document
does not own list (the part that stops sprawl)

Paste-ready files: ../roster/ — keep it at the lean set below.

Lean roster (this repo)

Role	Owns	File
Chief / dispatcher	Routing, status; optional	`../roster/chief-of-staff.md`
Reproducer	Red test or real `evaluate`/host path	`../roster/reproducer.md`
Implementer	One concern under `cmd/evaluate`	`../roster/implementer.md`
Verifier	Observed gates + proof in PR	`../roster/verifier.md`
Setup specialist	Adapters, pi template, rollback integrity	`../roster/host-setup-engineer.md`
Docs	README/docs ↔ `tools.go` / live docs	`../roster/docs-accuracy.md`

MCP contract work is Implementer territory with skill skills/mcp-contract.md — not a seventh standing bot unless contract changes are full-time.

Patterns (only when parallel work is real)

1. Chief of staff

One human-facing thread; routes to the lean set. Specialists still run their own task check. Skip the hop if you only have one worker.

2. Playbook broadcast

New standing rules go into AGENTS.md / agents/ / a skill once, principle not incident. Do not paste into every bot.

3. Staff meeting

Several viewpoints on a decision, instructed to disagree; optional evaluate choice/score over written options. Not for routine chores.

4. Sub-agent army

Low-context workers for batch jobs that fit this binary:

fuzz invalid payloads against offline validate
mechanical examples/*.json → validate()
table-driven setup dry paths

Live API swarms need spend caps. Parent audits; workers do not ping the human.

Standing policies (write once)

Urgent: smaller scope + faster proof — same gates. Never shout "urgent" to skip task check.

Failure: two failed attempts on one approach → report; do not loop.

Blocking: keys, billing, destructive git, publish, product guesses → human. Status = done / in progress / blocked; no change → "no change" or silence.

Off-track (if supervising runners): nudge sleep/drift/over-caution; never redefine done to skip verification.

Autopilot ladder

Name the rung in the instruction.

Rung	Means	Use when
Investigate	Diagnose only	Unclear cause; host misbehaviour; billing/key
Draft	Implement + PR; human merges	Default on this product
Autopilot	Implement + verify + land on green	Low blast radius; no setup-transaction / release / key risk
Full autopilot	Unattended plan→merge	Throwaway branches only

Tightening validateEvaluateResponse still requires task smoke on any autopilot rung. Pull back a rung when real hosts or real money are in play.

Cost model

You pay for agent tokens, tool use, and every Jev/API call. Five places the money goes:

Over-frequent routines — biggest leak; prefer events; audit cadence.
Browser where CLI exists — prefer task * / ./evaluate.
Group threads left running — one-to-one for routine work.
Roster sprawl — more bots → more context tax.
Uncapped live smoke / evals — EVALUATE_SMOKE=1 and harnesses spend real budget; flags + caps; keys/billing still stop-and-ask.

Levers: lower verbosity, drop dead context, batch independent evaluate questions, one skill instead of one bot.

Attention

More work done than ever; busier than ever.

Chief-of-staff or fewer bots is mitigation, not a cure. Budget attention like tokens and Jev calls.