references/orchestration.md
A supporting file of the ultra11y skill.
Orchestration — fanning the judgment phases out
The two judgment phases are per-item worklists: ADJUDICATE.todo.json holds one entry per
residual criterion, VERIFY.todo.json one per detected non-conformity. Neither has
cross-item dependencies, so both fan out cleanly across subagents — and both work exactly as
well done sequentially. This is a wall-clock optimization, never a correctness requirement.
An adjudicating subagent needs both files: ADJUDICATE.todo.json for the evidence and the
slots its verdict goes into, and adjudicate/<criteriaId>.md for the criterion itself — its
official wording, its numbered tests and, under a country standard, that standard's own test
methodology. The JSON carries none of the normative text, and the emitted contracts say so.
orchestrate emits the orchestration from the worklists that CURRENTLY exist, with absolute
paths and the real item ids baked in:
node scripts/ultra11y.mjs orchestrate --run <dir> [--phase adjudicate|verify-report] [--eco] [--list]Route by harness
| Your harness | How to run each judgment phase |
|---|---|
| Has the Workflow tool | orchestrate --run <RUN> --phase <p>, then run <RUN>/orchestration/<p>.workflow.mjs. Subagents RETURN verdict fragments; you fold them into the worklist, then verify --apply as usual. |
| Subagents but no Workflow tool | Same orchestrate; dispatch one subagent per batch following <RUN>/orchestration/agents/<role>.md (the workflow script lists the batches and their prompts). One writer: you fold the results in. |
| Eco mode, or no subagents | orchestrate --run <RUN> --eco → follow <RUN>/orchestration/RUNBOOK.md sequentially, playing each role yourself. Correctness-identical; only wall-clock differs. |
The other dispatch: the review
The judgment phases are not the only thing that leaves this skill. Once the audit has
produced fixes, the review-a11y skill reviews the code under change — dispatched the
same way, and read from the same table:
| Your harness | How to run the review |
|---|---|
| Subagents (Workflow tool or not) | One subagent, one prompt: use the review-a11y skill on the change, return its report verbatim. |
| No subagents | Invoke review-a11y directly, in this session. |
It differs from a judgment batch in one way that matters: the review is not a worklist.
Nothing is folded back, no gate re-reads it, and it writes nothing — so the one-writer rule
below is satisfied trivially, and there is no --apply step to keep. What comes back is a
report for a human.
The rules that do not bend
- Subagents never write. Every emitted contract ends with the one-writer rule, and the
fail-closed
--applyfold always stays with you, the orchestrator. Parallel writers to one worklist is how a verdict silently disappears. - The gates are harness-independent.
checkandverify --applybehave identically whether one agent or twelve produced the verdicts, so a fan-out can never buy a greener result than the sequential path. - Re-run
orchestratewhenever a worklist changes. Emission is deterministic and idempotent, so re-running is free and keeps the batches aligned with reality. --phase <p>before its worklist exists fails, and names the command that produces it.
Splitting the work sensibly
An adjudication batch should hold criteria that share context — the media criteria together, the form criteria together — so each subagent reads one part of the codebase rather than all of it. The emitted contracts already group this way; if you dispatch by hand, keep it.
A subagent adjudicating a criterion needs the same three things you do: the harvested
evidence, the decision rule (references/adjudication.md), and the reminder that a
non-conformity must cite a normative test that resolves. Point each contract at the relevant
knowledge reference rather than restating it — a paraphrase drifts.