agent-templates 0.1.0 → 0.2.1

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

@@ -1,153 +1,164 @@
-# 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 |
+# 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 |
+| **CRLF workflow scripts rejected on Windows** — the Workflow tool's permission layer refuses scripts containing `\r` ("control characters that would be hidden in the approval dialog"), so `/start-milestone` and `/nightly-issues` cannot launch their workflows when git autocrlf has rewritten the installed `.js` files | `[internal]` — **first field observation**: Ruihang2017/Groundwork, Windows 11, Claude Code, 2026-07-18 (catalog issue #21; workaround used: inline `script` param with LF) | Fixed 2026-07-18: catalog ships `.gitattributes` (`* text=auto eol=lf`), `adopt.mjs` normalizes all text installs to LF regardless of source state, and E2E guards assert no `\r` in runtime files (scaffold + installs + catalog self-host) | 2026-07-18 |
+| **CRLF regression on target checkouts** — issue #21's install-time LF normalization does not survive the target repo's own git: a later `checkout`/clone with `core.autocrlf=true` re-CRLFs the installed workflow scripts, and `Workflow({name: …})` (including `start-all`'s name-resolved `run-milestone` child) is rejected again for control characters | `[internal]` — recurrence: Ruihang2017/Groundwork, Windows 11, Claude Code, 2026-07-18 (catalog issue #23; workaround used: inline `script` param with LF) | Fixed 2026-07-18: `adopt.mjs` installs/appends a `.gitattributes` in the **target repo** pinning `.claude/workflows/*.js` and `.claude/scripts/*.mjs` to `text eol=lf` (marker-checked, append-once); E2E asserts fresh install, append-to-existing, and idempotent re-run | 2026-07-18 |
+| **Workflow `args` arrive JSON-stringified** — some harness paths deliver the Workflow tool's `args` as a JSON **string**, so `Object.assign(defaults, args)` merges nothing and launch validation throws in milliseconds (`args.tickets must be a non-empty array`, `args.modules must be a non-empty array`) | `[internal]` — Ruihang2017/Groundwork, Windows 11, Claude Code, 2026-07-18 (catalog issue #23; killed the first `run-milestone` launch in 10ms and would crash `/start-all` identically) | Fixed 2026-07-18: all three workflow scripts (`run-milestone.js`, `start-all.js`, `nightly-issues.js`) parse first — `typeof args === 'string' ? JSON.parse(args) : (args \|\| {})`; E2E runs runner + start-all scenarios with stringified args end-to-end | 2026-07-18 |
+| **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`).
+
+**Whole-PRD driver (`/start-all`):** one sign-off runs every module in dependency order — the module DAG is computed deterministically from ticket `blocked_by` frontmatter (`milestone-dag.mjs`; dangling refs and cycles are hard errors), and the `start-all` workflow composes `run-milestone` per module. Failure policy (maintainer decisions, catalog issue #20): a failed module blocks its dependents; independent DAG branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`; re-runs resume via closed-issue filtering (completed modules arrive empty → `already-complete`). No cost ceiling by explicit `[team-policy]`. Prefer `/start-milestone` while you still want module-boundary checkpoints.
+
+**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
+    │   └── milestone-dag.mjs  # module DAG from ticket blocked_by frontmatter (topo order, cycle detection)
+    ├── workflows/
+    │   ├── run-milestone.js   # deterministic milestone runner (Workflow script)
+    │   ├── start-all.js       # whole-PRD driver: composes run-milestone per module in DAG order
+    │   └── 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
+        ├── start-all.md       # /start-all [mode]         → Gate 1 for the whole PRD (DAG order)
+        └── 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-18 | **`/start-all` shipped** (catalog issue #20; maintainer-decided semantics: failed module blocks dependents, independent branches continue in `autonomous`, any non-CLEAR stops everything in `supervised`, no cost cap, resume via closed-issue filtering): deterministic DAG script (`milestone-dag.mjs`, ticket `blocked_by` as ground truth, cycles/dangling refs are hard errors) + `start-all` workflow composing `run-milestone` per module + `/start-all` command. 19 new E2E checks (DAG fixtures incl. cycle; module-policy scenarios via stubbed child workflows). Per-ticket stages unchanged. | Maintainer answers on issue #20, 2026-07-18. | Horace Hou (decisions) / Claude Fable 5 (build) |
+| 2026-07-18 | **First field bug fixed** (catalog issue #21, reported from Ruihang2017/Groundwork through the upstream feedback channel): CRLF-rewritten workflow scripts are rejected by the Workflow tool on Windows. Fix: repo-wide `.gitattributes` (`eol=lf`), working tree renormalized (67 files), `adopt.mjs` installs all text as LF, E2E `\r` guards added. Recorded as the pattern's first true `[internal]` pitfall observation. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-18 | **Field bug #2 fixed** (catalog issue #23, same reporter channel): (a) #21's install-time LF fix did not survive target-side git checkouts — `adopt.mjs` now installs/appends a target-repo `.gitattributes` pinning `.claude/workflows/*.js` + `.claude/scripts/*.mjs` to `eol=lf` (marker-checked, append-once); (b) Workflow `args` can arrive JSON-stringified — all three workflow scripts gained the `typeof args === 'string' ? JSON.parse(args) : (args \|\| {})` shim. Both recorded as §4 pitfalls; E2E extended (stringified-args runner + start-all scenarios; `.gitattributes` install/append/idempotency). Per-ticket stages and model/effort table unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 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

@@ -1,31 +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.
+---
+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

@@ -1,25 +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.
+---
+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.