agent-templates 0.1.0 → 0.2.1

package/ADOPTING.md

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

package/CLAUDE.md

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

package/LICENSE

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

package/README.md

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

package/package.json

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