Field-proven architectures for AI-agent development — each one a design write-up plus working scaffolding, E2E-tested before it ships. Humans decide at two gates; the agents do the rest.
Every model/effort claim carries a source label and an expiry date
Role boundaries enforced by config, not prose
Deterministic, zero-token E2E gates every scaffold change
3
patterns in the catalog
v0.16.2
on npm · MIT
0
tokens spent in the E2E gate
2
human gates per phase: sign-off & smoke test
Patterns
Choose by runtime and assurance boundary. The two three-agent entries preserve the same independent-review topology on different runtimes; hub-and-spoke trades that independence for parallel throughput. Commands and guarantees do not carry across — adopt installs exactly one pattern.
These are not versions of each other. Commands, artifacts and guarantees do not carry across — adopt installs exactly one pattern.
Three-Agent Architect–Builder–Reviewer
trialed · as of 2026-08-04 (every role cut one effort level — Architect high, Builder medium, Reviewer high, Triage high; §7)
One ticket flows through three agents in sequence: Architect plans → Builder implements → Reviewer (fresh context, different model tier) clears or bounces. No agent judges its own work.
Commands
/breakdown-prd[prd-path] [focus notes, e.g. module-count hint or what to defer]
Decompose a PRD into sub-PRDs + template-compliant tickets (three-agent pattern, pre-Gate-1 planning); appends a new phase to an existing PRD tree without touching delivered work
/build-ticket<ticket-id>
Run the Builder stage on a planned ticket (three-agent pattern)
/deliver-ticket<ticket-id> [supervised]
Deliver one reviewed-CLEAR ticket by hand, after a /review-ticket CLEAR — the manual path the stage commands stop short of
/nightly-issues[max-issues]
Nightly issue sweep — triage open issues, auto-fix the fixable ones through the three-agent pipeline, post the morning report (designed for headless `claude -p "/nightly-issues"`)
/plan-ticket<ticket-id or path to ticket file>
Run the Architect stage on a ticket (three-agent pattern)
/publish-tickets<module dir, e.g. docs/prd/01-foo> [--all]
Publish a module's tickets as tracker issues (and Asana subtasks if connected), then STOP — no pipeline run
/review-ticket<ticket-id> [branch-or-PR-ref]
Run the Reviewer stage on a built ticket (three-agent pattern) — requires a fresh context
npx agent-templates@latest adopt three-agent-architect-builder-reviewer . — scaffold, templates, docs skeleton, CLAUDE.md, in one idempotent command.
2. Break down
/breakdown-prd — the Architect turns your PRD into sub-PRDs and cold-startable tickets, then stops.
3. Gate 1 — you decide
Review the breakdown, then /start-milestone: tickets become tracker issues and the pipeline starts.
4. Autonomous middle
Plan → build → fresh-context review (bounce-capped in code) → merge on CLEAR → issue closed → delivery verified.
5. Gate 2 — smoke test
Agents own unit/integration/E2E all along; you test once per phase, when that PRD is done. A nightly sweep fixes issues while you sleep.
Parallel delivery — opt in with one number
concurrency — one number decides the shape. 1 (default) is the original sequential runner, one ticket at a time, unchanged. N (autonomous only) runs independent tickets — the ones the dependency DAG says don't block each other — as parallel lanes, scheduled by the deterministic workflow. /start-milestone docs/prd/01-foundation autonomous 4/start-all autonomous 4
Isolated worktrees
Each independent ticket runs in its own git worktree — builder and reviewer work there, so concurrent lanes never clash on the working tree.
Serialized merge
Delivery to the default branch never overlaps; a hidden file-scope overlap surfaces as a merge conflict → abort → escalate, so nothing lands broken.
DAG-bounded, opt-in
A failed ticket skips its dependents; real parallelism is bounded by the dependency graph and the runtime's agent cap. >1 multiplies token spend — opt in per run.
See the plan before you run it
/breakdown-prd writes docs/prd/dag.html — every ticket in one dependency graph, colored by module. A self-contained file: double-click it, no server, no build step. It tells you the concurrency worth passing instead of making you guess, and flags a module that can only ever use one lane — that is a file-scope decomposition problem, and Gate 1 is the cheapest moment to fix it.
15 tickets, 4 modules — pick a lane count and watch the same graph re-shape. This board is computed at build time by the pipeline's own scheduler, so it is the schedule you would actually get.
wave 1 · 5/6010101-core010201-core030103-jobs040104-docs040204-docsidle lane
wave 2 · 3/6010301-core010401-core030203-jobsidle laneidle laneidle lane
wave 3 · 2/6010501-core030303-jobsidle laneidle laneidle laneidle lane
wave 4 · 4/6020102-api020202-api020302-api020402-apiidle laneidle lane
wave 5 · 1/6020502-apiidle laneidle laneidle laneidle laneidle lane
1 lane — the shape of the DAG
Every ticket waits for the one before it, so the board is a single column per wave and the run is as long as the ticket count. Useful as the baseline: it is what concurrency defaults to.
More lanes — until they stop filling
Independent tickets pack into the same wave and the run gets shorter — up to a point. Past the widest wave the extra lanes render as idle, which is exactly the number the page tells you not to exceed.
Where you are, mid-run
/start-all reloads the DAG every few finished tickets, so a ticket added while it runs is published, scheduled, and re-rendered into the same page. Re-open it during a run — or regenerate any time with node .claude/scripts/dag-report.mjs docs/prd.
The project doesn't end at Gate 2
The PRD document splits by phase. The ticket tree never does. Write the next phase as its own PRD and point /breakdown-prd at it — it decomposes into the same docs/prd/, because /start-all schedules one global DAG and a dependency that crosses phases only resolves inside it. Then run the same command again: everything already delivered has a closed issue and filters itself out.
Three commands, no migration:
docs/PRD-02-billing.md # write the next phase
/breakdown-prd docs/PRD-02-billing.md # appends modules; delivered work is frozen
/start-all autonomous 2 # only the new tickets run
One tree, two phases — toggle to see what the second run actually schedules. Both boards are computed at build time by the pipeline's own scheduler. Watch BIL-1: it is blocked_by a phase-1 ticket that already shipped — the edge every argument for splitting the tree would break.
wave 1 · 1/2BIL-1← 0201 · phase 103-billingidle lane
wave 2 · 2/2BIL-203-billingBIL-303-billing
wave 3 · 1/2BIL-403-billingidle lane
One tree, one DAG
A parallel docs/prd2/ would make every cross-phase dependency a dangling reference — a hard error by design. Keeping one root is what lets new work depend on shipped work.
Delivered work is frozen
Existing files under docs/prd/ may only be added to — never modified or deleted — and that is checked against git, not asked for politely. A shipped ticket is the record of what was built.
Nothing is skipped silently
The run reports every ticket it dropped as already delivered. Edit a ticket after it shipped and it comes back as drift for a human to judge — the scheduler never re-runs it, and never hides it either.
Finish first, publish later
The tracker is not on the critical path unless you put it there. Pass none and every ticket merges to your local default branch — no push, no PR/MR, no tracker.
/start-all autonomous 1 none
Every delivery defect this catalog has recorded lives at the forge boundary — a pipeline gate, a protected branch, a 403 MR API, squash-merge ancestry, an expired token — and each one stopped a whole run. Review is unchanged: a ticket still only merges on CLEAR. What is deferred is publication, not judgement.
A committed ledger, not a scratch file
docs/delivered.json records each delivered ticket and the commit it landed as. That is the resume signal — a re-run executes only the new work — and what you or an agent read afterwards to know what still needs pushing. A gitignored file would vanish on the first clean checkout, exactly when it is needed.
It hands the work over
The run ends by stating that nothing was pushed and giving the exact command — git push origin main. A mode that quietly accumulates work on one machine and says nothing is indistinguishable from work nobody can see.
Same filter, different signal
With no tracker there is no closed issue to resume from, so the ledger carries that role — at launch and at every mid-run rescan. One rule, two sources; a delivered ticket is never re-planned and re-built against work it already contains.
Codex Three-Agent Architect–Builder–Reviewer
proposed · as of 2026-08-11
A Codex-native port of the catalog's three-agent assurance topology: a planning Architect hands a cold-startable artifact to a Builder, and a fresh-context read-only Reviewer clears or bounces the diff. Repository skills replace Claude slash commands; project custom-agent TOML replaces Claude agent frontmatter; deterministic Node scripts retain the ticket, DAG, tracker, and delivery gates.
Commands
$breakdown-prd
Decompose a PRD into Codex three-agent sub-PRDs and tickets, enforce append-only phases, and render the global DAG. Use before Gate 1.
$build-ticket
Run the Codex three-agent Builder stage for one already-planned ticket. Use when asked to implement a ticket through the Builder only.
$plan-ticket
Run the Codex three-agent Architect stage for one ticket. Use when asked to plan a ticket without implementing it.
$publish-tickets
Publish Codex pipeline ticket files as GitHub or GitLab issues and stop. Use when the board should be populated without starting implementation.
$review-ticket
Run a fresh, independent Codex Reviewer on a built ticket and return CLEAR or BOUNCE. Use for the review stage only.
$run-ticket
Run one ticket through the Codex Architect -> Builder -> fresh Reviewer -> delivery loop. Use for an end-to-end ticket pipeline.
$start-all
Gate 1 for the complete Codex three-agent docs/prd dependency graph. Publish all tickets and run the global DAG sequentially.
$start-milestone
Gate 1 for one Codex three-agent module. Publish its tickets, then run ready tickets sequentially through Architect, Builder, Reviewer, and delivery.
$verify-delivery
Verify the post-merge Definition of Done for a Codex three-agent ticket. Use after delivery or when auditing completion.
.codex/agents/*.toml pins each role's model, reasoning effort, sandbox, and developer instructions. The Reviewer is read-only and always starts fresh.
Repository skills
$breakdown-prd, $run-ticket, and the stage skills replace Claude slash commands. AGENTS.md keeps the orchestration rules with the repository.
Sequential by design
The global dependency DAG is preserved, but v1 rejects parallel Builders because they share a checkout. That is a stated safety boundary, not hidden missing isolation.
Both runtimes, one project
Install this pattern and the Claude one in the same repo. They do not collide — .claude/ + CLAUDE.md sit beside .codex/ + .agents/ + AGENTS.md.
So teammates with different tools work the same project, and one person can switch runtimes on a token budget without development stalling. No hybrid pattern is offered — it would add a third scaffold to maintain and a model table pinning two vendors at once, for no capability these two installs lack.
Shared: the project
The docs/prd/ ticket tree, the [<id>] tracker title prefix, ticket/<ID> branch names, docs/plans/, and the delivery ledger. A ticket planned in one runtime and built in the other works, because none of these belong to a runtime.
Separate: the machinery
Roles, entry points and guidance are runtime-native and never overlap. The E2E suite asserts that shared state is not runtime-scoped — a ledger under one runtime's directory would let the other re-run delivered tickets.
Hub-and-Spoke Orchestrator + Headless Executors
proposed · as of 2026-08-10
One long-lived hub (Claude Opus 5) decomposes a PRD into contract-first task briefs, N spokes (headless codex exec, low reasoning effort, one isolated git worktree each) implement one brief apiece, and the *same* hub session then audits, reviews and merges each branch. The pyramid is flattened into a pipeline: exactly one expensive context for the whole run, and no agent-to-agent conversation anywhere.
Commands
/hub-brief[prd-path] [focus notes, e.g. how many briefs or what to defer]
Hub stage 1 — decompose a PRD into contract-first task briefs that a low-effort headless executor can implement without designing anything
/hub-collect[briefs-dir] [--all | ID ...] [--merge]
Hub stage 3 — re-audit each spoke branch, re-run its tests, review the diff, and merge only what clears the deterministic gate
Hub stage 2 — fan the ready briefs out to headless Codex executors, one isolated worktree each, and report what came back
/connect-asana"[asana-task-url]"asana · optional
Connect this repo to an Asana task so the pipeline mirrors milestones and tickets as Asana subtasks (optional; the pipeline runs fine without it)
Roles · model · effort
Hub — decomposeClaude Opus 5 @highSpoke — executeCodex CLI (codex exec) @lowHub — collect / reviewClaude Opus 5, the same session as the decompose stage @high
Read this before adopting. The hub reviews diffs written against a contract it wrote itself, in the same session. That review is not independent — it is what this pattern trades away for cost and throughput, and it will not catch a wrong brief that was faithfully implemented. If a bad merge is expensive, use the three-agent pattern instead.
1. Adopt
npx agent-templates@latest adopt hub-and-spoke-orchestrator-executors . — scaffold, CLAUDE.md, permission rules. Needs the Codex CLI on PATH; it is a hard dependency, not an accelerator.
2. Brief
/hub-brief — the hub turns your PRD into contract-first briefs. Every interface, type and error shape is fixed here, because the executors are told not to design.
3. Gate 1 — you decide
Review the briefs. This gate carries more weight than its three-agent counterpart: there is no independent reviewer downstream to catch a wrong contract.
4. Dispatch
/hub-dispatch — one invalid brief dispatches nothing. The rest fan out to headless codex exec, one isolated worktree each, self-repairing under a capped loop.
5. Collect & Gate 2
/hub-collect — re-audit, re-test, review, merge. quarantined outranks green tests; unverified never merges. Then your smoke test.
What a brief is, and how big
One brief = one disjoint write-set. Not a feature, not an effort estimate. Two briefs may run at once exactly when the files they own do not overlap, so the decomposition is a partition of the filesystem — and the audit checks it against what the executor actually wrote.
In the committed rehearsal a 70-line PRD with 4 requirements became 4 briefs of 57–73 lines, each owning exactly one file. A brief is longer than the PRD section it implements, on purpose: the executor starts cold and is forbidden to design, so the contract has to be in the brief.
Frontmatter — the machine-readable half
idStable and never reused. Names the branch (spoke/<id>) and the worktree.
blocked_byThe machine-readable DAG. Dangling ids and cycles fail the whole set before any worktree exists.
file_scopeThe write-set this brief owns. Audited against the committed diff, so straying is detected, not trusted. A repo-wide or firewall-denied scope is rejected at decomposition time.
test_cmdScoped to this brief’s module, never the whole suite — the full suite cannot pass until the last brief lands, so a whole-suite command fails every brief but that one.
Body — every section required, empty ones rejected
## ContractThe interfaces, types, signatures and exact error messages the executor transcribes. This is the section that makes low effort safe: nothing is left to decide.
## Done whenThe observable outcome, so completion is checkable independently of the tests passing.
## Out of scopeEach exclusion names its owner: “no schema changes — that is FND-01”. Unowned exclusions read as oversights and get helpfully implemented.
4 briefs, 2 waves — the real schedule from the committed rehearsal, recomputed here by the driver's own scheduler. Wave 2 cannot start until wave 1 is merged, because its worktrees fork from the default branch.
wave 1src/categorize.mjsCAT-01src/money.mjsMNY-01
wave 2src/cli.mjsCLI-01src/report.mjsRPT-01
Cut on file ownership
Not on features. Two briefs run at once exactly when their write-sets are disjoint, so the question at every boundary is who writes these files — never “do these belong together”.
Shared things go first
Schemas, types, contracts and config land in one foundation brief everything else is blocked_by. Duplicating a shared contract to dodge a dependency produces two incompatible versions of it.
A serial module is a bug now
If a module's briefs form one straight chain it can never use more than one lane. That is a decomposition problem to fix while briefs are still cheap — not a scheduling detail to discover mid-run.
Coming from the three-agent pattern?
The commands do not carry across — adopt installs one pattern's commands, and the scripts the other pattern's commands call are not present. The names differ on purpose: a reader who knows /breakdown-prd expects an independent reviewer downstream, and reusing the name would import that expectation into a pipeline that deliberately has none.
/breakdown-prd→ /hub-briefSame purpose, different artifact: a brief carries the full interface contract, its file-scope, and a per-module test command, because its implementer is forbidden to design.
/start-milestone · /start-all→ /hub-dispatch + /hub-collectSplit in two, because the hub must come back into the loop between fanning out and merging.
/plan-ticket→ no equivalentThe contract is already fixed in the brief; the executor does not plan.
/review-ticket→ no equivalentThere is no independent reviewer. This is the trade, stated plainly.
/verify-delivery→ collect.mjs gateRuns before the merge rather than after it.
/publish-tickets · /nightly-issues→ no equivalentNo tracker integration: the briefs and the branches are the record.
All-or-nothing dispatch
One invalid brief dispatches nothing. A bad decomposition is a hub problem, and low-effort executors will not notice it — so the gate runs before any worktree exists.
A global file firewall
No spoke writes dependency, lock, build, CI, secret or agent-config files — whatever its brief says. Deny is checked before scope, so a wide scope cannot launder a lockfile edit.
Two verdicts that outrank success
quarantined beats a green test run — passing tests is exactly what would otherwise wave an out-of-scope write through. unverified never merges: "could not check" is not "it is fine".