agent-templates 0.4.3 → 0.4.8

package/ADOPTING.md

@@ -16,7 +16,11 @@ npx agent-templates@latest adopt three-agent-architect-builder-reviewer C:\path\
 
 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).
+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 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).
+
+**Platform (GitHub vs GitLab)** is resolved before anything is installed — from the origin remote host, else a repo-local signal (`.gitlab-ci.yml` → GitLab, existing `.github/` → GitHub). If neither is present (e.g. a fresh repo with only a `PRD.md`), adopt **does not guess**: run interactively it asks; run non-interactively (an agent or CI) it exits without installing and asks you to pass `--platform gh|glab`. So on a bare repo, either set the remote first or pass `--platform`. The resolved value is written to the `Tracker:` line in `CLAUDE.md`, which the pipeline reads.
+
+**Upstream issue escalation is opt-in.** By default the installed `CLAUDE.md` carries **no** instruction to file pattern-level problems against any catalog — no external repo slug is written into your repo (safe for commercial and private projects). Pass `--upstream` to include the bullet pointing at the catalog you adopted from, or `--upstream <owner/repo>` to point it at your own fork or internal catalog.
 
 ## 2. New project from a bare PRD.md — end to end
 
@@ -35,6 +39,17 @@ Preconditions: git repo + remote, authenticated tracker CLI (`gh auth login` / `
 
 Same `adopt.mjs` run — skip-existing protects your files. The differences:
 
+**Updating to a newer catalog version:** a plain re-run only adds files that don't exist yet; it will not update a file the previous version already installed. To pull the latest, re-run with `--force` (it overwrites, including `.claude/settings.json`), so commit first and review the diff to re-apply local customizations:
+
+```
+git add -A && git commit -m "checkpoint before agent-templates update"
+npx agent-templates@latest adopt three-agent-architect-builder-reviewer . --force
+git diff
+```
+
+`--force` refreshes the scaffold and tracker/settings files, but not the `CLAUDE.md` pipeline section or `.gitattributes` (both marker-guarded) — re-apply any pipeline-rule changes from a release by hand.
+
+
 - `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.

package/CLAUDE.md

@@ -116,7 +116,7 @@ Upstream docs convention assumed by patterns (exemplar: `fx-eye-tracking`): `doc
 
 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.
+3. **This repo's test suite** is `node testbed/e2e/run-e2e.mjs` — the Builder/Reviewer run it exactly like any project's tests. **CI enforces it server-side**: `.github/workflows/test.yml` runs the suite on every PR and push to `main` (ubuntu + windows × Node 18/20). Releases publish from a `v*` tag via `.github/workflows/publish.yml` (E2E gate → tag-matches-version check → `npm publish` with the `NPM_TOKEN` secret) — see README § "CI & releasing".
 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`.
 

package/README.md

@@ -1,6 +1,6 @@
 # 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/)**
+[![npm](https://img.shields.io/npm/v/agent-templates)](https://www.npmjs.com/package/agent-templates) · [![test](https://github.com/Ruihang2017/agent-templates/actions/workflows/test.yml/badge.svg)](https://github.com/Ruihang2017/agent-templates/actions/workflows/test.yml) · **[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.
 
@@ -18,6 +18,18 @@ npx agent-templates@latest adopt three-agent-architect-builder-reviewer .
 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).
 
+### Updating an existing install
+
+Re-run adopt with `--force` to pull the latest catalog version. A plain re-run only adds new files (existing ones are skipped); `--force` overwrites changed ones. Because it overwrites (including `.claude/settings.json`), commit first, then review the diff and re-apply any local customizations:
+
+```
+git add -A && git commit -m "checkpoint before agent-templates update"
+npx agent-templates@latest adopt three-agent-architect-builder-reviewer . --force
+git diff        # re-apply your customizations (esp. .claude/settings.json)
+```
+
+`--force` refreshes the scaffold and tracker/settings files. It does **not** rewrite the `CLAUDE.md` pipeline section or `.gitattributes` (both marker-guarded, so a re-run reports them as already present) — if a release changes the pipeline rules in the snippet, re-apply those by hand.
+
 | 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 |
@@ -42,6 +54,18 @@ Installed into your project by `adopt`; run them in Claude Code. Full list is ge
 - 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
 
+## CI & releasing
+
+CI ([`.github/workflows/test.yml`](.github/workflows/test.yml)) runs the E2E suite on every PR and push to `main`, across ubuntu + windows × Node 18/20 — the merge gate is enforced server-side and cross-platform.
+
+Releases publish from a version tag ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)): bump `package.json`, then
+
+```
+git tag vX.Y.Z && git push origin vX.Y.Z   # X.Y.Z = the version in package.json
+```
+
+CI re-runs the E2E gate, checks the tag matches `package.json`, and publishes to npm. **One-time setup:** add an `NPM_TOKEN` repo secret (Settings → Secrets and variables → Actions).
+
 ## 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

