agentleFS
ShehabovShehabov/ai-dev-crew/.claude/skills/team-orchestration/SKILL.md

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

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
  1. Very specific:

    Every stack, product and locale fact an agent needs comes from PROJECT.md, by section heading.

    line 62
  2. Distinctive:

    Ask about one section at a time.

    line 70
  3. Very specific:

    Write the answer into that section in place of the marker, then read it back.

    line 82
  4. Very specific:

    When a pack is named, run the setup section of its SKILL.md.

    line 91
  5. Distinctive:

    Ask before installing anything a setup section lists.

    line 98
  6. Very specific:

    Search for TODO: once more.

    line 99
  7. Very specific:

    When the session cannot put questions to the Product Lead (a headless run, for example), stop before opening the run and list the sections …

    line 102
  8. Very specific:

    Run it after the run opened line and before the first dispatch.

    line 108
  9. Very specific:

    Write every check to evidence/toolchain-preflight.log, one line each, with the shell timestamp, the command or call, and the answer or the …

    line 125
  10. Very specific:

    Read the brief. brief in run.json is the Product Lead's words, verbatim.

    line 163
  11. Very specific:

    Read PROJECT.md in full, at the moment you plan.

    line 164
  12. Very specific:

    Read BUGS.md: the standing rules that bind the orchestrator, and the entries on the surfaces the brief names.

    line 165
  13. Very specific:

    Read the gate table below, so the names you write into run.json are the names the owners write back.

    line 167
  14. Very specific:

    Remove every gate whose owner is omitted from gates, and remove its name from every remaining blocked_by and blocks.

    line 311
  15. Very specific:

    Remove every omitted role's artefacts from the remaining entries' consumes.

    line 315
  16. Very specific:

    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.

    line 318
  17. Very specific:

    When release-engineer is omitted, set ships to false, remove the release gate, and give bug-historian's stage 12 entry blocked_by: …

    line 321
  18. Very specific:

    Never add one to a later entry's consumes: a record that is sometimes not written would leave that entry never due.

    line 351
  19. Very specific:

    Before the first dispatch, interrogate the plan and write the answers into orchestrator/plan.md under a heading ## Audit, with what you …

    line 376
  20. Very specific:

    Every handoff comes back to you.

    line 493
  21. Very specific:

    When the Product Lead answers, append a decision line that quotes their words, names the handoff and the question it answers, and records …

    line 510
  22. Very specific:

    Stop and put the decision to the Product Lead, named in PROJECT.md § Product Lead, through decisions_for_product_lead in the orchestrator's …

    line 524
  23. Distinctive:

    After every handoff you read, sync the gates, so a gate that just passed can open the next entry.

    line 616
  24. Very specific:

    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 …

    line 767
  25. Very specific:

    Every entry in run.json plan has a handoff on disk for its pass, with a status of passed, blocked, rejected or escalated.

    line 811
  26. Very specific:

    Every path in every produced array exists and is non-empty.

    line 813
  27. Very specific:

    Every output meant to feed another role appears in a later agent's consumed.

    line 814
  28. Very specific:

    Every gate in run.json gates reads pass, recorded by its owner, with an evidence path that exists.

    line 815
  29. Very specific:

    No open blocker and no unanswered decisions_for_product_lead, and every answer and acceptance the Product Lead gave has its own decision …

    line 817
  30. Very specific:

    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 …

    line 828
  31. Very specific:

    Run the pair once more, so run.json reads run-closure: pass and the check is clean.

    line 831

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

