agent-templates 0.1.0

package/ADOPTING.md

@@ -0,0 +1,57 @@
+# Adopting a pattern
+
+How to apply a pattern from this catalog to a **new** project (even a folder holding nothing but a `PRD.md`) or an **existing** one.
+
+## 0. Pick the pattern
+
+Check the index in [README.md](README.md), then the pattern's own §1 **When to use / when not to use** — take the "not" side seriously. Check the pattern's expiry trigger (metadata table); do not copy an expired model/effort table without re-verifying it.
+
+## 1. Install — one command
+
+From the public npm registry (anonymous, works for anyone):
+
+```
+npx agent-templates@latest adopt three-agent-architect-builder-reviewer C:\path\to\your-project
+```
+
+Pin an exact version for reproducibility (`npx agent-templates@0.1.0 …`) — a published version is a verified snapshot of the catalog's recommendations. Alternatives: `npx github:Ruihang2017/agent-templates …` (tracks the repo, no release needed; npx caches git installs — `--prefer-online` picks up updates), or from a checkout: `node scripts/adopt.mjs three-agent-architect-builder-reviewer <target-dir>`.
+
+Idempotent (re-runs skip what exists; `--force` overwrites). It installs the scaffold `.claude/` (agents with pinned model/effort, stage commands, write guard, workflows, publish script), the universal `templates/ticket.template.md`, the platform tracker templates (`--platform gh|glab`, autodetected from the origin remote) into `.github/` or `.gitlab/`, creates `docs/prd|adr|plans/`, copies a root `PRD.md` to `docs/PRD.md`, and seeds or appends `CLAUDE.md` from the pattern snippet (marker-checked, never duplicated).
+
+## 2. New project from a bare PRD.md — end to end
+
+Preconditions: git repo + remote, authenticated tracker CLI (`gh auth login` / `glab auth login`), Node ≥ 18, Claude Code.
+
+1. `git init`, create the remote (e.g. `gh repo create`), commit `PRD.md`.
+2. Run `adopt.mjs` (above) — then commit the scaffolding.
+3. Review `CLAUDE.md`: add your project facts and non-negotiables above the pipeline section; keep **Operating mode: `supervised`** for now. Fill the **Constraint check** section of `.github/PULL_REQUEST_TEMPLATE.md` (or the GitLab MR template) from those non-negotiables.
+4. In Claude Code, in the project: **`/breakdown-prd`** — the Architect decomposes `docs/PRD.md` into `docs/prd/breakdown-plan.md` + sub-PRDs + template-compliant tickets (disjoint file-scopes, dependency DAG), then stops.
+5. **Gate 1 — your product judgment moment.** Review the breakdown: module boundaries, non-goals, the DAG, open questions. Edit/ask until right. Then sign off by running **`/start-milestone docs/prd/00-<module> supervised`** — tickets publish as tracker issues and the pipeline runs the first ticket to a CLEAR verdict, then stops for your merge. Re-run to continue (closed issues are skipped automatically).
+6. **Graduate**: when the supervised runs hold, flip `CLAUDE.md` to `Operating mode: autonomous` — from then on, one `/start-milestone` runs the whole module: plan → build → fresh-context review (bounce-capped) → merge on CLEAR → issue closed → Definition-of-Done verified, with no per-ticket approvals.
+7. **Gate 2**: when the PRD's tasks are done, you smoke-test the result. That is your only test duty — the agents own unit/integration/E2E throughout.
+8. Optional: arm the **nightly sweep** (pattern `INSTALL.md` § Nightly sweep) — overnight issue triage/fix/report while the machine is on.
+
+## 3. Existing project
+
+Same `adopt.mjs` run — skip-existing protects your files. The differences:
+
+- `CLAUDE.md` gets the snippet **appended**: read the merged result once and resolve contradictions with your existing rules (the pipeline rules assume no agent judges its own work).
+- An existing `.claude/settings.json` is kept; merge the scaffold's `hooks.PreToolUse` (write guard) and `permissions.allow` entries by hand.
+- Formalize `docs/PRD.md` for the area you will pipeline first — it can cover a single module; you do not need to spec the whole codebase to start.
+- Retrofit gradually: run one small module through `supervised` mode end to end before trusting `autonomous`. Your existing test suite becomes the Builder/Reviewer suite from day one.
+
+## 4. Distributing the catalog
+
+The repo is public, so distribution has two tiers:
+
+1. **npx from git — works for everyone, today, zero infra.** The `npx github:…` command above needs no credentials and no publishing. Pin `#main` or a tag for reproducibility.
+2. **Public npm — the release tier (LIVE).** Published as [`agent-templates`](https://www.npmjs.com/package/agent-templates) (MIT, maintainer decision 2026-07-17, issue #15). Anonymous installs, semver pinning that pairs with the catalog's expiry discipline (a published version = a verified snapshot of the recommendations), and a natural companion to a future GitHub Pages catalog site.
+
+**Why not GitHub Packages:** its npm registry requires an access token **even to install public packages** — "You need an access token to publish, install, and delete private, internal, and public packages" (GitHub docs, *Working with the npm registry*, verified live 2026-07-17) — and it supports scoped names only. That defeats frictionless public sharing; it remains the right choice only for private-org registries, which this catalog no longer needs.
+
+## 5. Day-2 operations
+
+- `/verify-delivery <ticket>` after every merge (automatic in autonomous mode) — delivery is verified, never assumed.
+- Nightly sweep for open issues; hand-written issues follow the installed templates so triage can convert them.
+- **Pattern-level problems go upstream**: if the pipeline itself misbehaves, file an issue on this catalog (templates provided) — its own nightly sweep triages pattern-tweak requests.
+- Re-verify the pattern's model/effort table when its expiry triggers (successor model or +6 months).

package/CLAUDE.md

@@ -0,0 +1,125 @@
+# agent-templates — Operating Manual
+
+> Auto-loaded into every session in this repo. Conversation with the user may be in Chinese; **every file committed to this repo MUST be in English** (docs, scaffolding, comments, identifiers).
+
+## What this repo is
+
+A library/catalog of the multi-agent development architecture patterns this team reuses across projects. Each pattern is a **self-contained, reusable unit**: a design write-up plus actual working scaffolding (CLAUDE.md snippets, subagent definitions, slash commands) that a new project copies directly instead of redesigning the architecture from scratch.
+
+This repo ships documentation, scaffolding, and a testbed. The only application code is the testbed's toy target app.
+
+**Target operating model** (what patterns are hardened toward): for a project that fits a pattern, humans decide at exactly two gates — upstream (master PRD → sub-PRDs → generated tickets, signed off before the pipeline starts) and downstream (a smoke test of the delivered work). Between those gates the multi-agent workflow runs autonomously. Consequences for this repo: not every project fits every pattern ("when not to use" is a required section, take it seriously), and role boundaries are enforced mechanically wherever possible — hooks and permission config over prose exhortation, because prose alone has already been observed to fail.
+
+**Testing policy** (`[team-policy]`, 2026-07-17, binding on every pattern): the agents own the whole test pyramid — unit, integration, and E2E — run manually or wired into the pipeline as fits the project. The human's only test duty is the final smoke test once the PRD's tasks are all done (Gate 2).
+
+## Layout
+
+```
+CLAUDE.md                              # this file — the operating manual
+README.md                              # human-facing pattern index
+ADOPTING.md                            # how users apply a pattern to new/existing projects
+LICENSE                                # MIT (scaffold-output carve-out noted in README § License)
+package.json                           # published npm package `agent-templates` (bin + files whitelist)
+scripts/
+  cli.mjs                              # npx entry point: list · adopt (dispatches to adopt.mjs)
+  adopt.mjs                            # one-command pattern installer (idempotent; E2E-tested)
+  build-site.mjs                       # generates the GitHub Pages catalog page from pattern data (never hand-edit output)
+templates/                             # UNIVERSAL — shared by all patterns and by this repo itself
+  pattern-README.template.md           # mandatory starting point for every new pattern
+  ticket.template.md                   # the ticket format (field-proven: fx / PIL-15 / FND-9 standard)
+  tracker/                             # tracker-native templates: github/ + gitlab/ — issues (bug-report,
+                                       #   task, decision-record) and the PR/MR template
+patterns/<pattern-name>/               # kebab-case; one directory per pattern
+  README.md                            # the write-up — MUST follow the schema below
+  scaffold/                            # drop-in files a target repo copies, then adapts
+testbed/                               # E2E for the pattern chain (see testbed/README.md)
+  e2e/run-e2e.mjs                      # Level 0: deterministic, zero-token — the merge gate for scaffold changes
+  app/                                 # Level 1: tiny real target project for live pipeline rehearsals
+.claude/                               # self-hosted pattern machinery — byte-synced scaffold copies (see "How this repo develops itself")
+.github/ISSUE_TEMPLATE/                # issue templates (from the scaffold) — pattern-tweak requests from other projects land here
+```
+
+Worked example — `patterns/three-agent-architect-builder-reviewer/` is the canonical entry; **every future pattern must match its format**:
+
+```
+patterns/three-agent-architect-builder-reviewer/
+├── README.md                          # schema-compliant write-up (the format reference)
+└── scaffold/
+    ├── INSTALL.md                     # how to drop the scaffold into a target repo
+    ├── claude-md-snippet.md           # block to append to the target repo's CLAUDE.md
+    └── .claude/
+        ├── settings.json              # PreToolUse write guard wiring
+        ├── hooks/
+        │   └── guard-main-session-writes.mjs
+        ├── scripts/
+        │   └── publish-tickets.mjs
+        ├── workflows/
+        │   ├── run-milestone.js
+        │   └── nightly-issues.js
+        ├── agents/
+        │   ├── architect.md
+        │   ├── builder.md
+        │   ├── reviewer.md
+        │   └── triage.md
+        └── commands/
+            ├── breakdown-prd.md
+            ├── plan-ticket.md
+            ├── build-ticket.md
+            ├── review-ticket.md
+            ├── verify-delivery.md
+            ├── start-milestone.md
+            └── nightly-issues.md
+```
+
+## Pattern README schema (all sections required, in this order)
+
+| Section | Must contain |
+|---|---|
+| Metadata table (under the title) | Pattern name · status (`proposed` / `trialed` / `adopted` / `deprecated`) · as-of date · expiry trigger · sign-off |
+| 1. When to use / when not to use | Concrete task shapes, both directions — not adjectives |
+| 2. Agent roles & boundaries | Per agent: what it does / what it must never do; who judges whom |
+| 3. Model + effort assignment | Table: role · model · effort · reasoning · source label per claim. Heading carries the as-of date |
+| 4. Known failure modes / pitfalls | Symptom · the specific context/harness it was observed in · mitigation · date recorded. "None recorded yet" is a valid honest entry; an invented one is not |
+| 5. Upstream / downstream integration | How work enters (master PRD → sub-PRD → ticket, ADRs), what leaves (PR, review verdict, docs), and the **human gates** — where humans decide, and where they must not be needed |
+| 6. Scaffold | What is in `scaffold/` and how to install it |
+| 7. Provenance & change log | Dated entries: what changed, on what basis, by whom |
+
+Status glossary: `proposed` = drafted, not signed off · `trialed` = signed off as the team standard, awaiting its first real-ticket run · `adopted` = has run ≥ 1 real ticket in a real project, named in the provenance log · `deprecated` = superseded, kept for history.
+
+Upstream docs convention assumed by patterns (exemplar: `fx-eye-tracking`): `docs/PRD.md` (master PRD) → `docs/prd/<module>/README.md` (sub-PRDs) → `docs/prd/<module>/tickets/*.md` (tickets = future issue bodies), plus `docs/adr/` for hard-to-reverse decisions.
+
+## Source labels (mandatory on every model/effort claim)
+
+| Label | Meaning |
+|---|---|
+| `[official]` | Anthropic docs / system card / model page — verifiable at a URL today |
+| `[vendor-benchmark]` | Anthropic-reported benchmark number |
+| `[third-party]` | External benchmark or report — name the source |
+| `[internal]` | Our own observation — name the harness, project, and date |
+| `[unverified]` | Unverified third-party data / needs testing |
+| `[team-policy]` | A deliberate team decision — a choice, not a capability claim |
+
+## Adding a new pattern
+
+1. Copy `templates/pattern-README.template.md` → `patterns/<kebab-name>/README.md`. Fill every section; delete none.
+2. Build `scaffold/` with actually-runnable files. Verify every config key (agent/command frontmatter, settings) against current Claude Code docs at write time — not from memory.
+3. `node testbed/e2e/run-e2e.mjs` must be green before merging any scaffold change; when you add scaffold surface (new files, new orchestration logic), extend the E2E suites to cover it.
+4. Open a PR. Status starts at `proposed`.
+5. Sign-off to merge: the repo maintainer (Horace Hou) approves schema compliance and grounding. Promotion to `adopted` additionally requires the pattern having run on ≥1 real ticket in a real project, named in the provenance log.
+6. Any later change to a model/effort recommendation updates the table **and** the as-of date **and** adds a provenance-log entry — in the same commit.
+
+## How this repo develops itself
+
+1. **Issues are the decision record; commits are only the change record.** Every unit of work starts as a GitHub issue stating what + why (use the universal templates — work items follow `task`/`bug-report`, records follow `decision-record`). The work lands via a PR referencing it (`Closes #N`), written against `.github/PULL_REQUEST_TEMPLATE.md` (byte-synced from `templates/tracker/github/`). **No direct merges to main.** Bootstrap exception: the rounds merged on 2026-07-17 before this rule existed are backfilled as `decision-record` issues #1–#4.
+2. **Self-hosted nightly sweep.** This repo runs the pattern's own `/nightly-issues`: other projects file pattern-tweak requests here (templates in `.github/ISSUE_TEMPLATE/`), and the sweep triages — and where fixable, fixes — them overnight. The machinery at `.claude/` (four agents, two workflows, `nightly-issues` + `verify-delivery` commands) is a **byte-synced copy of the scaffold**, enforced by the E2E integrity suite: change the scaffold first, then re-copy.
+3. **This repo's test suite** is `node testbed/e2e/run-e2e.mjs` — the Builder/Reviewer run it exactly like any project's tests.
+4. The scaffold's main-session write guard is **not installed here** — interactive doc-editing with the maintainer is this repo's norm. Revisit if orchestrator role leakage appears in this repo's own pipeline runs.
+5. Labels in use: `decision-record` · `triage:invalid` · `nightly:escalated` · `needs-human`.
+
+## Grounding rules — binding on every agent working in this repo, including Claude
+
+1. **No training-data impressions.** Every model/effort recommendation must be grounded in currently verifiable official documentation (link it), or be explicitly labeled `[unverified]` — "unverified third-party data / needs testing". If you cannot verify it right now, label it; never launder a hunch into a recommendation.
+2. **Official conclusions ≠ harness observations.** Keep "conclusion from official docs / system cards" and "phenomenon observed under one specific benchmark harness" visibly distinct (use the source labels). A single-harness observation is never written up as a general conclusion — scope it with harness, conditions, and date.
+3. **As-of dates move with recommendations.** Model capability and effort behavior change across versions; every recommendation is traceable, expirable, and updatable — never a permanent conclusion. Whenever a recommendation changes, its as-of date changes in the same commit.
+4. **Staleness (default policy, maintainer-adjustable):** a model/effort table expires when a successor to any listed model ships, or 6 months after its as-of date, whichever comes first. Expired ≠ wrong — it means "re-verify before citing or copying into a new project".
+5. **English only** in committed files; Chinese is for conversation, never for the repo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Horace Hou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# agent-templates
+
+[![npm](https://img.shields.io/npm/v/agent-templates)](https://www.npmjs.com/package/agent-templates) · **[Catalog site →](https://ruihang2017.github.io/agent-templates/)**
+
+Catalog of reusable multi-agent development architecture patterns. Each entry is a design write-up plus drop-in scaffolding (subagent definitions, slash commands, CLAUDE.md snippets) so a new project reuses a proven pattern instead of redesigning one.
+
+## Quickstart — from a bare `PRD.md` to a running pipeline
+
+```
+cd path\to\my-project        # contains PRD.md; git init + remote done; gh/glab authenticated
+npx agent-templates@latest adopt three-agent-architect-builder-reviewer .
+```
+
+(Also works: `npx github:Ruihang2017/agent-templates …` for the unreleased latest, or `node scripts/adopt.mjs …` from a checkout.)
+
+1. Review `CLAUDE.md`: add project facts, keep **Operating mode: `supervised`**; fill the PR template's Constraint check from your non-negotiables.
+2. In Claude Code, inside the project: **`/breakdown-prd`** — the Architect turns `docs/PRD.md` into sub-PRDs + tickets, then stops for your review.
+3. **Gate 1** — review the breakdown, then **`/start-milestone docs/prd/00-<module> supervised`**: tickets publish as tracker issues; each ticket runs plan → build → fresh-context review to CLEAR, pausing for your merge.
+4. When it holds, flip to `autonomous` — whole milestones run hands-off. **Gate 2** = your smoke test at the end. Full guide: [ADOPTING.md](ADOPTING.md).
+
+| Pattern | Status | As of | Summary |
+|---|---|---|---|
+| [three-agent-architect-builder-reviewer](patterns/three-agent-architect-builder-reviewer/README.md) | trialed | 2026-07-17 | Architect plans → Builder implements → independent Reviewer (fresh context, different model tier) clears or bounces; `/start-milestone` runs a whole module autonomously |
+
+- **Applying a pattern to your project** (new — even a bare `PRD.md` — or existing): [ADOPTING.md](ADOPTING.md) — one command: `node scripts/adopt.mjs <pattern> <target-dir>`
+- Operating manual, pattern schema, grounding rules: [CLAUDE.md](CLAUDE.md)
+- Adding a pattern: start from [templates/pattern-README.template.md](templates/pattern-README.template.md), process in [CLAUDE.md](CLAUDE.md) § "Adding a new pattern"
+- E2E testing for the pattern chain: [testbed/README.md](testbed/README.md) — `node testbed/e2e/run-e2e.mjs` is the merge gate for scaffold changes
+
+## License
+
+MIT — see [LICENSE](LICENSE). Carve-out: files installed **into your project** by `adopt.mjs` (the scaffold, templates, and anything generated from them) may be used in your projects without attribution.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "agent-templates",
+  "version": "0.1.0",
+  "description": "Catalog of multi-agent development architecture patterns - design write-ups plus drop-in scaffolding (agents, slash commands, workflows, templates).",
+  "license": "MIT",
+  "author": "Horace Hou",
+  "type": "module",
+  "bin": {
+    "agent-templates": "scripts/cli.mjs"
+  },
+  "files": [
+    "scripts/",
+    "patterns/",
+    "templates/",
+    "ADOPTING.md",
+    "CLAUDE.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ruihang2017/agent-templates.git"
+  },
+  "homepage": "https://github.com/Ruihang2017/agent-templates#readme",
+  "bugs": {
+    "url": "https://github.com/Ruihang2017/agent-templates/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node testbed/e2e/run-e2e.mjs"
+  }
+}

package/patterns/three-agent-architect-builder-reviewer/README.md

@@ -0,0 +1,153 @@
+# Pattern: Three-Agent Architect–Builder–Reviewer
+
+| Field | Value |
+|---|---|
+| **Pattern name** | `three-agent-architect-builder-reviewer` |
+| **Status** | `trialed` — signed off as the team standard 2026-07-17; promotes to `adopted` after its first real-ticket run (CLAUDE.md promotion rule) |
+| **As-of date** | 2026-07-17 |
+| **Expiry trigger** | First successor release to any listed model, or 2027-01-17 (+6 months), whichever comes first |
+| **Sign-off** | Horace Hou (repo maintainer), 2026-07-17 |
+
+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.
+
+## 1. When to use / when not to use
+
+**Use when:**
+- Ticket-scoped production changes where a bad merge is expensive: shared services, security-sensitive paths, concurrency-heavy code.
+- The ticket is large enough to amortize three agent runs (rule of thumb: ≥ half a day of human-equivalent work).
+- The team priority is predictable, reviewable delivery over token cost and latency — an explicit policy of this pattern.
+
+**Do not use when:**
+- Trivial or mechanical changes (typo fixes, config bumps, codemod output) — pipeline overhead dominates the value.
+- Throwaway spikes and prototypes — a plan plus an independent review of disposable code adds nothing.
+- Live pair-programming where a human already reviews every step in real time.
+
+*(Scope guidance is design-derived, not a benchmark claim.)*
+
+## 2. Agent roles & boundaries
+
+| Agent | Does | Never does |
+|---|---|---|
+| **Architect** (Planner) | Reads the ticket and the codebase; produces the implementation plan. Exploration/tool-call heavy. | Writes production code. |
+| **Builder** (Coder) | Implements against the Architect's plan; runs tests; iterates until passing. | Acts as the final judge of its own work; merges without Reviewer clearance. |
+| **Reviewer** | Runs in a **fresh context** (never the Builder's session); reviews the Builder's output against the ticket and the plan, focusing on edge cases, concurrency, and security-sensitive paths. Clears the work or bounces it back to the Builder with findings. | Continues the Builder's session; fixes code itself. |
+
+| **Triage** (nightly sweep only) | Classifies open tracker issues — fixable / invalid / needs-human — and synthesizes a cold-startable ticket file from each fixable one. | Fixes code; writes to the tracker (the report step owns all tracker writes). |
+
+The Reviewer is **deliberately a different model tier from the Builder** so the two do not share blind spots. This is a hard requirement of the pattern, not a cost knob.
+
+**Testing policy `[team-policy]` (2026-07-17):** the agents own the whole test pyramid. The Builder writes and runs unit + integration tests (and E2E tests where the ticket's acceptance calls for them); the Reviewer independently re-runs the full suite; the deliver step re-runs it on the merged default branch. Tests run manually or wired into the pipeline as fits the project. The human tests exactly once — the Gate 2 smoke test after the PRD's tasks are all done.
+
+Related in-house variant: fx-eye-tracking's `planner` / `generator` / `evaluator` harness — same independence principle, heavier machinery (spec decomposition, file-scope parallelism, sprint contracts, tracker governance). That harness runs a whole project; this pattern runs one ticket.
+
+## 3. Model + effort assignment (as of 2026-07-17)
+
+| Role | Model | Effort | Reasoning | Source labels |
+|---|---|---|---|---|
+| Architect | Claude Sonnet 5 | `xhigh` | Planning is terminal/tool-call-heavy work, where Sonnet 5 benchmarks strongest in the lineup: Terminal-Bench 2.1 **80.4** vs Opus 4.8's **74.6**. `xhigh` is Anthropic's documented recommendation for agentic exploration workloads. | Benchmark: `[third-party]` (link not captured — attach at first re-verification). Effort guidance: `[official]` |
+| Builder | Claude Opus 4.8 | `xhigh` | Anthropic's official guidance is to start at `xhigh` for coding and agentic use cases. Opus 4.8 leads Sonnet 5 on the hardest agentic-coding benchmark: SWE-bench Pro **69.2** vs **63.2**. One effort setting for all tickets — no per-ticket downgrades; team priority is predictable delivery over token cost. | Benchmark: `[vendor-benchmark]` (Anthropic-reported). Effort guidance: `[official]`. No-downgrade rule: `[team-policy]` |
+| Reviewer | Claude Fable 5 | `max` | The Reviewer is the last quality gate before merge. Fable 5 has the largest capability margin on the hardest problems (SWE-bench Pro **~80.3**), and catching missed edge cases is where that margin pays off most. `max` because token cost is explicitly not the constraint at this gate. | Benchmark: `[unverified]` — recorded as "reported" without a named source; treat as unverified until linked. `max` choice: `[team-policy]` |
+| Triage (nightly only) | Claude Sonnet 5 | `xhigh` | Classification + ticket synthesis is planning-shaped work; profile inherited from the Architect row rather than separately derived. | `[team-policy]` — no separate benchmark basis |
+
+Figures are transcribed from the team-finalized specification dated 2026-07-17 (§7). Do not re-derive or silently alter them; update only via the process in the repo CLAUDE.md (new as-of date + provenance entry in the same commit).
+
+## 4. Known failure modes / pitfalls
+
+| Pitfall | Context | Mitigation | Recorded |
+|---|---|---|---|
+| **Reviewer contamination** — review run inside the Builder's session inherits the Builder's assumptions and blind spots | Design constraint from the pattern spec (not a measured incident) | Reviewer always starts in a fresh context; `/review-ticket` checks for and refuses a contaminated session | 2026-07-17 |
+| **Tier collapse** — Reviewer switched to the Builder's model/tier "to save cost" | Design constraint | Different tier is a hard requirement; changing it means updating this pattern entry first, not the target repo's config | 2026-07-17 |
+| **Self-clearing** — Builder declares its own "small" diff done and skips review | Process risk | No merge without a Reviewer verdict attached to the PR | 2026-07-17 |
+| **Unbounded bounce loop** — Reviewer ↔ Builder ping-pong without convergence | Process risk | Cap at 2 bounce cycles, then escalate to a human | 2026-07-17 |
+| **Cold-start starvation** — the fresh-context Reviewer (or Builder) lacks context that lived only in the Architect's conversation | Design implication of fresh contexts | Ticket and plan must be self-contained (cold-startable); a plan that needs the planning conversation to be understood is defective | 2026-07-17 |
+| **`max`-effort overthinking / latency at the gate** | Claude Code's own effort-level description: `max` "may use excessive tokens resulting in long response times or overthinking. Use sparingly." — `[official]` product text, observed 2026-07-17 | Accepted at this gate by explicit `[team-policy]`; do not copy `max` to Builder/Architect by default; keep tickets small so review diffs stay bounded | 2026-07-17 |
+| **Orchestrator role leakage** — the main (orchestrator) session absorbs subagent work: plans, implements, or reviews inline instead of dispatching, dissolving the role boundaries the pattern exists for | `[internal]` — observed on fx-eye-tracking's planner/generator/evaluator harness (sibling of this pattern), reported by the maintainer, 2026-07-17. Soft "launch the subagent" prompts alone did not hold. | Mechanically enforced since 2026-07-17: a PreToolUse guard denies main-session Edit/Write while subagent calls pass (`agent_id` is present in hook input only for subagents — see the verification record in `scaffold/INSTALL.md`). Backed by prose rules in the CLAUDE.md snippet and a "never absorb the role" line in every stage command. If leakage still recurs, switch to Mode B (separate human-run sessions — no orchestrator exists to leak). | 2026-07-17 |
+| **Silent delivery drop** — end-of-pipeline bookkeeping relied on side effects that never fired: many MRs merged, **zero** tracker issues closed, and no step verified the transition | `[internal]` — fx-eye-tracking, reported by the maintainer, 2026-07-17. Root cause on that instance not yet diagnosed; typical causes: missing `Closes #N` in the MR description, or merging to a non-default branch (GitLab auto-close fires only on default-branch merges). | Delivery is verified, not assumed: run `/verify-delivery <ticket>` after every merge — it checks the Definition of Done (plan · tests · CLEAR verdict · merged · issue closed · writeback) and repairs gaps only with explicit human OK. Never trust tracker auto-close blindly. | 2026-07-17 |
+| **Guard bypass via Bash** — the write guard blocks the Edit/Write tool family only; the main session can still modify files through Bash (`echo >`, `git apply`, heredocs) | Known boundary of the mechanical guard — design analysis, 2026-07-17, not an incident | Accepted deliberately: blocking Bash would break legitimate orchestrator operations (checkout, merge, tracker CLI). The guard targets the observed failure mode — reflexive "I'll just edit it myself" — not a determined bypass. Prose rule stands: Bash in the main session is for orchestration, never for writing files. If bypass is ever observed in practice, record it here and escalate to Mode B. | 2026-07-17 |
+| **Nightly grinding** — the sweep re-attempts the same unfixable issue night after night, burning tokens | Design risk of the nightly loop (not a measured incident) | Unsolved/failed issues get `nightly:escalated` and are excluded from later sweeps until a human clears the label; `maxIssues` caps each night's spend | 2026-07-17 |
+| **Autonomous misjudgment of "invalid"** — the sweep wrongly declares a real issue invalid and it gets ignored | Design risk | Invalid verdicts only **label** (`triage:invalid`) and comment with evidence — never auto-close; the morning human is the final judge; triage is instructed to prefer `needs-human` when uncertain | 2026-07-17 |
+| **Harness-specific timeouts/failures** for these exact model+effort combinations | **None recorded yet** (as of 2026-07-17) | When observed: record here with harness name, conditions, and date | — |
+
+## 5. Upstream / downstream integration
+
+**Upstream (work intake)** — assumes the standard docs layout (exemplar: fx-eye-tracking):
+
+- `docs/PRD.md` (master PRD) → `docs/prd/<module>/README.md` (sub-PRD) → `docs/prd/<module>/tickets/*.md` (one file per ticket; each ticket is a future issue body).
+- The **ticket file is the Architect's input**; the Architect also reads the linked sub-PRD and any `docs/adr/` entries touching the affected area.
+- The Architect's plan lands at `docs/plans/<ticket-id>.md`. A hard-to-reverse choice made while planning becomes a new ADR, not a paragraph buried in the plan.
+
+**Downstream (deliverables):**
+
+- Builder → a PR: code + passing tests, referencing the ticket and the plan, plus a deviations note where it departed from the plan.
+- Reviewer → a verdict on the PR: **CLEAR** (short note of what was checked) or **BOUNCE** (numbered findings: `file:line`, failure scenario, severity). Findings go back to the Builder.
+- Net output: merged PR, updated docs/ADRs, closed ticket. Merge requires a CLEAR verdict.
+- **Feedback channel (upstream):** pattern-level problems observed while running the pipeline — a role boundary that misfits, a stale model/effort pin, an orchestration bug — are filed as issues against the pattern catalog (`Ruihang2017/agent-templates`, issue templates provided); the catalog self-hosts the nightly sweep and triages them. Project-level bugs stay in the project's own tracker.
+- Delivery is **verified, not assumed**: after every merge, `/verify-delivery <ticket>` checks the Definition of Done — plan on disk · tests green · CLEAR verdict · MR merged into the default branch · tracker issue closed · writeback done. Added 2026-07-17 after the fx-eye-tracking silent-delivery-drop observation (§4).
+
+**Human gates (target operating model):**
+
+- **Gate 1 — upstream sign-off = the start signal:** once the module's sub-PRD and all its tickets are generated (from a bare PRD: `/breakdown-prd` generates them for review; format: the catalog's `templates/ticket.template.md`), a human types **`/start-milestone <module>`**. That one action is the sign-off. The session then publishes every ticket as a tracker issue (`.claude/scripts/publish-tickets.mjs` — deterministic and idempotent, `[<id>]` title prefix as the dedupe key; agents never hand-create issues) and launches the milestone runner.
+- **Gate 2 — smoke test:** a human smoke-tests the delivered work at the end of the ticket batch / milestone.
+- **Between the gates the pipeline runs autonomously** via `.claude/workflows/run-milestone.js` (a Workflow script): plan → build → review → merge on CLEAR → deliver (including closing the tracker issue), with no per-ticket human approval. Stage order, reviewer freshness, the bounce cap, and no-merge-without-CLEAR are enforced **in code**, not prose — prose-only orchestration is a recorded failure mode (§4).
+- **Exception path (the only other way a human appears):** 2 bounce cycles without convergence, a failed build, or an unrepairable delivery item escalates to a human; the runner is fail-fast by default because later tickets may depend on earlier ones.
+- **On-ramp:** a project newly adopting the pattern starts in `supervised` mode: the runner takes one ticket to a CLEAR verdict and **stops the run** for the human merge (later tickets may depend on the merged result). Re-run `/start-milestone` to continue — tickets whose issues are already closed are filtered out before the run, which also makes crash recovery mechanical. Switch to `autonomous` once the pattern holds. The mode is declared in the target repo's CLAUDE.md (see `scaffold/claude-md-snippet.md`).
+
+**Orchestration mechanics:** a single ticket can still be run by hand with the stage commands; a milestone runs through the deterministic workflow. `ultracode` is not needed in target repos — typing `/start-milestone` is the explicit orchestration request (its instructions call the Workflow tool). Note that `ultracode` is a Claude Code **session setting** (`xhigh` effort + automatic workflow orchestration), not a model effort level — the pattern's pinned per-role efforts are unaffected by it. `[official]` — workflows + model-config docs, verified 2026-07-17 (record in `scaffold/INSTALL.md`).
+
+**Nightly issue sweep (unattended variant):** `claude -p "/nightly-issues"` on an OS schedule (Windows Task Scheduler etc.) while the machine is on. Flow: collect open issues → **Triage** (read-only; synthesizes tickets under `docs/prd/99-nightly/` for fixable ones) → **run-milestone** (autonomous, `continueOnFailure` — issues are independent) → one **report** step does all tracker writes: per-issue outcome comments, labels (`triage:invalid` / `nightly:escalated` / `needs-human`), closes delivered issues, and a `Nightly report YYYY-MM-DD` issue. The morning email is the tracker's own notification stream (watch the repo) — no SMTP to configure. Cost cap: `maxIssues` per night (default 5). Hand-written issues follow the catalog's universal tracker templates (`templates/tracker/`, installed to `.github/` / `.gitlab/`) so triage can convert them mechanically. Headless flags, permissions, and scheduling: `scaffold/INSTALL.md` § Nightly sweep.
+
+## 6. Scaffold
+
+```
+scaffold/
+├── INSTALL.md                 # install steps + config-key verification record
+├── claude-md-snippet.md       # block to append to the target repo's CLAUDE.md
+└── .claude/
+    ├── settings.json          # wires the PreToolUse write guard
+    ├── hooks/
+    │   └── guard-main-session-writes.mjs  # denies main-session Edit/Write; subagents pass
+    ├── scripts/
+    │   └── publish-tickets.mjs # tickets → tracker issues; idempotent; dry-run by default
+    ├── workflows/
+    │   ├── run-milestone.js   # deterministic milestone runner (Workflow script)
+    │   └── nightly-issues.js  # nightly sweep: triage → pipeline → report (Workflow script)
+    ├── agents/                # role definitions with pinned model + effort
+    │   ├── architect.md       # claude-sonnet-5 @ xhigh; writes the plan, no production code
+    │   ├── builder.md         # claude-opus-4-8 @ xhigh; inherits all tools
+    │   ├── reviewer.md        # claude-fable-5 @ max; read/run-only (no Write/Edit)
+    │   └── triage.md          # claude-sonnet-5 @ xhigh; nightly classification + ticket synthesis
+    └── commands/
+        ├── breakdown-prd.md   # /breakdown-prd [notes]    → pre-Gate-1: PRD → sub-PRDs + tickets
+        ├── plan-ticket.md     # /plan-ticket <ticket>    → Architect stage
+        ├── build-ticket.md    # /build-ticket <ticket>   → Builder stage
+        ├── review-ticket.md   # /review-ticket <ticket>  → Reviewer stage (fresh context)
+        ├── verify-delivery.md # /verify-delivery <ticket> → post-merge Definition-of-Done check
+        ├── start-milestone.md # /start-milestone <module> → Gate 1 signal: publish issues + run milestone
+        └── nightly-issues.md  # /nightly-issues [max]     → unattended sweep (headless claude -p)
+```
+
+Adoption is one command from the catalog — `node scripts/adopt.mjs three-agent-architect-builder-reviewer <target-dir>` — see the catalog's `ADOPTING.md` for the end-to-end walkthrough (bare `PRD.md` → running pipeline).
+
+Shared, universal assets live at the **catalog root**, not in this scaffold: `templates/ticket.template.md` (the ticket format — field-proven fx / PIL-15 / FND-9 standard) and `templates/tracker/` (issue + PR/MR templates for GitHub and GitLab). INSTALL steps 1–2 copy them into the target repo alongside `.claude/`.
+
+The deterministic chain is covered by the repo's Level-0 E2E (`node testbed/e2e/run-e2e.mjs`, see `testbed/README.md`) — green is the merge gate for scaffold changes. Level 1 (live pipeline rehearsal on `testbed/app/`) is the promotion trigger from `trialed` to `adopted`.
+
+Install steps and usage modes: [scaffold/INSTALL.md](scaffold/INSTALL.md). Frontmatter keys (`model`, `effort`, `tools`, command arguments) verified against official Claude Code docs on 2026-07-17 — see the verification record in INSTALL.md.
+
+## 7. Provenance & change log
+
+| Date | Change | Basis | Author |
+|---|---|---|---|
+| 2026-07-17 | Initial entry. Roles, boundaries, and the model/effort table adopted as the team standard. | Team-finalized specification, 2026-07-17. Benchmark figures transcribed as recorded there; original source links were not captured — attach them at the first re-verification. Scaffold config keys verified against live Claude Code docs same day (record in `scaffold/INSTALL.md`). | Horace Hou (spec) / Claude Fable 5 (write-up) |
+| 2026-07-17 | Added two `[internal]` failure modes observed on the fx-eye-tracking sibling harness: orchestrator role leakage, and silent delivery drop (MRs merged, issues never closed). Hardened the scaffold accordingly: orchestrator-discipline rules in the CLAUDE.md snippet, "never absorb the role" line in every stage command, new `/verify-delivery` Definition-of-Done command. Model/effort table unchanged. | Maintainer report (Horace Hou), 2026-07-17. | Horace Hou (report) / Claude Fable 5 (write-up) |
+| 2026-07-17 | Documented the target operating model — two human gates (upstream PRD/sub-PRD/ticket sign-off; final smoke test), autonomous pipeline in between, `supervised` on-ramp mode. Orchestrator write-denial is now mechanically enforced: PreToolUse guard denies main-session Edit/Write, subagent calls pass. Model/effort table unchanged. | Maintainer direction (Horace Hou), 2026-07-17. Hook mechanism verified against live Claude Code docs the same day (hooks.md, permissions.md — record in `scaffold/INSTALL.md`). | Horace Hou (direction) / Claude Fable 5 (write-up) |
+| 2026-07-17 | Gate 1 made concrete: `/start-milestone` = the human start signal → tickets auto-published as tracker issues (`publish-tickets.mjs`, adapted from fx-eye-tracking `create-issues.mjs`; `[<id>]` title prefix as dedupe key; smoke-tested dry-run/no-CLI/usage paths) → deterministic milestone runner (`run-milestone.js` Workflow script: stage order, reviewer freshness, bounce cap, merge policy in code). Added `templates/ticket.template.md` (adapted from fx ticket discipline). Recorded the Bash guard boundary as a known pitfall. Clarified `ultracode`: a session setting (`xhigh` + automatic workflow orchestration), not a model effort level — role efforts unchanged. | Maintainer direction (Horace Hou), 2026-07-17. fx-eye-tracking conventions read the same day (read-only). Workflow tool, `.claude/workflows/`, and `ultracode` semantics verified against live docs (workflows, claude-directory, model-config — record in `scaffold/INSTALL.md`). | Horace Hou (direction) / Claude Fable 5 (write-up) |
+| 2026-07-17 | **Catalog site**: claymorphic GitHub Pages page generated from pattern data (`scripts/build-site.mjs` — parses pattern README metadata/§1/§3 + package.json; live npm-version fetch with build-time fallback; deployed via `gh-pages` branch). Style spec + generated-not-handwritten rationale in catalog issue #17. | Maintainer direction (Horace Hou) with reference designs, 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (build) |
+| 2026-07-17 | **Released**: catalog published to public npm as `agent-templates` under MIT (maintainer decisions: MIT + personal ownership + publish, 2026-07-17 — catalog issue #15). README carries the scaffold-output attribution carve-out. Adoption command is now `npx agent-templates@latest adopt …`. | Maintainer decision (Horace Hou), 2026-07-17. | Horace Hou (decision) / Claude Fable 5 (release) |
+| 2026-07-17 | **Registry decision — public npm over GitHub Packages** (repo is public; goal is public sharing): GH Packages requires a token even to install public packages (`[official]` GitHub docs, verified live 2026-07-17) and is scope-only; npm allows anonymous installs and the bare name `agent-templates` was unclaimed (registry 404, same day). Publish itself is gated on maintainer decisions — license (repo has none), npm account/name — tracked in catalog issue #13; `package.json` carries the publish-prep (`files`, `repository`) with `private: true` until then. | Maintainer direction (Horace Hou) + live verification, 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (write-up) |
+| 2026-07-17 | **Distribution**: the catalog is npx-runnable (`npx github:Ruihang2017/agent-templates adopt <pattern> <dir>` — root `package.json` bin → `scripts/cli.mjs` dispatcher; `private: true` blocks accidental registry publish, git-specifier installs unaffected). README gained the five-step quickstart; ADOPTING.md gained the team-distribution tiers (npx-from-git → GitHub Packages → public npm) and the org-account question (open, issue #11). | Maintainer direction (Horace Hou), 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (build) |
+| 2026-07-17 | **Adoption path** (maintainer request: "a folder with only a PRD.md"): one-command installer `scripts/adopt.mjs` (idempotent; scaffold + universal templates + docs skeleton + CLAUDE.md seed/append; E2E-tested incl. re-run and platform variants), new `/breakdown-prd` command closing the flow gap between a bare master PRD and ticket'd modules (Architect charter extended to planning artifacts: plans + decomposition outputs, still never production code), and the catalog-level `ADOPTING.md` walkthrough (new + existing projects). Catalog issue #9. | Maintainer direction (Horace Hou), 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (build) |
+| 2026-07-17 | Templates made **universal** (maintainer direction): source of truth relocated from this scaffold to the catalog root — `templates/ticket.template.md` upgraded to the field-proven PIL-15 / FND-9 standard (traceability header with ADR/PR chain + per-ticket agent-assignment basis, `lane`/`blocked_by`/`blocks` frontmatter DAG, per-item Non-goal owners, file-scope does-not-touch + serial-safety analysis, code-level deliverables, project-defined acceptance-tag vocabulary, enumerated feedback-obligation escalation paths). Added `templates/tracker/`: PR/MR templates (pipeline-evidence + constraint-check sections, after MeritAI's) and a `decision-record` issue template formalizing catalog issues #1–#4's genre. The catalog itself uses the same templates (`.github/` byte-synced, E2E-enforced). Catalog issue #7. | Maintainer direction (Horace Hou), 2026-07-17, citing realtime-pilot PIL-15 and MeritAI FND-9 + PULL_REQUEST_TEMPLATE.md (both read-only references). | Horace Hou (direction) / Claude Fable 5 (write-up) |
+| 2026-07-17 | Documented the **upstream feedback channel** (target repos file pattern-level issues against the catalog, which self-hosts the nightly sweep to triage them). The catalog repo also adopted issue/PR decision-record discipline — see catalog issues #1–#5. | Maintainer direction (Horace Hou), 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (write-up) |
+| 2026-07-17 | Added the unattended **nightly issue sweep** (triage agent + `nightly-issues` workflow + `/nightly-issues` headless entry + native tracker issue templates so hand-written issues keep the pipeline format), the **testbed** (Level-0 deterministic E2E — 122 checks over guard/publisher/runner — plus the Level-1 live-rehearsal app; Level-0 green is now the merge gate for scaffold changes), `GH_BIN`/`GLAB_BIN` test-double overrides (fx `GLAB_BIN` precedent), and the **testing policy**: agents own unit/integration/E2E; the human's only test duty is the Gate 2 smoke test after the PRD completes. Headless/permission/scheduling facts verified against live docs (headless.md, permission-modes.md, permissions.md, scheduled-tasks.md, routines.md — record in `scaffold/INSTALL.md`). | Maintainer direction (Horace Hou), 2026-07-17; verified by testbed E2E 122/122 green. | Horace Hou (direction) / Claude Fable 5 (build) |
+| 2026-07-17 | Pre-merge adversarial review (three parallel reviewers; script findings reproduced with fixtures and fake gh/glab CLIs) — all findings fixed. Runner: a reviewer infrastructure failure no longer consumes bounce budget or dispatches phantom fixes (one retry → escalate `reviewer-failed`); `delivered` now requires merged ∧ issueClosed ∧ dodPassed; plan paths computed in code, agent-returned values verified; branch mismatch = builder failure; empty-findings BOUNCE escalates; config strictly validated; `supervised` mode stops the run after each CLEAR for dependency safety, resumable because closed issues are filtered on re-run. Publisher: existence check now fetches the issue list once per run and matches the `[<id>]` prefix exactly (fixes wrong-issue-number matching and per-ticket search rate/consistency risks); create failures keep the machine-readable summary and exit 1; within-run duplicate-id dedupe; BOM and quoted-YAML titles handled; invalid tickets included in the summary. DoD gains an explicit "tests green" item (verify-delivery + deliver prompt). Status corrected `adopted` → `trialed` per the promotion rule — this pattern has not yet run a real ticket (fx-eye-tracking ran the sibling harness, not this pipeline). | Internal adversarial review, 2026-07-17. | Claude Fable 5 (fixes); status correction flagged for maintainer confirmation |

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/architect.md

@@ -0,0 +1,31 @@
+---
+name: architect
+description: Architect (Planner) stage of the three-agent pattern. Reads the ticket and the codebase, produces the implementation plan at docs/plans/<ticket-id>.md. Exploration/tool-call heavy. Writes NO production code.
+model: claude-sonnet-5
+effort: xhigh
+tools: Read, Glob, Grep, Bash, Write
+---
+
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+     Do not change them here first — update the pattern entry in agent-templates, then sync. -->
+
+You are the **Architect** in the Architect → Builder → Reviewer pipeline. You plan; you do not build. You write **planning artifacts only**: per-ticket implementation plans (`docs/plans/`), and — when running a PRD decomposition via `/breakdown-prd` — the breakdown plan, sub-PRDs, and tickets under `docs/prd/` (follow that command's output spec and `templates/ticket.template.md` exactly). Never production code, tests, or configs.
+
+**Ticket-planning mode** — input: a ticket (ID or file path). Read the ticket, its sub-PRD, and any `docs/adr/` entries touching the affected area.
+
+Produce `docs/plans/<ticket-id>.md` containing:
+
+1. **Scope** — what this ticket changes, and explicitly what it does not.
+2. **Change list** — the exact files/functions to touch and how, found by exploring the codebase now, not guessed.
+3. **Test plan** — what proves each acceptance criterion.
+4. **Risks & edge cases** — concurrency and security-sensitive paths called out explicitly (the Reviewer will check these).
+5. **Open questions** — anything unresolved, each with who decides it.
+
+Rules:
+
+- Everything you write must be **cold-startable**: a fresh agent with no access to this conversation must be able to execute it from the file alone. If understanding it requires this conversation, it is defective.
+- In ticket-planning mode you write exactly one file — the plan.
+- Use Bash for read-only exploration only (builds, `git log`, inspection) — never to modify state.
+- A hard-to-reverse architectural choice made while planning is flagged as an ADR candidate in the plan, not buried in it.
+
+Output: the plan path plus a one-paragraph summary.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/builder.md

@@ -0,0 +1,25 @@
+---
+name: builder
+description: Builder (Coder) stage of the three-agent pattern. Implements one ticket against the Architect's plan, runs tests, iterates until passing. Never the final judge of its own work.
+model: claude-opus-4-8
+effort: xhigh
+---
+
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+     Do not change them here first — update the pattern entry in agent-templates, then sync. -->
+
+You are the **Builder** in the Architect → Builder → Reviewer pipeline.
+
+Input: a ticket and its plan at `docs/plans/<ticket-id>.md`. Read both before writing any code.
+
+Do:
+
+1. Implement exactly the plan's scope. Write and run the tests it calls for — unit and integration always, E2E where the ticket's acceptance requires it — and iterate until green. Testing is your job, not the human's.
+2. Where reality forces a departure from the plan, depart — and record it in a **Deviations** note (what changed, why).
+3. Finish with: a diff summary, the actual test output (never "should pass"), and the Deviations note.
+
+Never:
+
+- Judge your own work as final — clearance comes only from the Reviewer, in a fresh context.
+- Merge, or mark the ticket done.
+- Expand scope beyond ticket + plan. If the plan is wrong, say so in Deviations rather than silently redesigning.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/reviewer.md

@@ -0,0 +1,33 @@
+---
+name: reviewer
+description: Reviewer stage of the three-agent pattern. Independent judge in a FRESH context — never the Builder's session, deliberately a different model tier from the Builder so the two do not share blind spots. Clears the work or bounces it back with findings.
+model: claude-fable-5
+effort: max
+tools: Read, Glob, Grep, Bash
+---
+
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+     Do not change them here first — update the pattern entry in agent-templates, then sync. -->
+
+You are the **Reviewer** — the last quality gate before merge, independent of the Builder.
+
+Context rule: you must be running in a **fresh context**. Your input is only: the ticket, the plan (`docs/plans/<ticket-id>.md`), and the Builder's diff (branch or PR ref). If you have been handed the Builder's conversation or its self-assessment, stop and report the pattern violation instead of reviewing.
+
+Review the diff against the ticket and the plan, in priority order:
+
+1. **Edge cases** — inputs and states the happy path ignores.
+2. **Concurrency** — races, ordering assumptions, shared-state mutation.
+3. **Security-sensitive paths** — authz checks, input validation, secrets handling, injection.
+4. **Plan conformance** — undeclared deviations from the plan are findings.
+
+Method:
+
+- Run the FULL suite yourself via Bash — unit, integration, and E2E where present, not only the tests the diff touches. Never trust reported results.
+- Be adversarial: try to refute the claim that the ticket is done. Default to BOUNCE when uncertain.
+
+Verdict (exactly one):
+
+- **CLEAR** — with a short note of what was checked.
+- **BOUNCE** — with numbered findings: `file:line` · concrete failure scenario · severity. Findings go back to the Builder.
+
+Never: fix the code yourself; approve out of politeness; re-clear without new commits to review.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/triage.md

@@ -0,0 +1,31 @@
+---
+name: triage
+description: Nightly triage stage. Classifies an open tracker issue as fixable / invalid / needs-human; for fixable ones synthesizes a cold-startable pipeline ticket file from the issue. Never fixes code, never touches the tracker.
+model: claude-sonnet-5
+effort: xhigh
+tools: Read, Glob, Grep, Bash, Write
+---
+
+<!-- Model/effort: profile inherited from the Architect row of the pattern README §3 —
+     classification + ticket synthesis is planning-shaped work; no separate benchmark
+     basis. [team-policy], as of 2026-07-17. Update via the pattern entry, then sync. -->
+
+You are the **Triage** stage of the nightly issue sweep.
+
+Input: one tracker issue (number, title, body, labels).
+
+Classify it as exactly one of:
+
+- **fixable** — a real defect or small task the pipeline can complete autonomously: a clear symptom or goal, bounded scope, and you can trace it to specific code by exploring now.
+- **invalid** — not a real issue: works as intended, duplicate, or out of scope. State why, with evidence (file refs, the behavior you verified).
+- **needs-human** — real, but not autonomous-safe: needs product judgment, a hard-to-reverse choice, is too large for one overnight ticket, or you cannot locate the code.
+
+For **fixable** only: write a ticket file at `docs/prd/99-nightly/tickets/ISS-<number>-<slug>.md` following `templates/ticket.template.md` (`id: ISS-<number>`, `module: 99-nightly`, honest `size`). Inline everything the pipeline needs — quote the relevant issue text, name the files you traced — per the cold-start rule. The acceptance checklist must be classified, mechanical wherever possible, and MUST turn the reported symptom into a test.
+
+Rules:
+
+- Read the code to verify claims before classifying — never classify from the issue text alone.
+- Never modify code. Never close, label, or comment on issues — tracker writes belong to the report step.
+- When torn between fixable and needs-human, choose **needs-human**: a wrong autonomous fix at night is worse than a skipped issue.
+
+Return: `classification`, `reason` (with evidence), and `ticketPath` (fixable only).

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/breakdown-prd.md

@@ -0,0 +1,18 @@
+---
+description: Decompose docs/PRD.md into sub-PRDs + template-compliant tickets (three-agent pattern, pre-Gate-1 planning)
+argument-hint: [focus notes, e.g. module-count hint or what to defer]
+---
+
+Launch the **architect** subagent to decompose the master PRD. Optional focus notes from the human: `$ARGUMENTS`
+
+Input: `docs/PRD.md` (hard requirement — STOP with a clear message if absent) plus any existing `docs/adr/` entries.
+
+Output (planning artifacts only — the architect writes no production code):
+
+1. `docs/prd/breakdown-plan.md` — the module split, cut on **file-ownership boundaries** (disjoint file-scopes are what make parallel lanes safe later; shared contracts/schemas go into a foundation module built first), the global file-scope allocation table, and the ticket dependency DAG (mirrors each ticket's `blocked_by`/`blocks`).
+2. Per module `NN-<name>`: `docs/prd/NN-<name>/README.md` — the sub-PRD: problem, scope/non-goals, decisions (each with a basis), rejected alternatives, open questions (each with an owner), work-breakdown table (ticket · size · lane · file-scope · depends-on), acceptance, changelog.
+3. `docs/prd/NN-<name>/tickets/<ID>-<slug>.md` — every ticket follows `templates/ticket.template.md` **fully**: traceability header, "Why `<agent>`" basis, `lane`/`blocked_by`/`blocks` frontmatter, per-item Non-goal owners, file-scope + does-not-touch + serial-safety, code-level deliverables, classified acceptance (tag vocabulary from this repo's CLAUDE.md), test plan, feedback obligation. Every ticket must be cold-startable.
+
+When the architect returns: present the breakdown summary (modules, ticket count, DAG, open questions) and **STOP**. This output is the input to Gate 1 — the human's review plus `/start-milestone` is the sign-off. Never begin implementation from this command.
+
+Hard rule: this stage runs in the **architect** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role.