@@ -1,6 +1,6 @@
 {
   "name": "agent-templates",
-  "version": "0.4.3",
+  "version": "0.4.8",
   "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",

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

@@ -4,8 +4,8 @@
 |---|---|
 | **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 |
+| **As-of date** | 2026-07-21 (model/effort revised; §7) |
+| **Expiry trigger** | First successor release to any listed model, or 2027-01-21 (+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.
@@ -40,16 +40,16 @@ The Reviewer is **deliberately a different model tier from the Builder** so the
 
 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)
+## 3. Model + effort assignment (as of 2026-07-21)
 
 | 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]` |
+| Architect | Claude Opus 4.8 | `max` | The plan is the pattern's cold-start contract: Builder and Reviewer consume it in fresh contexts, so anything the plan leaves vague drifts downstream. Field runs showed `sonnet-5 @ xhigh` plans coming out too general — the highest-leverage stage under-invested. Moved to the top model at `max`: token budget is explicitly not the constraint here, and plan depth pays for itself in reduced downstream drift and bounces. Sharing the Builder's model at a higher effort is fine — the independence constraint applies only to the Reviewer. | Plan-vagueness observation: `[internal]` (maintainer, 2026-07-21, across the recent autonomous runs). Investment choice: `[team-policy]` |
 | 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 |
+| Reviewer | Claude Fable 5 | `xhigh` | The Reviewer is the last quality gate before merge, and Fable 5 has the largest capability margin on the hardest problems (SWE-bench Pro **~80.3**) — at this gate that raw margin, not effort headroom, is what catches edge cases. Dropped from `max` to `xhigh`: `max` carries a documented overthinking/latency risk (§4), and with the stronger Architect producing tighter plans the Reviewer's burden drops. | Benchmark: `[unverified]` — recorded as "reported" without a named source; treat as unverified until linked. Effort choice: `[team-policy]` (+ §4 `max`-overthinking pitfall) |
+| Triage (nightly only) | Claude Sonnet 5 | `xhigh` | Classification + ticket synthesis is planning-shaped work; profile derived separately from the Architect row (nightly triage does not need the Architect's full planning tier). | `[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).
+Figures dated 2026-07-17 are from the team-finalized specification (§7); the Architect and Reviewer rows were revised 2026-07-21 (§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
 
@@ -120,9 +120,9 @@ scaffold/
     │   ├── 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
+    │   ├── architect.md       # claude-opus-4-8 @ max; 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)
+    │   ├── reviewer.md        # claude-fable-5 @ xhigh; 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
@@ -154,6 +154,9 @@ Install steps and usage modes: [scaffold/INSTALL.md](scaffold/INSTALL.md). Front
 | 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-20 | **Doc/site command coverage mechanized** (catalog issue #35, maintainer direction: `/start-all` had shipped but never appeared in the npm README or the catalog site, so users could not discover it — surfacing commands must be impossible to forget). The command frontmatter is the single source of truth: `build-site.mjs` now renders a Commands section per pattern from it (site complete by construction), README carries the full command list, and an E2E coverage gate asserts every `scaffold/.claude/commands/*.md` name appears in BOTH the generated site and README with a non-empty description (plus a non-vacuous sentinel guard). Adding a command without documenting it now fails the merge gate. No pattern-behavior change. | Maintainer direction (Horace Hou), 2026-07-20. | Horace Hou (direction) / Claude Opus 4.8 (build) |
+| 2026-07-21 | **Model/effort revised** (catalog issue #42, maintainer decision from field observation): Architect `claude-sonnet-5 @ xhigh` → `claude-opus-4-8 @ max` — plans were running too general and, being the fresh-context cold-start contract, under-specified plans drift downstream; the top model at `max` is invested in the highest-leverage stage (token budget not a constraint). Reviewer `claude-fable-5 @ max` → `@ xhigh` — Fable 5's capability margin (not effort headroom) is what catches edge cases at the gate, and `max` carries the documented overthinking/latency risk (§4). Builder and Triage unchanged; Reviewer stays a different model tier from the Builder. Same-commit: §3 table + as-of date, agent frontmatter, snippet, integrity pins. No benchmark claims invented — the Architect change is grounded in the `[internal]` observation + a `[team-policy]` choice. | Maintainer decision (Horace Hou), 2026-07-21. | Horace Hou (decision) / Claude Opus 4.8 (build) |
+| 2026-07-20 | **Upstream issue escalation made opt-in** (catalog issue #40, maintainer decision): the CLAUDE.md snippet's "file pattern-level problems against the catalog" bullet — which hardcoded the maintainer's repo slug and a `gh issue create` instruction — is now wrapped in `<!-- upstream-escalation -->` markers and stripped by default. `adopt --upstream` opts in (bare = the catalog you adopted from; `--upstream <owner/repo>` retargets to a fork or internal catalog); the markers never leak into CLAUDE.md. Rationale: commercial and private adopters do not want an external repo slug or "file issues upstream" behavior written into their repo unasked. A neighboring line that named the product was also generalized to "the upstream pattern catalog". E2E: default adopt writes no catalog slug/marker/bullet; `--upstream` and `--upstream <repo>` include and retarget it. | Maintainer decision (Horace Hou), 2026-07-20. | Horace Hou (decision) / Claude Opus 4.8 (build) |
+| 2026-07-20 | **adopt never guesses the platform** (catalog issue #38, maintainer decision, refining #34): the no-signal fallback no longer silently defaults to `gh`. Resolution order — `--platform`, origin host, repo-local signal (`.gitlab-ci.yml`/`.github/`); when none resolve, adopt prompts if interactive and otherwise exits without installing, asking for `--platform gh|glab`. This makes the agent-driven flow confirm the platform (adopt errors → agent asks the user → re-runs with `--platform`) before any infrastructure is built. E2E: no-signal non-TTY exits 1 and installs nothing; a repo-local signal still resolves without `--platform`. | Maintainer decision (Horace Hou), 2026-07-20. | Horace Hou (decision) / Claude Opus 4.8 (build) |
 | 2026-07-20 | **Platform compatibility hardened** (catalog issue #34, maintainer question): `adopt.mjs` detection now uses multiple deterministic signals — origin host `gitlab`/`github` substring, then a repo-local signal (`.gitlab-ci.yml` → glab, existing `.github/` → gh), then default gh with a loud ambiguity note — so a self-hosted GitLab on a custom domain is no longer misread as GitHub. The resolved platform is recorded as a `Tracker:` line in the adopted CLAUDE.md, and `/start-milestone` · `/start-all` · `/nightly-issues` now read `platform` from that line instead of guessing (parallel to Operating mode / testCmd). E2E: self-hosted-GitLab detection, `Tracker:` line matches platform, ambiguity note. Runtime scripts' own `--platform`/autodetect unchanged. | Maintainer question (Horace Hou), 2026-07-20. | Horace Hou (question) / Claude Opus 4.8 (fix) |
 | 2026-07-19 | **Field bug #4 fixed** (catalog issue #31, field report from Ruihang2017/Groundwork2): `milestone-dag.mjs` emitted each module's tickets in ID order instead of topologically by intra-module `blocked_by`, so a module whose declared order deviates from ID order dispatched a ticket before its blocker and failed at the Builder's precondition gate. Fix: a shared Kahn `topoSort` now orders both modules and, within each module, tickets by intra-module `blocked_by` (cross-module edges stay module-level; ID order as tiebreak; intra-module cycle fails loudly). E2E +7 (suite-dag D6 the 0502/0503 inversion, D7 intra-module cycle, D8 ID-order tiebreak). run-milestone dispatch loop unchanged. | Field report (Horace Hou via Groundwork2), 2026-07-18. | Horace Hou (report) / Claude Opus 4.8 (fix) |
 | 2026-07-19 | **Pipeline tool surface explicitly pre-allowed** (catalog issue #30, maintainer direction): scaffold `settings.json` now enumerates allow rules for everything the stages legitimately run — deterministic scripts, git branch/commit/push/read set, `npm test`-family, `gh`/`glab` issue list/view/comment/edit|update|note/close/create — so a fully autonomous `/start-all` → deliver → nightly cycle triggers zero interactive approvals. Deliberately not pre-allowed (role discipline stays mechanical): `git merge`/`rebase`/`reset`/`clean`, `gh pr *`, and bare `git:*`/`gh:*`/`glab:*` wildcards — E2E asserts both directions so drift fails the gate. Risk accepted and recorded: `git push:*` includes force variants; `gh issue create:*` is broader than the publish-tickets discipline (nightly report issue needs it); prefix-deny of flags is structurally incomplete so not attempted. | Maintainer direction (Horace Hou), 2026-07-19. | Horace Hou (direction) / Claude Fable 5 (build) |

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

@@ -1,12 +1,12 @@
 ---
 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
+model: claude-opus-4-8
+effort: max
 tools: Read, Glob, Grep, Bash, Write
 ---
 
-<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-21.
      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.

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

@@ -2,11 +2,11 @@
 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
+effort: xhigh
 tools: Read, Glob, Grep, Bash
 ---
 
-<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-21.
      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.

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

@@ -12,7 +12,7 @@ From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-bu
 2. Install the catalog's **universal templates** (shared by all patterns — source of truth is the catalog root, not this scaffold): `templates/ticket.template.md` → the target repo's `templates/`; the platform half of `templates/tracker/` → `.github/` (ISSUE_TEMPLATE/ + PULL_REQUEST_TEMPLATE.md) or `.gitlab/` (issue_templates/ + merge_request_templates/). Then fill the PR/MR template's **Constraint check** section with the target repo's CLAUDE.md non-negotiables. Hand-written issues and pipeline PRs now share one format that triage can convert and reviewers can verify.
 3. The write-guard hook needs Node.js ≥ 18 on PATH. It denies main-session Edit/Write with a dispatch instruction; subagent writes pass. Override switch for human-approved out-of-pipeline edits: create `.claude/allow-main-writes`, delete it afterwards — and add that path to `.gitignore`.
 4. The tracker steps (`publish-tickets.mjs`, `deliver-ticket.mjs`, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides). Delivery (merge `--no-ff` + push + verified issue close + deterministic DoD) is `deliver-ticket.mjs` — never an agent improvising git/tracker writes; `settings.json` carries explicit allow rules for the pipeline's whole tool surface (the three deterministic scripts, the enumerated git branch/commit/push set, `npm test`-family test commands, and the enumerated `gh`/`glab` issue commands) so unattended runs do not stall waiting for interactive approval (catalog issues #26, #30). Deliberately NOT pre-allowed: `git merge` / `rebase` / `reset` / `clean` and `gh pr *` — merging belongs to `deliver-ticket.mjs`. If your project's test command is not `npm test` / `npm run test` / `node --test`, add one more allow rule for it (e.g. `Bash(pytest:*)`).
-5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target) and the **Tracker** line (`gh` for GitHub, `glab` for GitLab — the commands and workflows read the platform from this line). `adopt.mjs` sets Tracker automatically from the origin remote; set it by hand only on a manual install.
+5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target) and the **Tracker** line (`gh` for GitHub, `glab` for GitLab — the commands and workflows read the platform from this line). `adopt.mjs` sets Tracker automatically from the origin remote; set it by hand only on a manual install. The snippet contains one **opt-in** bullet between `<!-- upstream-escalation -->` markers that tells agents to file pattern-level problems against the catalog — **delete that block (and its markers) unless you want it**, or repoint the `--repo` slug at your own catalog. `adopt.mjs` strips it by default; keep it only with `--upstream`.
 6. Ensure the docs layout the pipeline assumes exists: `docs/PRD.md`, `docs/prd/<module>/README.md` (the sub-PRD — `/start-milestone` hard-requires it), `docs/prd/<module>/tickets/` (author tickets from `templates/ticket.template.md`), `docs/adr/`, and an empty `docs/plans/`.
 7. Check the pattern entry's expiry (README metadata table). If expired, re-verify the model/effort table against current official docs before adopting — do not copy an expired recommendation into a new project.
 

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

@@ -12,9 +12,9 @@
 Every non-trivial ticket flows through three stages; no agent judges its own work.
 
 - **`/breakdown-prd [notes]`** — pre-Gate-1: the Architect decomposes `docs/PRD.md` into a breakdown plan + sub-PRDs + template-compliant tickets (disjoint file-scopes, dependency DAG), then stops for human review.
-- **`/plan-ticket <ticket>`** — Architect (`claude-sonnet-5` @ `xhigh`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
+- **`/plan-ticket <ticket>`** — Architect (`claude-opus-4-8` @ `max`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
 - **`/build-ticket <ticket>`** — Builder (`claude-opus-4-8` @ `xhigh`) implements the plan, runs tests until green, records deviations. Never merges or self-clears.
-- **`/review-ticket <ticket>`** — Reviewer (`claude-fable-5` @ `max`) in a **fresh context**, deliberately a different model tier from the Builder. Focus: edge cases, concurrency, security-sensitive paths. Verdict **CLEAR** or **BOUNCE**; merge requires CLEAR.
+- **`/review-ticket <ticket>`** — Reviewer (`claude-fable-5` @ `xhigh`) in a **fresh context**, deliberately a different model tier from the Builder. Focus: edge cases, concurrency, security-sensitive paths. Verdict **CLEAR** or **BOUNCE**; merge requires CLEAR.
 - **`/verify-delivery <ticket>`** — post-merge Definition-of-Done check: plan on disk · tests green · CLEAR verdict · MR merged into the default branch · **tracker issue closed** · writeback done. Run after **every** merge; tracker auto-close side effects are never trusted blindly.
 - **`/start-milestone <module> [mode]`** — the Gate 1 start signal: verify sub-PRD + tickets, publish tickets as tracker issues (deterministic idempotent script — agents never hand-create issues), then run every ticket through the deterministic `run-milestone` workflow (stage order, bounce cap, merge policy enforced in code).
 - **`/start-all [mode]`** — Gate 1 for the **whole PRD**: compute the module DAG from ticket `blocked_by` frontmatter (`milestone-dag.mjs`, deterministic — cycles and dangling refs fail loudly), publish every module, then drive all modules through `run-milestone` in dependency order. Failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`. Re-run to resume — fully-closed modules skip as already-complete.
@@ -35,5 +35,7 @@ Rules:
 - Trivial/mechanical changes may skip the pipeline only with an explicit human OK.
 - Ticket files are the issue-content source of truth. Issues are created only by `.claude/scripts/publish-tickets.mjs` (`[<id>]` title prefix = dedupe key); to change an issue body, edit the ticket file and republish. Issue state (close) moves via the deliver step / `/verify-delivery`, never by hand mid-pipeline.
 - Agents own the whole test pyramid: the Builder writes and runs unit + integration tests (and E2E where the ticket's acceptance calls for it); the Reviewer re-runs the full suite independently; the deliver step re-runs it on the merged default branch. The human tests exactly once — the Gate 2 smoke test after the PRD's tasks are all done.
+<!-- upstream-escalation:start -->
 - **Pattern-level problems go upstream, not here.** If the pipeline itself misbehaves (a role boundary misfits, a model/effort pin looks stale, an orchestration bug), file an issue against the pattern catalog — `gh issue create --repo Ruihang2017/agent-templates` using its issue templates — so the catalog's own nightly sweep triages it. Project bugs stay in this repo's tracker.
-- Model/effort per role are pinned in `.claude/agents/*.md`. Change them by updating the pattern entry in agent-templates first (new as-of date + provenance entry), then syncing here — never by editing only this repo.
+<!-- upstream-escalation:end -->
+- Model/effort per role are pinned in `.claude/agents/*.md`. Change them by updating the pattern entry in the upstream pattern catalog first (new as-of date + provenance entry), then syncing here — never by editing only this repo.

package/scripts/adopt.mjs

@@ -18,6 +18,7 @@
 
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { execFileSync } from 'node:child_process'
+import { createInterface } from 'node:readline/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -31,10 +32,27 @@ if (pIx !== -1 && (!PLATFORM || PLATFORM.startsWith('--'))) {
   console.error('missing or invalid --platform value (expected gh or glab)')
   process.exit(1)
 }
-const positional = argv.filter((a, i) => !a.startsWith('--') && (pIx === -1 || i !== pIx + 1))
+
+// --upstream [owner/repo]: opt IN to the "file pattern-level problems against the
+// catalog" bullet in CLAUDE.md (off by default — the bullet names a specific repo and
+// tells agents to file issues there, which commercial/private adopters do not want, and
+// the repo slug should never land in a CLAUDE.md unasked; issue #40). Bare --upstream
+// targets the catalog this pattern came from; --upstream <repo> points elsewhere.
+const CATALOG_REPO = 'Ruihang2017/agent-templates'
+const uIx = argv.indexOf('--upstream')
+const UPSTREAM = uIx !== -1
+let UPSTREAM_REPO = CATALOG_REPO
+if (uIx !== -1 && argv[uIx + 1] && !argv[uIx + 1].startsWith('--')) UPSTREAM_REPO = argv[uIx + 1]
+
+// positional args = everything that isn't a flag or a flag's consumed value
+const consumed = new Set()
+for (const ix of [pIx, uIx]) {
+  if (ix !== -1 && argv[ix + 1] && !argv[ix + 1].startsWith('--')) consumed.add(ix + 1)
+}
+const positional = argv.filter((a, i) => !a.startsWith('--') && !consumed.has(i))
 const [pattern, targetArg] = positional
 if (!pattern || !targetArg) {
-  console.error('usage: node scripts/adopt.mjs <pattern-name> <target-dir> [--platform gh|glab] [--force]')
+  console.error('usage: node scripts/adopt.mjs <pattern-name> <target-dir> [--platform gh|glab] [--upstream [owner/repo]] [--force]')
   process.exit(1)
 }
 
@@ -72,7 +90,35 @@ if (!PLATFORM) {
   else if (/github/i.test(host)) { PLATFORM = 'gh'; console.log(`platform: gh (from origin host '${host}'; override with --platform)`) }
   else if (existsSync(join(target, '.gitlab-ci.yml'))) { PLATFORM = 'glab'; console.log(`platform: glab (from .gitlab-ci.yml${inconclusive}; override with --platform)`) }
   else if (existsSync(join(target, '.github'))) { PLATFORM = 'gh'; console.log(`platform: gh (from existing .github/${inconclusive}; override with --platform)`) }
-  else { PLATFORM = 'gh'; console.log(`platform: gh (default — ${host ? `could not classify origin host '${host}'` : 'no origin remote'}; pass --platform glab if this is a self-hosted GitLab)`) }
+  else {
+    // No signal: never guess — a wrong guess installs the wrong tracker config and a
+    // wrong Tracker line (issue #38). Ask when interactive; otherwise stop and install
+    // nothing so the agent/CI can re-run with an explicit --platform.
+    const reason = host ? `could not classify origin host '${host}'` : 'no git remote, and no .gitlab-ci.yml or .github/ to infer from'
+    if (process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout })
+      // Ctrl+D / closed stdin before an answer: abort cleanly (nothing installed)
+      // instead of leaving the top-level await unsettled.
+      rl.on('close', () => {
+        if (!PLATFORM) {
+          console.error('\nplatform: undetermined (input closed). Re-run with --platform gh|glab (nothing was installed).')
+          process.exit(1)
+        }
+      })
+      try {
+        console.log(`Cannot determine the tracker platform (${reason}).`)
+        for (;;) {
+          const a = (await rl.question('Which tracker is this repo on? [gh/glab] ')).trim().toLowerCase()
+          if (a === 'gh' || a === 'github') { PLATFORM = 'gh'; break }
+          if (a === 'glab' || a === 'gitlab') { PLATFORM = 'glab'; break }
+          console.log("please answer 'gh' or 'glab'")
+        }
+      } finally { rl.close() }
+    } else {
+      console.error(`platform: undetermined — ${reason}. Re-run with --platform gh|glab (nothing was installed).`)
+      process.exit(1)
+    }
+  }
 }
 if (PLATFORM !== 'gh' && PLATFORM !== 'glab') {
   console.error(`unknown platform: ${PLATFORM} (expected gh or glab)`)
@@ -167,8 +213,23 @@ if (existsSync(rootPrd) && !existsSync(docsPrd)) {
 // 6. CLAUDE.md: create from the snippet, or append it once (marker-checked, never duplicated).
 // The snippet defaults its Tracker line to `gh`; rewrite it to the resolved platform so the
 // pipeline reads the correct tracker from CLAUDE.md instead of re-guessing each run (issue #34).
-const snippet = readFileSync(join(scaffold, 'claude-md-snippet.md'), 'utf8')
+// Normalize CRLF up front: the marker/Tracker matching below needs literal \n, and a
+// catalog checkout under git autocrlf can carry \r\n — don't let that silently no-op the
+// strip and leak the block (same posture as copyFile; catalog issues #21/#23/#40).
+let snippet = readFileSync(join(scaffold, 'claude-md-snippet.md'), 'utf8')
+  .replace(/\r\n/g, '\n')
   .replace('**Tracker: `gh`**', `**Tracker: \`${PLATFORM}\`**`)
+// Upstream-escalation bullet is opt-in (issue #40): keep it only with --upstream (pointing
+// at the chosen catalog repo), otherwise strip the whole marked block so no catalog repo
+// slug or "file issues upstream" instruction lands in the adopted CLAUDE.md.
+const UP_RE = /\n<!-- upstream-escalation:start -->\n([\s\S]*?)\n<!-- upstream-escalation:end -->/
+if (UPSTREAM) {
+  snippet = snippet.replace(UP_RE, (_, bullet) => '\n' + bullet.split(CATALOG_REPO).join(UPSTREAM_REPO))
+  console.log(`upstream escalation: on (issues -> ${UPSTREAM_REPO})`)
+} else {
+  snippet = snippet.replace(UP_RE, '')
+  console.log('upstream escalation: off (enable with --upstream [owner/repo])')
+}
 const MARKER = '## Delivery pipeline — three-agent Architect / Builder / Reviewer'
 const claudeMd = join(target, 'CLAUDE.md')
 if (!existsSync(claudeMd)) {

package/scripts/build-site.mjs

@@ -24,6 +24,7 @@ const OUT = outIx !== -1 && argv[outIx + 1] ? argv[outIx + 1] : join(ROOT, 'site
 const GITHUB = 'https://github.com/Ruihang2017/agent-templates'
 const NPM = 'https://www.npmjs.com/package/agent-templates'
 const QUICKSTART = 'npx agent-templates@latest adopt three-agent-architect-builder-reviewer .'
+const UPDATE = QUICKSTART + ' --force'
 
 const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
 const strip = (s) => String(s).replace(/\*\*/g, '').replace(/`/g, '').trim()
@@ -243,6 +244,8 @@ const html = `<!doctype html>
   .quick{margin-top:20px;border-radius:16px;background:var(--pill);padding:14px 16px 12px;
     box-shadow:inset 0 3px 6px rgba(var(--flt),0.2),inset 0 -2px 2px rgba(255,255,255,0.8)}
   .quick code{display:block;font-family:var(--mono);font-size:12px;font-weight:700;color:var(--code);line-height:1.55;word-break:break-all}
+  .update-note{margin:12px 0 0;font-size:11.5px;font-weight:700;line-height:1.5;color:var(--hero-body)}
+  .update-note code{font-family:var(--mono);font-size:11px;color:var(--hero-title);word-break:break-all}
   .copy{display:inline-flex;margin-top:10px;padding:6px 16px;border-radius:13px;border:0;
     background:linear-gradient(180deg,#f9d66e,#f0c14a);cursor:pointer;font-family:'Nunito',sans-serif;
     font-size:12px;font-weight:900;color:#6b4a15;transition:transform .15s ease;
@@ -340,6 +343,7 @@ const html = `<!doctype html>
         <code id="qs">${esc(QUICKSTART)}</code>
         <button class="copy" id="copy-btn" type="button">Copy</button>
       </div>
+      <p class="update-note">Already installed? Update to the latest catalog version: <code>${esc(UPDATE)}</code> (commit first — <code>--force</code> overwrites).</p>
     </div>
     <div class="hero-side">
       ${FACTS.map(([tile, glyph, copy]) => `<div class="fact"><span class="fact-ico" style="${tile}">${glyph}</span><p>${copy}</p></div>`).join('\n      ')}