#StepLedger line
1Kickoff, only while PROJECT.md carries a TODO: outside its worked example. No run folder exists yet.Written at step 2
2Create the run folder and ledger.mdrun opened, then kickoff naming the sections filled in this session, when there were any
3The toolchain pre-flight, written to evidence/toolchain-preflight.logtoolchain pre-flight
4Write run.json from the template, right-sized, and orchestrator/plan.md with its ## AuditCited in the step 5 line
5Write orchestrator/handoff.json with stage 0 and next set to bug-historianhandoff
6Dispatch bug-historian, before any other agent plansdispatch

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.

  1. 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.
  2. 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 chosen in Release, no attribution in House rules, BRAND.md in Brand), offer it and ask the Product Lead to confirm or change it. In Toolchain, say that the root .mcp.json declares 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.json and playwright from enabledMcpjsonServers in .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 .gitignore included: scripts/check.mjs reads 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.
  3. 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. none is a valid answer in Commands and Stack pack. A section is never filled with a guess.
  4. 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.
  5. For Stack pack, list the stack-* folders under .claude/skills/ and suggest the one that matches the Stack section, or none. Where a pack is chosen, offer its command set as the default for Commands.
  6. When a pack is named, run the setup section of its SKILL.md. For stack-nextjs-supabase that is its Kickoff setup: add the supabase entry from .claude/skills/stack-nextjs-supabase/templates/mcp.json to the root .mcp.json, beside the team's playwright entry, 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.
  7. 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.

