team-orchestration
Skill4 starsChanged 47 days agoMITView on GitHub
Run planning, right-sizing, gate enforcement, routing and the utilisation check for the team. Use when opening a run (the kickoff interview while PROJECT.md still carries TODO markers, the toolchain pre-flight, writing run.json from the run plan template and expanding its placeholders), when deciding which roles a change needs and recording why each other role is omitted, when dispatching an agent or routing a handoff that came back, when syncing gates and running the utilisation check after a stage, when judging a stall or a rejection loop, when writing a ledger line (including a decision line for every Product Lead answer and acceptance), and when closing a run with the report for the Product Lead.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- BonBear/open-ps3005dtheir own version, first seen Nov 15, 2026
- swap-cameroon/kuro-antigravity-configtheir own version, first seen Nov 15, 2026
- NoobyGains/godmodetheir own version, first seen Nov 1, 2026
- darker2016/WorkbuddySkillGroups4DSHtheir own version, first seen Aug 14, 2026
- thebiglaskowski/claude-sentienttheir own version, first seen Apr 7, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- NoobyGains/godmode★ 120same name
- darker2016/WorkbuddySkillGroups4DSH★ 6same name
- swap-cameroon/kuro-antigravity-config★ 2same name
- thebiglaskowski/claude-sentient★ 2same name
- BonBear/open-ps3005d★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- stack-nextjs-supabaseSkill
- team-architectureSkill
- team-brand-guardSkill
- team-bug-registerSkill
- team-clean-codeSkill
- team-code-analysisSkill
- team-code-reviewSkill
- team-copySkill
- team-design-systemSkill
- team-protocolSkill
- team-releaseSkill
- team-securitySkill
- team-test-protocolSkill
- team-ux-auditSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
31 rules. 0 are common, 3 are distinctive, and 28 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
28
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 62
Every stack, product and locale fact an agent needs comes from PROJECT.md, by section heading.
- Distinctive: line 70
Ask about one section at a time.
- Very specific: line 82
Write the answer into that section in place of the marker, then read it back.
- Very specific: line 91
When a pack is named, run the setup section of its SKILL.md.
- Distinctive: line 98
Ask before installing anything a setup section lists.
- Very specific: line 99
Search for TODO: once more.
- Very specific: line 102
When the session cannot put questions to the Product Lead (a headless run, for example), stop before opening the run and list the sections …
- Very specific: line 108
Run it after the run opened line and before the first dispatch.
- Very specific: line 125
Write every check to evidence/toolchain-preflight.log, one line each, with the shell timestamp, the command or call, and the answer or the …
- Very specific: line 163
Read the brief. brief in run.json is the Product Lead's words, verbatim.
- Very specific: line 164
Read PROJECT.md in full, at the moment you plan.
- Very specific: line 165
Read BUGS.md: the standing rules that bind the orchestrator, and the entries on the surfaces the brief names.
- Very specific: line 167
Read the gate table below, so the names you write into run.json are the names the owners write back.
- Very specific: line 311
Remove every gate whose owner is omitted from gates, and remove its name from every remaining blocked_by and blocks.
- Very specific: line 315
Remove every omitted role's artefacts from the remaining entries' consumes.
- Very specific: line 318
Remove an artefact from its producer's produces when every planned consumer of it is omitted, and say so in that producer's dispatch brief.
- Very specific: line 321
When release-engineer is omitted, set ships to false, remove the release gate, and give bug-historian's stage 12 entry blocked_by: …
- Very specific: line 351
Never add one to a later entry's consumes: a record that is sometimes not written would leave that entry never due.
- Very specific: line 376
Before the first dispatch, interrogate the plan and write the answers into orchestrator/plan.md under a heading ## Audit, with what you …
- Very specific: line 493
Every handoff comes back to you.
- Very specific: line 510
When the Product Lead answers, append a decision line that quotes their words, names the handoff and the question it answers, and records …
- Very specific: line 524
Stop and put the decision to the Product Lead, named in PROJECT.md § Product Lead, through decisions_for_product_lead in the orchestrator's …
- Distinctive: line 616
After every handoff you read, sync the gates, so a gate that just passed can open the next entry.
- Very specific: line 767
Write the result to orchestrator/review.md as a table with one row per planned entry, not only the failures, so the absence of a row is …
- Very specific: line 811
Every entry in run.json plan has a handoff on disk for its pass, with a status of passed, blocked, rejected or escalated.
- Very specific: line 813
Every path in every produced array exists and is non-empty.
- Very specific: line 814
Every output meant to feed another role appears in a later agent's consumed.
- Very specific: line 815
Every gate in run.json gates reads pass, recorded by its owner, with an evidence path that exists.
- Very specific: line 817
No open blocker and no unanswered decisions_for_product_lead, and every answer and acceptance the Product Lead gave has its own decision …
- Very specific: line 828
Write the closing handoff, handoff-stage<N>.json for the last stage in the plan, with run-closure in gates[], orchestrator/report.md as its …
- Very specific: line 831
Run the pair once more, so run.json reads run-closure: pass and the check is clean.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Orchestration
This is the orchestrator's toolkit. The orchestrator proves that the right roles did the work in the right order, and that each gate was resolved by the role that owns it. It does none of the work itself.
One question runs through everything below, and the orchestrator asks it after every stage: did every agent that should have run actually run, and was every agent that ran actually used?
This skill is the specification. .devteam/bin/sync-gates.mjs and
.devteam/bin/utilisation-check.mjs are its implementation, and .devteam/README.md
explains the run folder they read. The orchestrator's definition,
.claude/agents/orchestrator.md, carries the same run plan template and the same routing
table. The two are kept identical, and a check compares the templates byte for byte.
The orchestrator's place
The orchestrator runs as the main thread of the session and is the only role that
dispatches. .claude/settings.json sets "agent": "orchestrator", so a plain session opened
in the project is already the orchestrator, and claude --agent orchestrator starts one
explicitly. Every other agent runs as its subagent with the Agent tool disallowed. None of
them dispatches, re-runs or rejects directly to another: they set next and
blockers[].needs in their handoff and return, and the orchestrator routes.
A dispatch has to land in the ledger and in the utilisation check. One made by any other role lands in neither, and afterwards reads as a skipped gate.
A small, self-contained change may go straight to the responsible agent when the Product Lead asks for that. The orchestrator still records the run afterwards and runs the utilisation check at the end, because no other role checks that the gates held.
Opening a run
A run opens in this order, and nothing is dispatched until the last step.
| # | Step | Ledger line |
| 1 | Kickoff, only while PROJECT.md carries a TODO: outside its worked example. No run folder exists yet. | Written at step 2 |
| 2 | Create the run folder and ledger.md | run opened, then kickoff naming the sections filled in this session, when there were any |
| 3 | The toolchain pre-flight, written to evidence/toolchain-preflight.log | toolchain pre-flight |
| 4 | Write run.json from the template, right-sized, and orchestrator/plan.md with its ## Audit | Cited in the step 5 line |
| 5 | Write orchestrator/handoff.json with stage 0 and next set to bug-historian | handoff |
| 6 | Dispatch bug-historian, before any other agent plans | dispatch |
Opening a run is work with a standard, but it is not a gate, so it never goes in gates[],
where an unlisted name raises UNKNOWN_GATE. It is done when PROJECT.md has no TODO:
left, run.json exists with a non-empty plan, gates and done_means, every omission has
a reason, the audit is written and the pre-flight is on disk.
Kickoff: filling PROJECT.md
Every stack, product and locale fact an agent needs comes from PROJECT.md, by section
heading. Before opening a run, search it for TODO:, ignoring the worked example inside its
HTML comment. If any marker remains, the project has not been profiled yet, and the
orchestrator interviews the Product Lead before anything else.
- Take the twelve sections in their shipped order: Product, Product Lead, Stack, Commands,
Toolchain, Stack pack, Locales, Brand, Product invariants, Quality bar, Release, House
rules. Skip a section with no
TODO:left. - Ask about one section at a time. Say in one line what the section is for and which roles
read it. Where the section ships a default (the widths and WCAG 2.2 AA in Quality bar,
deferred: no target chosenin Release, no attribution in House rules,BRAND.mdin Brand), offer it and ask the Product Lead to confirm or change it. In Toolchain, say that the root.mcp.jsondeclares the Playwright MCP server for qc-engineer and qc-lead, and ask whether the project keeps it. On a yes, list it as present. On a no, ask before removing its entry from.mcp.jsonandplaywrightfromenabledMcpjsonServersin.claude/settings.json, and leave it out of the section. Remove the two together and change nothing else, the permission rules and the.playwright-mcp/line in.gitignoreincluded:scripts/check.mjsreads both gone as a decline and passes it, fails on one without the other, and still requires the five permission rules the server depends on, and that line. - Write the answer into that section in place of the marker, then read it back. Never
rename, reorder or merge a heading, because every agent finds its facts by heading.
noneis a valid answer in Commands and Stack pack. A section is never filled with a guess. - State each product invariant as a rule the data layer or the server can refuse to break, numbered I1, I2 and on. A rule only the client can hold is written down with that limitation named.
- For Stack pack, list the
stack-*folders under.claude/skills/and suggest the one that matches the Stack section, ornone. Where a pack is chosen, offer its command set as the default for Commands. - When a pack is named, run the setup section of its
SKILL.md. Forstack-nextjs-supabasethat is its Kickoff setup: add thesupabaseentry from.claude/skills/stack-nextjs-supabase/templates/mcp.jsonto the root.mcp.json, beside the team'splaywrightentry, creating the file from the template only when there is none and never replacing it or changing another server's entry, replace<project-ref>with the ref the Product Lead gives, and put no key or token in the file. Then tell the Product Lead to authorise the server with/mcp, and that it loads in the next session. Ask before installing anything a setup section lists. - Search for
TODO:once more. Open the run only when none remain outside the worked example.
When the session cannot put questions to the Product Lead (a headless run, for example),
stop before opening the run and list the sections that still carry TODO:. A missing fact is
asked for, never invented.
Toolchain pre-flight
Run it after the run opened line and before the first dispatch.
| Check | Command or call | Source |
| git | git --version | The core. Always checked. |
| node | node --version | The core. Always checked. |
Every tool PROJECT.md § Toolchain lists as present | Its version command | The project profile |
The Playwright MCP server, when PROJECT.md § Toolchain lists it | claude mcp list, from the project root. It answers when its playwright: line ends Connected. Pending approval, Failed or no line at all is a server that does not answer | The team's .mcp.json |
| Whatever the stack pack's pre-flight asks for | As its SKILL.md states | The pack named in PROJECT.md § Stack pack, read by path at .claude/skills/<pack>/SKILL.md |
For stack-nextjs-supabase, the section is Pre-flight at run open: npm --version,
npx --version, npm ls @electric-sql/pglite at the project root, and one list_tables
call through the Supabase MCP. That one read is the only call the orchestrator ever makes
through a project's MCP server. It never applies, queries or changes anything through one.
claude mcp list makes no call through a server: it asks Claude Code whether each server
starts. The orchestrator never calls a Playwright tool.
Write every check to evidence/toolchain-preflight.log, one line each, with the shell
timestamp, the command or call, and the answer or the exact error:
# Toolchain pre-flight · 2026-10-01-invoice-export
2026-10-01T08:03:05Z git --version git version 2.47.1
2026-10-01T08:03:05Z node --version v24.1.0
2026-10-01T08:03:06Z npm --version 11.3.0 stack pack
2026-10-01T08:03:06Z npx --version 11.3.0 stack pack
2026-10-01T08:03:08Z npm ls @electric-sql/pglite (empty) stack pack: offline proof unavailable
2026-10-01T08:03:09Z list_tables (supabase MCP) auth error supabase MCP not authorised
2026-10-01T08:03:12Z claude mcp list playwright: Connected| Result | Do this |
| Everything answers | Dispatch as planned. |
| git or node is missing | Stop and escalate. No stage can run. |
| A tool the Toolchain section lists is missing | Escalate, and plan no stage that needs it until a re-run of the check answers. |
| A check the stack pack lists fails | Do what the pack's table says for that row, and escalate where it says so. |
| An MCP server does not answer (its tools are missing, or the call returns an auth error) | Record <server> MCP not authorised in the ledger and in the stage 0 handoff's blockers, with needs set to product-lead, who authorises it with /mcp. Dispatch no entry that needs the server until a re-run answers. Still dispatch every entry that does not. |
Decide at planning time which plan entries need which server, and write that list in
orchestrator/plan.md. The stack pack names them for its own server. No entry needs the
Playwright MCP server to pass, because gate evidence comes from the suite, so a Playwright
server that does not answer is escalated and holds nothing, and qc-engineer and qc-lead name
the cases that needed it (team-test-protocol, When the MCP does not answer). An agent that
finds a server missing mid-run runs whatever offline proof its stack pack defines and hands off
blocked with the same reason, and it routes to the Product Lead the same way. A missing tool
is reported as blocked, never faked, and a result is never accepted in place of a tool that
did not run.
Planning the run
Before you write the plan
- Read the brief.
briefinrun.jsonis the Product Lead's words, verbatim. - Read
PROJECT.mdin full, at the moment you plan. - Read
BUGS.md: the standing rules that bind the orchestrator, and the entries on the surfaces the brief names. - Read the gate table below, so the names you write into
run.jsonare the names the owners write back. - Find prior runs on the same surface by searching
.devteam/runs/*/run.jsonfor the surface name, and read theorchestrator/report.mdof any that match. Runs are gitignored, so a fresh clone may have none, andBUGS.mdis the durable record. - Take every timestamp from the shell,
date -u +%Y-%m-%dT%H:%M:%SZ, never from memory.
The run plan template
The run id is <yyyy-mm-dd>-<short-slug>, for example 2026-10-01-invoice-export. The run
folder is .devteam/runs/<run-id>/, or <run-id>/ under DEVTEAM_RUNS_DIR where that is
set. run.json is written before anything is dispatched, and every run.json follows this
template. .claude/agents/orchestrator.md carries the identical block, and in the team's own
repository node scripts/check.mjs fails when the two differ by a single byte, so never edit
one without the other.
{
"run": "2026-10-01-invoice-export",
"brief": "Let account owners export a month of invoices as CSV from the billing page, in every locale, without exposing invoices from any other account.",
"opened": "2026-10-01T08:02:11Z",
"ships": true,
"done_means": [
"An account owner can export one calendar month of their own invoices as CSV from the billing page.",
"The export can never contain a row from another account, proved at the data layer, not in the client.",
"The page and the file work in every locale in PROJECT.md, at every width in the quality bar."
],
"out_of_scope": [
"Scheduled or emailed exports."
],
"plan": [
{ "stage": 1, "agent": "bug-historian", "task": "Regression brief: what has already broken on these surfaces", "consumes": ["run.json"], "produces": ["bug-historian/brief.md"], "blocked_by": [] },
{ "stage": 1, "agent": "tech-architect", "task": "ADR and task briefs for this change", "consumes": ["run.json", "bug-historian/brief.md"], "produces": ["tech-architect/adr-NNNN-<slug>.md", "tech-architect/brief-frontend.md", "tech-architect/brief-backend.md"], "blocked_by": [] },
{ "stage": 2, "agent": "ux-designer", "task": "Design spec, every surface and every state", "consumes": ["tech-architect/brief-frontend.md", "bug-historian/brief.md"], "produces": ["ux-designer/spec.md", "ux-designer/string-slots.json"], "blocked_by": ["design-authority"] },
{ "stage": 2, "agent": "backend-engineer", "task": "Data layer, API and the tests that prove the invariants", "consumes": ["tech-architect/brief-backend.md", "bug-historian/brief.md"], "produces": ["backend-engineer/files.md"], "blocked_by": ["design-authority"] },
{ "stage": 3, "agent": "ux-auditor", "task": "Independent audit of the design spec", "consumes": ["ux-designer/spec.md", "bug-historian/brief.md"], "produces": ["ux-auditor/findings.md"], "blocked_by": [] },
{ "stage": 4, "agent": "ux-writer", "task": "Every string for every new surface, in every locale", "consumes": ["ux-designer/spec.md", "ux-designer/string-slots.json", "ux-auditor/findings.md", "bug-historian/brief.md"], "produces": ["ux-writer/strings.md", "ux-writer/strings-<locale>.json"], "blocked_by": ["design"] },
{ "stage": 5, "agent": "frontend-engineer", "task": "Interface implementation against the approved spec", "consumes": ["tech-architect/brief-frontend.md", "ux-designer/spec.md", "ux-writer/strings-<locale>.json", "bug-historian/brief.md"], "produces": ["frontend-engineer/files.md"], "blocked_by": ["design", "copy"] },
{ "stage": 6, "agent": "peer-reviewer", "task": "Senior review: judgement, boundaries, failure modes", "consumes": ["backend-engineer/files.md", "frontend-engineer/files.md", "bug-historian/brief.md"], "produces": ["peer-reviewer/verdict.json", "peer-reviewer/comments.md"], "blocked_by": [] },
{ "stage": 6, "agent": "code-analyst", "task": "Line-by-line defects and structural rot", "consumes": ["backend-engineer/files.md", "frontend-engineer/files.md", "bug-historian/brief.md"], "produces": ["code-analyst/findings.md"], "blocked_by": [] },
{ "stage": 6, "agent": "code-steward", "task": "Clean code: naming, shape, module headers, comments", "consumes": ["backend-engineer/files.md", "frontend-engineer/files.md", "bug-historian/brief.md"], "produces": ["code-steward/findings.md"], "blocked_by": [] },
{ "stage": 6, "agent": "security-analyst", "task": "Security sweep: secrets, exposure, access control, injection, dependencies, failure handling", "consumes": ["backend-engineer/files.md", "frontend-engineer/files.md", "bug-historian/brief.md"], "produces": ["security-analyst/findings.md", "evidence/security/"], "blocked_by": [] },
{ "stage": 7, "agent": "bug-historian", "task": "Regression guard: was a known defect repeated", "consumes": ["bug-historian/brief.md", "backend-engineer/files.md", "frontend-engineer/files.md"], "produces": ["bug-historian/guard.md", "evidence/regression/"], "blocked_by": ["review-judgement", "review-defects", "review-readability", "security"] },
{ "stage": 8, "agent": "engineering-lead", "task": "Integration: does it build, migrate and run end to end", "consumes": ["peer-reviewer/verdict.json", "peer-reviewer/comments.md", "code-analyst/findings.md", "code-steward/findings.md", "security-analyst/findings.md", "bug-historian/guard.md"], "produces": ["engineering-lead/verdict.md", "evidence/build.log"], "blocked_by": ["review-judgement", "review-defects", "review-readability", "security", "regression-guard"] },
{ "stage": 9, "agent": "qc-engineer", "task": "Test the contract, the invariants, the flows, accessibility, locales and regressions", "consumes": ["engineering-lead/verdict.md", "bug-historian/brief.md"], "produces": ["qc-engineer/test-log.md", "qc-engineer/defects.md", "evidence/<test artefacts>"], "blocked_by": ["engineering"] },
{ "stage": 10, "agent": "qc-lead", "task": "Evidence audit and independent final pass", "consumes": ["qc-engineer/test-log.md", "qc-engineer/defects.md", "evidence/<test artefacts>"], "produces": ["qc-lead/readiness.md"], "blocked_by": [] },
{ "stage": 11, "agent": "release-engineer", "task": "Pre-flight, release, tag, verify", "consumes": ["qc-lead/readiness.md"], "produces": ["release-engineer/preflight.md", "release-engineer/release-log.md", "release-engineer/release-note.md", "release-engineer/rollback.md", "evidence/release/"], "blocked_by": ["quality"] },
{ "stage": 12, "agent": "bug-historian", "task": "Record: every defect and agent mistake raised in this run, into BUGS.md", "consumes": ["qc-engineer/defects.md", "qc-lead/readiness.md", "bug-historian/guard.md"], "produces": ["bug-historian/record.md"], "blocked_by": ["release"] }
],
"omitted": [],
"gates": [
{ "name": "design-authority", "owner": "tech-architect", "blocks": ["ux-designer", "backend-engineer"], "result": "pending" },
{ "name": "design", "owner": "ux-auditor", "blocks": ["ux-writer", "frontend-engineer"], "result": "pending" },
{ "name": "copy", "owner": "ux-writer", "blocks": ["frontend-engineer"], "result": "pending" },
{ "name": "review-judgement", "owner": "peer-reviewer", "blocks": ["bug-historian", "engineering-lead"], "result": "pending" },
{ "name": "review-defects", "owner": "code-analyst", "blocks": ["bug-historian", "engineering-lead"], "result": "pending" },
{ "name": "review-readability", "owner": "code-steward", "blocks": ["bug-historian", "engineering-lead"], "result": "pending" },
{ "name": "security", "owner": "security-analyst", "blocks": ["bug-historian", "engineering-lead"], "result": "pending" },
{ "name": "regression-guard", "owner": "bug-historian", "blocks": ["engineering-lead"], "result": "pending" },
{ "name": "engineering", "owner": "engineering-lead", "blocks": ["qc-engineer"], "result": "pending" },
{ "name": "quality", "owner": "qc-lead", "blocks": ["release-engineer"], "result": "pending" },
{ "name": "release", "owner": "release-engineer", "blocks": ["bug-historian"], "result": "pending" },
{ "name": "run-closure", "owner": "orchestrator", "blocks": [], "result": "pending" }
],
"utilisation": []
}Field rules
| Field | Rule |
run | The run id. Every agent in the run uses the same one. |
brief | The Product Lead's words, verbatim. |
opened | From the shell. |
ships | true when release-engineer is planned, false when it is in omitted. |
done_means | Every line checkable against a file, a log or a screenshot. Rewrite a line until it is. |
out_of_scope | Named so no role reads a gap as an oversight. |
plan | One entry per pass. An agent that runs more than once has one entry per pass, each with its own stage. Two entries that share a stage number run in parallel once both are due. |
consumes, produces | Paths relative to the run folder, fully expanded. The check measures every handoff against them, so an entry with an empty produces cannot be verified. |
blocked_by | Gate names, never agent names. Every name is in gates, and that gate's blocks lists this agent. |
omitted | One object per plan entry left out, with its reason. See Right-sizing. |
gates | The twelve canonical names, minus any whose owner is omitted. Never rename one for a run: the owner writes the same name back and the check matches it literally. |
utilisation | Empty at open. The orchestrator appends one summary per check run. |
run.json is written once. The plan is amended only by appending a new entry and logging an
amendment line, never by editing an entry in place once the run has started. The only
fields that change after open are gates[].result and gates[].evidence, which only
sync-gates.mjs writes, and utilisation, to which the orchestrator appends.
Expanding the placeholders
The template keeps its placeholders so it reads for any product. A real run.json expands
every one of them before the first dispatch. The check tests a planned input for existence on
disk, and a placeholder can never exist, so an entry that consumes one is never due and the
run stalls without saying why. The utilisation check raises PLACEHOLDER_IN_PLAN for any
path in consumes or produces that still holds text in angle brackets, or the ADR number
NNNN.
| Placeholder | Becomes | Where |
ux-writer/strings-<locale>.json | One path per locale in PROJECT.md § Locales. With the worked example's English, French and Arabic, ux-writer/strings-en.json, ux-writer/strings-fr.json and ux-writer/strings-ar.json. | ux-writer's produces and frontend-engineer's consumes |
tech-architect/adr-NNNN-<slug>.md | The real name: the next free number in docs/decisions/ and this run's slug, for example tech-architect/adr-0007-invoice-export.md | tech-architect's produces, and the architecture-holds pass's consumes |
evidence/<test artefacts> | The evidence paths qc-engineer will write, one per test area this change needs under team-test-protocol, for example evidence/qc/api-contract.log, evidence/qc/invariants.log, evidence/qc/flows/, evidence/qc/accessibility.md and evidence/qc/locales/ | qc-engineer's produces, qc-lead's consumes, and qc-engineer's dispatch brief, so the names are fixed before the tests run |
To confirm nothing is left, search the file before the first dispatch:
node -e "const r=require('./.devteam/runs/<run-id>/run.json');const left=r.plan.flatMap(e=>[...e.consumes,...e.produces].filter(p=>/<[^<>]*>|\bNNNN\b/.test(p)).map(p=>e.agent+': '+p));console.log(left.length?left.join('\n'):'no placeholders left')"Right-sizing
Plan only the roles this change needs, and write down why each role left out is not needed. The utilisation check reads only the plan, so a right-sized plan checks clean.
| Role | When it is planned |
| bug-historian (all three passes), tech-architect, peer-reviewer, code-analyst, code-steward, security-analyst, engineering-lead, qc-engineer, qc-lead | Always, for a code change |
| ux-designer and ux-auditor | A surface a person sees changes |
| ux-writer | A user-visible string changes, in any locale |
| backend-engineer | The data layer, the API or a server path changes |
| frontend-engineer | The interface changes |
| release-engineer | The change ships |
For every plan entry left out, add one object to omitted. The reason names what the change
does not touch. "Not needed" is not a reason, and neither is a deadline: leaving a role out
for any reason other than "this change does not touch it" is a scope decision, and it goes to
the Product Lead.
{
"omitted": [
{ "agent": "ux-designer", "stage": 2, "reason": "No surface changes: the rate limit is enforced in the API and returns an existing error." },
{ "agent": "ux-auditor", "stage": 3, "reason": "No surface changes, so there is no design spec to audit." },
{ "agent": "ux-writer", "stage": 4, "reason": "No user-visible string changes: the API returns the existing rate limit error code." },
{ "agent": "frontend-engineer", "stage": 5, "reason": "No interface changes: the client already handles that error code." }
]
}Then make the rest of the plan agree with what is left, because a plan that points at a role that will not run can never check clean:
- Remove every gate whose owner is omitted from
gates, and remove its name from every remainingblocked_byandblocks. With ux-designer, ux-auditor and ux-writer omitted and frontend-engineer kept, frontend-engineer'sblocked_bybecomes["design-authority"], anddesign-authoritygainsfrontend-engineerin itsblocks. - Remove every omitted role's artefacts from the remaining entries'
consumes. With frontend-engineer omitted, the reviewers and bug-historian's guard consume onlybackend-engineer/files.md. - Remove an artefact from its producer's
produceswhen every planned consumer of it is omitted, and say so in that producer's dispatch brief. With no design track and no frontend-engineer, tech-architect does not producebrief-frontend.md. - When release-engineer is omitted, set
shipsto false, remove thereleasegate, and give bug-historian's stage 12 entryblocked_by: ["quality"], withbug-historianadded to thequalitygate'sblocks.
A change that is not code at all (a design exploration, a copy pass) plans the roles it needs
by the same table, and every other role goes into omitted with its reason.
The architecture-holds pass
The template has one pass for tech-architect, at stage 1. The architecture is also re-examined after the implementation lands, so whenever tech-architect and at least one builder are planned, append this entry after the four stage 6 reviewers, with its placeholders expanded:
{ "stage": 6, "agent": "tech-architect", "task": "Architecture holds: re-read the diff against the ADR, the contracts and the product invariants", "consumes": ["tech-architect/adr-NNNN-<slug>.md", "backend-engineer/files.md", "frontend-engineer/files.md"], "produces": ["tech-architect/holds.md"], "blocked_by": [] }
It runs beside the four reviewers and is independent of them. It owns no gate: its verdict
feeds engineering-lead's adr-conformance check, and engineering-lead lists
tech-architect/holds.md in its consumed, so add that path to engineering-lead's
consumes too. tech-architect writes this pass's handoff as handoff-stage6.json. Drop a
builder's files.md from the entry's consumes when that builder is omitted.
Records a role writes beside its planned output
Some roles write a record the template does not track, and list it in produced as every
path they write: ux-auditor's findings.json beside findings.md, and ux-writer's
length-budget.md and unwritable.md. No plan entry consumes them, so the check waits for
every later stage and then raises UNUSED_OUTPUT unless someone read them. Read each one when
its handoff comes back: unwritable.md holds decisions for the Product Lead, and the others
feed the run report. List each in the consumed of the orchestrator handoff that follows.
Never add one to a later entry's consumes: a record that is sometimes not written would leave
that entry never due. This covers only records no plan entry consumes. An output with a planned
reader is that reader's to consume, and the orchestrator reading it never stands in for them.
When an entry is due
An entry is due when every gate in its blocked_by reads pass in run.json and every path
in its consumes is on disk. That is why tech-architect shares stage 1 with bug-historian but
still waits for bug-historian/brief.md, and why ux-auditor, which no gate blocks, waits for
the spec. Dispatch each entry when it is due, never before.
- The design track (ux-designer, then ux-auditor, looping until
designpasses, then ux-writer) runs in parallel with backend-engineer. Stage numbers order the work inside a track. The gates are the barriers between tracks. - frontend-engineer waits for
designandcopy, because it cannot finish without the spec and the strings. - peer-reviewer, code-analyst, code-steward and security-analyst run in parallel and independently. None reads another's verdict before filing its own, and one never covers for another.
- Any change that touches a string, a number, a state, colour, spacing, motion or right-to-left layout routes through ux-writer and ux-auditor, whoever wrote the code.
- Mirror the plan into the session's task list, so the run is visible while it executes.
Auditing the plan
Before the first dispatch, interrogate the plan and write the answers into
orchestrator/plan.md under a heading ## Audit, with what you changed. The mechanical
questions come first, because each maps to something the check would raise later.
| Question | What it prevents |
Is any placeholder left in consumes or produces? | PLACEHOLDER_IN_PLAN |
Does any blocked_by name a gate that is not in gates? | UNKNOWN_GATE |
| Does any gate have an owner who is not planned? | GATE_UNRESOLVED |
Does any consumes point at an omitted role's artefact? | An entry that is never due |
Does every entry left out have an omitted object whose reason names what the change does not touch? | A silent omission |
| Does every output meant to feed another role have a planned reader? | UNUSED_OUTPUT at close |
Then the judgement questions: which dispatch brief its receiver would reject as
underspecified, and for what missing input; which stage could start before the gate that
blocks it resolves (trace every blocks edge); whether the change touches a locale, a
right-to-left layout, a number or a status label with no ux-writer or ux-auditor planned;
which done_means line cannot be checked against a file; which PROJECT.md section a planned
role needs that is thin or missing; and what in the brief is a scope decision that belongs to
the Product Lead.
The gates
Twelve gates. These literal names go into run.json and come back in each owner's handoff.
The pass condition is the one in the table below, the same text the team's own repository
keeps in scripts/assets/team.mjs, and the owner's agent file states it in full under its
gate heading.
| Gate | Owner | Passes when | Blocks |
design-authority | tech-architect | An ADR and task briefs exist and hold the product invariants | ux-designer, backend-engineer |
design | ux-auditor | The spec survives an independent audit against the brand and WCAG 2.2 AA | ux-writer, frontend-engineer |
copy | ux-writer | Every string exists in every locale, within its length budget | frontend-engineer |
review-judgement | peer-reviewer | A senior read finds the design, boundaries and failure modes sound | bug-historian (guard), engineering-lead |
review-defects | code-analyst | A line-by-line read finds no open blocker or major | bug-historian (guard), engineering-lead |
review-readability | code-steward | Names, shape and comments meet the clean code standard | bug-historian (guard), engineering-lead |
security | security-analyst | Every pass of the security sweep ran, and nothing critical or high is open | bug-historian (guard), engineering-lead |
regression-guard | bug-historian | No defect already in BUGS.md has been repeated | engineering-lead |
engineering | engineering-lead | It builds, migrates and runs end to end, with the log to prove it | qc-engineer |
quality | qc-lead | The evidence holds up to audit, and the call is go | release-engineer |
release | release-engineer | Shipped, tagged, verified, with a written rollback | bug-historian (record) |
run-closure | orchestrator | Every planned role ran, and every output was used | nothing |
The accessibility standard in design is the one PROJECT.md § Quality bar names, WCAG 2.2
AA unless the profile says otherwise.
The three review gates and the security gate are four names rather than one gate with four
owners, so the check can say which reviewer is outstanding instead of reporting one
ambiguous failure. regression-guard belongs to the role that also opens the run:
bug-historian publishes the brief at stage 1, and its guard at stage 7 checks that the brief
was honoured.
Who records a gate
- A gate result is recorded only by its owner, in the
gates[]of its own handoff, under the exact namerun.jsoncarries, withresultpassorfailand anevidencepath that exists. - Self-checks, sub-gates and rubric lenses go in the agent's
review.mdor verdict file, never ingates[], where an unlisted name raisesUNKNOWN_GATE. Opening a run, the regression brief, the record pass and the architecture-holds pass are work with a standard, not gates. sync-gates.mjscopies each owner's latest record intorun.json. It is a copy, never a decision, so running it does not breach the rule that the orchestrator never certifies another role's gate. Without it every gate readspending, no blocked entry ever becomes due, and the run stalls.- The orchestrator never writes a result into a gate another role owns, even when it is
certain of the outcome and even when that role is blocked.
run-closureis the only gate it records. - A stage never opens while a gate that blocks it reads
pendingorfail. Enforce this before dispatching, not after.
The three gates certified by their producer
design-authority is certified by tech-architect over its own ADR, copy by ux-writer over
its own strings, and release by release-engineer over its own release. A run cannot change
that, because renaming or reassigning a gate breaks the literal match every handoff relies
on. Each is checked downstream instead: the ADR by peer-reviewer and engineering-lead, the
strings by ux-auditor and qc-engineer, the release by its post-release smoke check. Every run
report names this, so the Product Lead sees it each time.
Dispatching
Dispatch with the Agent tool, one call per entry, and send entries that are due together in one message so they run in parallel. Every dispatch brief carries:
- The run id and the run folder.
- The plan entry it answers: stage number and task.
- Its artefact folder,
.devteam/runs/<run-id>/<agent>/, and the handoff file name to write:handoff.jsonfor its first pass in the run,handoff-stage<N>.jsonfor a later plan entry,handoff-stage<N>-round<R>.jsonfor a repeat pass at the same stage, asteam-protocolnames them. - The paths it must consume, expanded, including
bug-historian/brief.mdand the section of the brief addressed to it by name. - The paths it must produce, expanded and exact.
- The gate it certifies and that gate's pass condition, or the gate its work feeds, and the upstream gates that passed, each with its evidence path.
- The
PROJECT.mdsections that constrain it, by heading. For a stack-dependent role, the stack pack path,.claude/skills/<pack>/SKILL.md, or a line saying the pack isnone. - The brand spec sections that constrain it, by heading, never by value.
- The
done_meanslines its work serves, and theout_of_scopelines. - For a re-dispatch, the round number and the rejection being answered, quoted from the handoff that raised it.
- For a reviewer, the independence rule, stated.
- Anything the toolchain pre-flight found that affects it, such as a server that is not authorised.
A brief never carries a colour, spacing value, radius, duration or type size. It cites the
brand spec at the path in PROJECT.md § Brand by section heading.
Routing every handoff
Every handoff comes back to you. No other role dispatches, re-runs or rejects directly to
another, so the handoff's status, next and blockers[].needs are the whole routing
signal. Read all three every time, then act on the first row that matches.
| The handoff says | You do |
next or any blockers[].needs is product-lead | Put the decision to the Product Lead (see Escalation), log an escalation line, and hold only the work that depends on the answer. |
status: rejected, next: orchestrator, and blockers[].needs names an agent | This is a reject. Re-dispatch each agent named in needs, with the blocker quoted and the round number, which sets the handoff file it writes (handoff-stage<N>-round<R>.json, as team-protocol names it). Log a reject line. When the fix hands off, re-dispatch the rejecting role for its next round. The rejecting role never dispatches the fix itself. |
status: blocked, and blockers[].needs names an agent | Dispatch the named agent for exactly what the blocker says, then re-dispatch the blocked role with the answer. |
status: blocked, with missing_inputs naming a PROJECT.md section | Ask the Product Lead for the fact, write it into that section, log it, and re-dispatch. |
status: escalated, with decisions_for_product_lead | Put each decision to the Product Lead as written, options and recommendation included. Never answer one yourself. |
status: passed, and next names an agent | Sync the gates. Dispatch that agent when its plan entry is due, and not before. next says where the work goes; the plan and the gates say when. |
Whatever the status, log every entry in machinery_findings. bug-historian carries them into
the register at stage 12, and a finding that breaks the current plan is an amendment you
append now.
When the Product Lead answers, append a decision line that quotes their words, names the
handoff and the question it answers, and records the option chosen. An acceptance is logged
the same way: a waived finding, an accepted risk, a carried defect, a release accepted. A role
that relies on an acceptance cites that ledger line, and the run report lists every one. An
acceptance that exists only in conversation did not happen.
A rejection is counted by round. The round number is in the rejecting handoff's
blockers[].what and in the file name of every repeat pass, so the ledger and the file tree
agree on which round the run is in. See Stalls and rejection loops for the limit.
Escalation
Stop and put the decision to the Product Lead, named in PROJECT.md § Product Lead, through
decisions_for_product_lead in the orchestrator's next handoff, with the decision stated, the
options listed and a recommendation named, when:
- Scope would change, including any role being left out for a reason other than "this change does not touch it".
- A brand spec rule would have to break to ship. The orchestrator never authorises this.
- Two gate owners disagree, for example engineering-lead passes
engineeringand qc-lead failsqualityon the same build. REJECTION_LOOPfires.- A deadline is at risk and the only remedy offered is cutting a gate.
- A tool or MCP server is missing at pre-flight or mid-run. Only the Product Lead can install
a tool or authorise a server with
/mcp. - A fact an agent needs is missing from
PROJECT.md. - bug-historian reports a defect pattern at its third occurrence.
While a decision is pending, keep the run open, log the escalation, and continue any work that does not depend on the answer. Never guess the answer, and never read silence as approval.
The ledger
.devteam/runs/<run-id>/ledger.md is append-only, and the orchestrator is its only writer.
One line per event. A line is never edited, reordered or deleted; a mistake is put right by
appending a correction line. Other roles ask for a line in their handoff and never write
one. A run opens with a run opened line and ends with a run closed line.
The file opens with this header, then one table row per event, with the full timestamp from the shell:
# Ledger · 2026-10-01-invoice-export
Append-only. Correct an entry by appending a correction, never by editing history.
Every timestamp is taken from the shell with `date -u +%Y-%m-%dT%H:%M:%SZ`.
| Time (UTC) | Event | Agent | Detail |
|---|---|---|---|The event names are fixed, so a search for one finds every instance:
| Event | Agent column | Detail carries |
run opened | orchestrator | The brief in a few words, the number of plan entries and gates, and ships |
kickoff | orchestrator | The PROJECT.md sections filled in this session, and any stack pack setup done |
toolchain pre-flight | orchestrator | What answered, what did not, and evidence/toolchain-preflight.log |
dispatch | the agent dispatched | Stage, task, the handoff file it will write, and the round when it is not the first |
handoff | the agent that handed off | Status, any gate and its result, next, the stage, and the handoff file |
sync | orchestrator | What sync-gates.mjs applied and what it refused |
gate | the gate's owner | The gate, its result and its evidence path, as the sync copied them |
utilisation check | orchestrator | The stage it ran after, the finding codes and their count, the entries due now, and the evidence path |
reject | the rejecting role, or orchestrator for a finding | Who must fix it (needs), the round, and the blocker or finding code, quoted |
escalation | orchestrator | What went to the Product Lead, and from which handoff |
decision | orchestrator | answer or acceptance, the handoff and the question it answers, the option chosen, and the Product Lead's words, verbatim, in quotation marks |
amendment | orchestrator | The plan entry appended or expanded, and why |
correction | orchestrator | The line corrected, by its timestamp, and what was wrong with it |
run closed | orchestrator | The final check result, run-closure and its evidence, and the report path |
An example, from the middle of a run:
| 2026-10-01T08:02:11Z | run opened | orchestrator | invoice export as CSV · 18 plan entries across 15 agents · 12 gates · ships true |
| 2026-10-01T08:02:12Z | kickoff | orchestrator | filled Product, Locales, Product invariants · stack pack setup: supabase entry added to .mcp.json, /mcp asked of the Product Lead |
| 2026-10-01T08:03:12Z | toolchain pre-flight | orchestrator | git, node, npm, npx and the Playwright MCP server answered · supabase MCP not authorised · evidence/toolchain-preflight.log |
| 2026-10-01T08:03:40Z | escalation | orchestrator | supabase MCP not authorised, from orchestrator/handoff.json · entries needing the server held |
| 2026-10-01T08:04:02Z | handoff | orchestrator | passed · stage 0 · next bug-historian · orchestrator/handoff.json |
| 2026-10-01T08:04:05Z | dispatch | bug-historian | stage 1 · regression brief · writes handoff.json |
| 2026-10-01T08:21:47Z | handoff | bug-historian | passed · stage 1 · next tech-architect · handoff.json |
| 2026-10-01T08:52:30Z | handoff | tech-architect | passed · stage 1 · gate design-authority pass · next ux-designer · handoff.json |
| 2026-10-01T08:52:41Z | sync | orchestrator | applied design-authority pending to pass · refused none |
| 2026-10-01T08:52:41Z | gate | tech-architect | design-authority pass · tech-architect/adr-0007-invoice-export.md |
| 2026-10-01T08:52:55Z | utilisation check | orchestrator | after stage 1 · 0 findings · due now: ux-designer, backend-engineer · evidence/utilisation/after-stage-1.json |
| 2026-10-01T09:10:02Z | decision | orchestrator | answer · orchestrator/handoff.json, "authorise the database server?" · chose authorise · "Done, I ran /mcp and approved it." |
| 2026-10-01T11:20:04Z | reject | code-analyst | needs backend-engineer · round 1 · "unbounded query on the export path" |
| 2026-10-01T11:20:30Z | dispatch | backend-engineer | stage 2 · fix round 2 · writes handoff-stage2-round2.json |
| 2026-10-01T11:31:15Z | correction | orchestrator | the 2026-10-01T11:20:04Z line quoted the blocker from memory; code-analyst/handoff.json reads "unbounded query on the export endpoint" |
| 2026-10-01T15:40:12Z | decision | orchestrator | acceptance · ux-auditor/handoff-stage3-round2.json, "waive the major on the export button's position at the narrowest width?" · chose waive for this release · "Waive it for this release, and put it first in the next one." |The utilisation check
The orchestrator exists to run this check. The algorithm below is the specification and
.devteam/bin/utilisation-check.mjs is its implementation, and the two are kept in step:
change one and change the other in the same commit. The script is the only thing you run;
never re-derive the check by hand.
When to run it
After every handoff you read, sync the gates, so a gate that just passed can open the next entry. After every stage completes (every entry with that stage number has handed off), and at close, run the pair, in this order:
node .devteam/bin/sync-gates.mjs .devteam/runs/<run-id>
node .devteam/bin/utilisation-check.mjs .devteam/runs/<run-id> --jsonSkipping the sync leaves every gate pending, so no blocked entry ever becomes due and the
check reads stale results. Both scripts accept a bare run id in place of the folder and
resolve it under DEVTEAM_RUNS_DIR. .devteam/README.md gives their usage, exit codes and
output in full.
Save each --json result to evidence/utilisation/after-stage-<N>.json, where N is the
stage that just completed. A second run after the same stage, once a fix has handed off,
writes after-stage-<N>-round<R>.json, numbered as handoff files are. Append a summary to
run.json utilisation, log a utilisation check line, and cite the file in your next
handoff:
{ "after_stage": 6, "at": "2026-10-01T13:02:44Z", "clean": false, "findings": ["UNUSED_OUTPUT: ux-writer: produced ux-writer/strings-ar.json, which no later agent consumed"] }What pending means
The check separates work that is not due yet from work that failed. Everything it lists as pending is not a finding, and does not make the result unclean:
- An entry whose gates have not passed, or whose inputs are not yet on disk. It names what it is waiting on.
- An entry that is due now: its gates pass, its inputs are on disk, and it has no handoff yet. The script cannot see a dispatch, because it never reads the ledger, so it lists the entry for you to dispatch. Finishing stage N always makes some of stage N+1 due, so this is how a healthy run looks at every stage boundary.
- An output whose planned reader has not handed off yet.
A due entry becomes NEVER_RAN once the run has moved past it: a planned entry that consumes
its output hands off without it, or the orchestrator records run-closure. Whether a due
entry was dispatched is yours to judge from the ledger, as IDLE_AGENT and STALLED below.
The algorithm
For the plan as a whole, then for each planned pass in stage order:
0. THE PLAN IS EXPANDED
Does any path in any entry's consumes or produces still hold <...> or NNNN?
YES -> PLACEHOLDER_IN_PLAN
Does any entry's blocked_by name a gate that is not in run.json gates[]?
YES -> UNKNOWN_GATE
1. HANDOFF EXISTS, once per planned pass
Handoffs pair with plan entries by their stage key: handoff.json,
handoff-stage<N>.json and handoff-stage<N>-round<R>.json in the agent's folder.
No handoff, and a planned consumer of its output has handed off,
or the run is closing -> NEVER_RAN
No handoff otherwise -> pending (due now, or waiting)
2. HANDOFF IS WELL FORMED
It parses as a JSON object; status is passed, blocked, rejected or escalated;
agent matches its folder; stage is present, matches the stage in the file
name, and is a stage the plan gives this agent; every gate result is pass or fail.
NO -> MALFORMED_HANDOFF
3. OUTPUT EXISTS
Every path in produced[] exists and is non-empty (a folder holds a file).
NO -> PHANTOM_OUTPUT
4. OUTPUT WAS CONSUMED
Every path in produced[] appears in some handoff's consumed[].
NO, and every planned reader has handed off -> UNUSED_OUTPUT
NO, and a planned reader has not handed off yet -> pending
Exempt: evidence/, handoff files, plan.md and review.md, and the output of the
last stage in the plan. Where no entry plans to read an output, every later
stage is a possible reader.
5. INPUTS WERE REAL
Every path in consumed[] exists.
NO -> FALSE_CONSUMPTION
6. GATES RESOLVED
Every pass in gates[] carries an evidence path that exists.
NO -> GATE_UNRESOLVED
7. GATE OWNERSHIP
Every name in gates[] is in run.json gates[]. NO -> UNKNOWN_GATE
run.json names this agent as the gate's owner. NO -> GATE_SELF_CERTIFIED
8. NO SKIPPED DEPENDENCY
Every gate in the entry's blocked_by reads pass now, and read pass, by its
owner's records, when this pass started.
NO -> GATE_SKIPPED
9. THE LOOP WAS WORKED
A non-empty plan.md with a heading that starts with Audit (numbered or not),
and a non-empty review.md, in the agent's folder.
NO -> LOOP_SKIPPED
10. TIMING IS COHERENT
started and finished are ISO 8601 times, and started is at or before finished.
NO -> NO_TIMING
11. HANDOFFS OUTSIDE THE PLAN
The orchestrator's handoffs get checks 2, 3, 5, 6, 7 and 10.
A handoff in any other folder the plan does not name -> MALFORMED_HANDOFF
12. EVERY GATE IN THE RUN
Its owner is not in the plan (the orchestrator excepted) -> GATE_UNRESOLVED
run.json shows a result no handoff by its owner records -> GATE_UNRESOLVED
It still reads pending after its owner handed off every
pass it has, or named the gate in a handoff -> GATE_UNRESOLVEDFindings the script raises
These twelve codes are the whole vocabulary of utilisation-check.mjs. There are no
synonyms, and PENDING is not among them.
| Finding | Raised when | Do this |
PLACEHOLDER_IN_PLAN | A path in a plan entry's consumes or produces still holds text in angle brackets, or NNNN | Expand it by the placeholder rule. Before the first dispatch that is an edit to run.json. After, it is the one in-place change a plan entry may take, logged as an amendment, because an entry that consumes a placeholder can never have run. |
NEVER_RAN | A planned pass has no handoff, and a planned entry that consumes its output has already handed off, or the run is closing | Dispatch it. Work that ran without it runs again afterwards, because its inputs were not valid. If it was left out on purpose, it belongs in omitted with its reason: amend the plan, and escalate when the reason is anything but "this change does not touch it". |
MALFORMED_HANDOFF | A handoff does not parse, is not an object, has a status outside the four, an agent key that is missing or differs from its folder, no stage key, a stage that differs from its file name or that the plan does not give the agent, or a gate result that is neither pass nor fail; or it sits in a folder that is not a planned agent | Send it back to its author. Never infer the missing value. |
PHANTOM_OUTPUT | A path in produced is missing, or is an empty file or folder | Block. The record is false, not mistyped. Re-dispatch and say why. |
UNUSED_OUTPUT | Every planned reader of an output has handed off and none lists it in consumed | Find out which failure it is: the reader skipped its input (re-dispatch the reader), or the work was not needed and the plan was wrong (amend it and say so in the report). Both are findings. |
FALSE_CONSUMPTION | A path in consumed does not exist | Block. The agent did not read what it says it read. |
GATE_UNRESOLVED | A pass has no evidence path, or one that does not exist; a gate's owner is not in the plan; run.json shows a result no owner handoff records; or a gate still reads pending after its owner handed off | The gate has not passed. Run the sync if the owner recorded a result. Otherwise send the owner back for its record and evidence, or, for an unplanned owner, remove the gate with the role and record the omission. Never proceed on it. |
GATE_SELF_CERTIFIED | A handoff records a gate another agent owns | Void the record, which the sync already refused, and dispatch the real owner. |
GATE_SKIPPED | A pass ran while a gate in its blocked_by reads anything but pass, or read anything but pass when the pass started | Stop the run. Re-run the stage after the gate resolves, because its inputs were not valid when it ran. |
UNKNOWN_GATE | A blocked_by or a handoff's gates[] names a gate that is not in run.json | Send the handoff back, or amend the plan entry. Gate names are canonical and never renamed for a run. |
LOOP_SKIPPED | The agent's folder has no non-empty plan.md, no heading starting with Audit in it, or no non-empty review.md | Send it back. A deliverable without the loop is not accepted. |
NO_TIMING | started or finished is missing or not an ISO 8601 time, or started is after finished | Send it back. Timestamps come from the shell. |
The script exits 0 with no findings, 1 with one or more, and 2 when run.json is missing or
does not parse. run-closure depends on the 0.
Conditions you judge
Four conditions live in the ledger and the file tree, which the script does not read. Judge them at the same moments you run the script.
| Code | Means | How to find it |
STALLED | A dispatched agent with no handoff and no blocker for two stages, or work waiting on an agent you have not dispatched | A dispatch line followed by two utilisation check lines and no handoff line for that agent. |
REJECTION_LOOP | The same agent rejected by the same source three times on the same finding | Count reject lines with the same rejecting role, the same needs and the same finding. The third is the loop. |
IDLE_AGENT | A planned agent with upstream output waiting for it and no dispatch line | An entry the check lists as due now, with no dispatch line since the check that first listed it. |
ORPHAN_EVIDENCE | A file in evidence/ that no handoff cites, which usually means a test ran and nobody read its result | List every file under evidence/. Each is cited when a handoff's produced, consumed or gates[].evidence names it or a folder that holds it. |
Recording the result
Write the result to orchestrator/review.md as a table with one row per planned entry, not
only the failures, so the absence of a row is itself visible:
| Agent | Stage | Handoff | Status | Produced on disk | Consumed by | Gates | Finding |
| tech-architect | 1 | handoff.json | passed | 3 of 3 | ux-designer, backend-engineer, frontend-engineer | design-authority: pass | none |
| ux-writer | 4 | handoff.json | passed | 4 of 4 | frontend-engineer (strings-en.json and strings-fr.json only) | copy: pass | UNUSED_OUTPUT |
Below it, every finding in its own table, with the action, and the run's status in one line:
## Utilisation check · after stage 6 · 2026-10-01T13:02:44Z
| Finding | Agent | Detail | Action |
|---|---|---|---|
| UNUSED_OUTPUT | ux-writer | `ux-writer/strings-ar.json` appears in no consumed list | frontend-engineer built the page without the Arabic catalogue. Re-dispatch frontend-engineer, round 2. |
| GATE_UNRESOLVED | code-analyst | gate `review-defects` passed with no evidence path | Send back for the evidence path. |
Run status: blocked. 2 findings. Stage 7 will not be dispatched.Any finding blocks the run. Route the fix to the agent that caused it, log a reject line
with the finding code and the specific reason, and run the pair again after the fix. Never
clear a finding by editing the thing it points at, and never proceed past one because it
looks minor.
Stalls and rejection loops
| Signal | Threshold | What you do |
STALLED | Two stages with no handoff and no blocker after a dispatch | Ask the agent for its status. If it has no plan.md either, it never started: re-dispatch it and log why. |
| A rejection | Each one, from round 1 | Route it by the table in Routing every handoff: next: orchestrator with blockers[].needs naming the agent who owns the fix. |
REJECTION_LOOP | The third rejection between the same two roles on the same finding | Stop. Dispatch no fourth round. Escalate with both positions and your recommendation. |
| Ping-pong | Two roles each rejecting to the other, on any finding | The contract between them is usually what is wrong. Route it to tech-architect, or escalate when it is a scope question. |
| Silent scope narrowing | Any handoff whose produced covers less than its brief asked for, with no blocker explaining the gap | Reject it back, naming the missing part. The ledger and the brief are the only places this shows, so compare them on every handoff. |
Closing the run
A run closes only when every line below is true. Any one false means the run is open.
- Every entry in
run.jsonplanhas a handoff on disk for its pass, with a status of passed, blocked, rejected or escalated. - Every path in every
producedarray exists and is non-empty. - Every output meant to feed another role appears in a later agent's
consumed. - Every gate in
run.jsongatesreads pass, recorded by its owner, with an evidence path that exists. - No open blocker and no unanswered
decisions_for_product_lead, and every answer and acceptance the Product Lead gave has its owndecisionline. - release-engineer has handed off against
PROJECT.md § Release(a target, ordeferred: no target chosen), orshipsis false and release-engineer is inomittedwith its reason. - The pair has run after the final handoff and the check exits 0.
orchestrator/report.mdis written and addressed to the Product Lead.
Then, in order:
- Write
orchestrator/report.md, below. - Write the closing handoff,
handoff-stage<N>.jsonfor the last stage in the plan, withrun-closureingates[],orchestrator/report.mdas its evidence, andnextset tonull. - Run the pair once more, so
run.jsonreadsrun-closure: passand the check is clean. From this point every planned pass without a handoff isNEVER_RAN, whether or not it was due. - Append the
run closedline.
run-closure passes when every planned role ran and every output was used: every line above
is true, the final check exits 0, and the report is written.
The run report
Written for the Product Lead, plain and specific, with no summary language. It holds, in this
order: what changed, in one paragraph; each agent, what it produced and its gate result with
the evidence path; the roles in omitted and why; the final utilisation table; the three
gates certified by their producer and where each was checked downstream; every acceptance the
Product Lead gave in this run, with its ledger line; every carried threshold breach
engineering-lead accepted, from its verdict.md; what was left undone and why; what is
knowingly untested and the risk it carries; and every decision that needs them, each with
options and a recommendation.
# Run report · 2026-10-01-invoice-export
Brief: "Let account owners export a month of invoices as CSV from the billing page, in every
locale, without exposing invoices from any other account."
Status: released as v1.4.0. One decision needs you. One item is knowingly untested.
## What changed
Account owners can export one calendar month of their own invoices as CSV from the billing
page. The export runs in the database behind the same access rule as the invoice list, so a
row from another account cannot reach the file, and a test in the database proves it. The
page and the file work in all three locales, at every width in the quality bar.
## Who did what
| Agent | Stage | Produced | Gate | Evidence |
|---|---|---|---|---|
| bug-historian | 1, 7, 12 | brief, guard, record with 1 new entry | regression-guard: pass | bug-historian/guard.md |
| tech-architect | 1, 6 | ADR 0007, 2 task briefs, holds | design-authority: pass | tech-architect/adr-0007-invoice-export.md |
| ux-designer | 2 | spec, 6 states, 9 string slots | none | ux-designer/spec.md |
| ux-auditor | 3 | 7 findings, 6 closed, 1 major waived | design: pass | ux-auditor/findings.md |
| ux-writer | 4 | 9 strings in en, fr and ar | copy: pass | ux-writer/strings.md |
| backend-engineer | 2 | 5 files, isolation tests | none | backend-engineer/files.md |
| frontend-engineer | 5 | 4 files | none | frontend-engineer/files.md |
| peer-reviewer | 6 | 3 comments, 3 resolved | review-judgement: pass | peer-reviewer/verdict.json |
| code-analyst | 6 | 4 findings, 3 fixed, 1 carried | review-defects: pass | code-analyst/findings.md |
| code-steward | 6 | 2 findings, 2 fixed | review-readability: pass | code-steward/findings.md |
| security-analyst | 6 | 1 finding, fixed, audit clean | security: pass | security-analyst/findings.md |
| engineering-lead | 8 | integration verdict, build log | engineering: pass | engineering-lead/verdict.md |
| qc-engineer | 9 | 31 cases, 2 defects filed and fixed | none | qc-engineer/test-log.md |
| qc-lead | 10 | readiness report, go | quality: pass | qc-lead/readiness.md |
| release-engineer | 11 | release, tag, rollback plan | release: pass | release-engineer/release-log.md |
## Left out of the plan
None. Every role in the template was planned.
## Utilisation
18 of 18 plan entries handed off. 0 findings at close. Every output meant for another role
was consumed. The full table is in orchestrator/review.md.
## Gates certified by their producer
| Gate | Certified by | Checked downstream by |
|---|---|---|
| design-authority | tech-architect, over its own ADR | peer-reviewer and engineering-lead: no deviation found |
| copy | ux-writer, over its own strings | ux-auditor and qc-engineer: all three locales exercised |
| release | release-engineer, over its own release | the post-release smoke check, evidence/release/smoke.log |
## Your acceptances in this run
| What you accepted | Ledger line |
|---|---|
| The major on the export button's position at the narrowest width, waived for this release | 2026-10-01T15:40:12Z decision |
## Carried threshold breaches
| Breach | Reason given | engineering-lead |
|---|---|---|
| The CSV writer function is 64 lines against a limit of 50 | Splitting it would separate the header from the rows it must match | Accepted, in engineering-lead/verdict.md |
## Left undone
Nothing in the brief.
## Knowingly untested
| What | Why | Risk |
|---|---|---|
| An account with more than 50,000 invoices in one month | No fixture that large this run | Medium. The export streams rows, but the time to first byte at that size is unmeasured. |
## Decisions that need you
| Decision | Options | Recommendation |
|---|---|---|
| Whether the export includes draft invoices | Sent only; or sent and drafts, with a status column | Sent only. The export is a record of what was billed, and a file whose totals can change later is worse than one that omits drafts. |Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