CheckCommand or callSource
gitgit --versionThe core. Always checked.
nodenode --versionThe core. Always checked.
Every tool PROJECT.md § Toolchain lists as presentIts version commandThe project profile
The Playwright MCP server, when PROJECT.md § Toolchain lists itclaude 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 answerThe team's .mcp.json
Whatever the stack pack's pre-flight asks forAs its SKILL.md statesThe 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
ResultDo this
Everything answersDispatch as planned.
git or node is missingStop and escalate. No stage can run.
A tool the Toolchain section lists is missingEscalate, and plan no stage that needs it until a re-run of the check answers.
A check the stack pack lists failsDo 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. brief in run.json is the Product Lead's words, verbatim.
  • Read PROJECT.md in 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.json are the names the owners write back.
  • Find prior runs on the same surface by searching .devteam/runs/*/run.json for the surface name, and read the orchestrator/report.md of any that match. Runs are gitignored, so a fresh clone may have none, and BUGS.md is 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

FieldRule
runThe run id. Every agent in the run uses the same one.
briefThe Product Lead's words, verbatim.
openedFrom the shell.
shipstrue when release-engineer is planned, false when it is in omitted.
done_meansEvery line checkable against a file, a log or a screenshot. Rewrite a line until it is.
out_of_scopeNamed so no role reads a gap as an oversight.
planOne 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, producesPaths 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_byGate names, never agent names. Every name is in gates, and that gate's blocks lists this agent.
omittedOne object per plan entry left out, with its reason. See Right-sizing.
gatesThe 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.
utilisationEmpty 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.

PlaceholderBecomesWhere
ux-writer/strings-<locale>.jsonOne 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>.mdThe real name: the next free number in docs/decisions/ and this run's slug, for example tech-architect/adr-0007-invoice-export.mdtech-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.

RoleWhen it is planned
bug-historian (all three passes), tech-architect, peer-reviewer, code-analyst, code-steward, security-analyst, engineering-lead, qc-engineer, qc-leadAlways, for a code change
ux-designer and ux-auditorA surface a person sees changes
ux-writerA user-visible string changes, in any locale
backend-engineerThe data layer, the API or a server path changes
frontend-engineerThe interface changes
release-engineerThe 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 remaining blocked_by and blocks. With ux-designer, ux-auditor and ux-writer omitted and frontend-engineer kept, frontend-engineer's blocked_by becomes ["design-authority"], and design-authority gains frontend-engineer in its blocks.
  • Remove every omitted role's artefacts from the remaining entries' consumes. With frontend-engineer omitted, the reviewers and bug-historian's guard consume only backend-engineer/files.md.
  • 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. With no design track and no frontend-engineer, tech-architect does not produce brief-frontend.md.
  • When release-engineer is omitted, set ships to false, remove the release gate, and give bug-historian's stage 12 entry blocked_by: ["quality"], with bug-historian added to the quality gate's blocks.

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 design passes, 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 design and copy, 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.

QuestionWhat 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.

GateOwnerPasses whenBlocks
design-authoritytech-architectAn ADR and task briefs exist and hold the product invariantsux-designer, backend-engineer
designux-auditorThe spec survives an independent audit against the brand and WCAG 2.2 AAux-writer, frontend-engineer
copyux-writerEvery string exists in every locale, within its length budgetfrontend-engineer
review-judgementpeer-reviewerA senior read finds the design, boundaries and failure modes soundbug-historian (guard), engineering-lead
review-defectscode-analystA line-by-line read finds no open blocker or majorbug-historian (guard), engineering-lead
review-readabilitycode-stewardNames, shape and comments meet the clean code standardbug-historian (guard), engineering-lead
securitysecurity-analystEvery pass of the security sweep ran, and nothing critical or high is openbug-historian (guard), engineering-lead
regression-guardbug-historianNo defect already in BUGS.md has been repeatedengineering-lead
engineeringengineering-leadIt builds, migrates and runs end to end, with the log to prove itqc-engineer
qualityqc-leadThe evidence holds up to audit, and the call is gorelease-engineer
releaserelease-engineerShipped, tagged, verified, with a written rollbackbug-historian (record)
run-closureorchestratorEvery planned role ran, and every output was usednothing

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 name run.json carries, with result pass or fail and an evidence path that exists.
  • Self-checks, sub-gates and rubric lenses go in the agent's review.md or verdict file, never in gates[], where an unlisted name raises UNKNOWN_GATE. Opening a run, the regression brief, the record pass and the architecture-holds pass are work with a standard, not gates.
  • sync-gates.mjs copies each owner's latest record into run.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 reads pending, 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-closure is the only gate it records.
  • A stage never opens while a gate that blocks it reads pending or fail. 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:

  1. The run id and the run folder.
  2. The plan entry it answers: stage number and task.
  3. Its artefact folder, .devteam/runs/<run-id>/<agent>/, and the handoff file name to write: handoff.json for its first pass in the run, handoff-stage<N>.json for a later plan entry, handoff-stage<N>-round<R>.json for a repeat pass at the same stage, as team-protocol names them.
  4. The paths it must consume, expanded, including bug-historian/brief.md and the section of the brief addressed to it by name.
  5. The paths it must produce, expanded and exact.
  6. 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.
  7. The PROJECT.md sections 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 is none.
  8. The brand spec sections that constrain it, by heading, never by value.
  9. The done_means lines its work serves, and the out_of_scope lines.
  10. For a re-dispatch, the round number and the rejection being answered, quoted from the handoff that raised it.
  11. For a reviewer, the independence rule, stated.
  12. 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 saysYou do
next or any blockers[].needs is product-leadPut 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 agentThis 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 agentDispatch 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 sectionAsk the Product Lead for the fact, write it into that section, log it, and re-dispatch.
status: escalated, with decisions_for_product_leadPut each decision to the Product Lead as written, options and recommendation included. Never answer one yourself.
status: passed, and next names an agentSync 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 engineering and qc-lead fails quality on the same build.
  • REJECTION_LOOP fires.
  • 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:

EventAgent columnDetail carries
run openedorchestratorThe brief in a few words, the number of plan entries and gates, and ships
kickofforchestratorThe PROJECT.md sections filled in this session, and any stack pack setup done
toolchain pre-flightorchestratorWhat answered, what did not, and evidence/toolchain-preflight.log
dispatchthe agent dispatchedStage, task, the handoff file it will write, and the round when it is not the first
handoffthe agent that handed offStatus, any gate and its result, next, the stage, and the handoff file
syncorchestratorWhat sync-gates.mjs applied and what it refused
gatethe gate's ownerThe gate, its result and its evidence path, as the sync copied them
utilisation checkorchestratorThe stage it ran after, the finding codes and their count, the entries due now, and the evidence path
rejectthe rejecting role, or orchestrator for a findingWho must fix it (needs), the round, and the blocker or finding code, quoted
escalationorchestratorWhat went to the Product Lead, and from which handoff
decisionorchestratoranswer or acceptance, the handoff and the question it answers, the option chosen, and the Product Lead's words, verbatim, in quotation marks
amendmentorchestratorThe plan entry appended or expanded, and why
correctionorchestratorThe line corrected, by its timestamp, and what was wrong with it
run closedorchestratorThe 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> --json

Skipping 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_UNRESOLVED

Findings the script raises

These twelve codes are the whole vocabulary of utilisation-check.mjs. There are no synonyms, and PENDING is not among them.

FindingRaised whenDo this
PLACEHOLDER_IN_PLANA path in a plan entry's consumes or produces still holds text in angle brackets, or NNNNExpand 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_RANA planned pass has no handoff, and a planned entry that consumes its output has already handed off, or the run is closingDispatch 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_HANDOFFA 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 agentSend it back to its author. Never infer the missing value.
PHANTOM_OUTPUTA path in produced is missing, or is an empty file or folderBlock. The record is false, not mistyped. Re-dispatch and say why.
UNUSED_OUTPUTEvery planned reader of an output has handed off and none lists it in consumedFind 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_CONSUMPTIONA path in consumed does not existBlock. The agent did not read what it says it read.
GATE_UNRESOLVEDA 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 offThe 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_CERTIFIEDA handoff records a gate another agent ownsVoid the record, which the sync already refused, and dispatch the real owner.
GATE_SKIPPEDA pass ran while a gate in its blocked_by reads anything but pass, or read anything but pass when the pass startedStop the run. Re-run the stage after the gate resolves, because its inputs were not valid when it ran.
UNKNOWN_GATEA blocked_by or a handoff's gates[] names a gate that is not in run.jsonSend the handoff back, or amend the plan entry. Gate names are canonical and never renamed for a run.
LOOP_SKIPPEDThe agent's folder has no non-empty plan.md, no heading starting with Audit in it, or no non-empty review.mdSend it back. A deliverable without the loop is not accepted.
NO_TIMINGstarted or finished is missing or not an ISO 8601 time, or started is after finishedSend 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.

CodeMeansHow to find it
STALLEDA dispatched agent with no handoff and no blocker for two stages, or work waiting on an agent you have not dispatchedA dispatch line followed by two utilisation check lines and no handoff line for that agent.
REJECTION_LOOPThe same agent rejected by the same source three times on the same findingCount reject lines with the same rejecting role, the same needs and the same finding. The third is the loop.
IDLE_AGENTA planned agent with upstream output waiting for it and no dispatch lineAn entry the check lists as due now, with no dispatch line since the check that first listed it.
ORPHAN_EVIDENCEA file in evidence/ that no handoff cites, which usually means a test ran and nobody read its resultList 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:

AgentStageHandoffStatusProduced on diskConsumed byGatesFinding
tech-architect1handoff.jsonpassed3 of 3ux-designer, backend-engineer, frontend-engineerdesign-authority: passnone
ux-writer4handoff.jsonpassed4 of 4frontend-engineer (strings-en.json and strings-fr.json only)copy: passUNUSED_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

SignalThresholdWhat you do
STALLEDTwo stages with no handoff and no blocker after a dispatchAsk the agent for its status. If it has no plan.md either, it never started: re-dispatch it and log why.
A rejectionEach one, from round 1Route it by the table in Routing every handoff: next: orchestrator with blockers[].needs naming the agent who owns the fix.
REJECTION_LOOPThe third rejection between the same two roles on the same findingStop. Dispatch no fourth round. Escalate with both positions and your recommendation.
Ping-pongTwo roles each rejecting to the other, on any findingThe contract between them is usually what is wrong. Route it to tech-architect, or escalate when it is a scope question.
Silent scope narrowingAny handoff whose produced covers less than its brief asked for, with no blocker explaining the gapReject 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.json plan has a handoff on disk for its pass, with a status of passed, blocked, rejected or escalated.
  • Every path in every produced array exists and is non-empty.
  • Every output meant to feed another role appears in a later agent's consumed.
  • Every gate in run.json gates reads 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 own decision line.
  • release-engineer has handed off against PROJECT.md § Release (a target, or deferred: no target chosen), or ships is false and release-engineer is in omitted with its reason.
  • The pair has run after the final handoff and the check exits 0.
  • orchestrator/report.md is written and addressed to the Product Lead.

Then, in order:

  1. Write orchestrator/report.md, below.
  2. 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 evidence, and next set to null.
  3. Run the pair once more, so run.json reads run-closure: pass and the check is clean. From this point every planned pass without a handoff is NEVER_RAN, whether or not it was due.
  4. Append the run closed line.

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. |

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.