agent-templates 0.4.8 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-templates",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "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-21 (model/effort revised; §7) |
-| **Expiry trigger** | First successor release to any listed model, or 2027-01-21 (+6 months), whichever comes first |
+| **As-of date** | 2026-07-22 (Architect model on trial; §7) |
+| **Expiry trigger** | First successor release to any listed model, or 2027-01-22 (+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-21)
+## 3. Model + effort assignment (as of 2026-07-22)
 
 | Role | Model | Effort | Reasoning | Source labels |
 |---|---|---|---|---|
-| 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]` |
+| Architect | Claude Fable 5 | `max` | **On trial (2026-07-22).** The plan is the cold-start contract, and the Reviewer checks the implementation *against* the plan — it does not judge whether the plan was the right plan. So an internally-consistent but under-specified plan passes review silently and surfaces later as drift; planning strength has value review cannot backstop. This trials at that stage the model the Reviewer row cites — on `[unverified]` data — as having the largest capability margin. Accepted cost (see §4): Architect and Reviewer now share a model, so the Reviewer is blinder to plan-level defects — materially weaker than a Reviewer/Builder collapse, but not free. Judge on real bounce rate and observed drift; revert or re-pin on evidence. | `[team-policy]` — maintainer trial, 2026-07-22. **No benchmark basis claimed**: there is no verified evidence on record that Fable 5 outperforms Opus 4.8 at planning (§3's Fable figure is itself `[unverified]`) |
 | 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 | `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) |
+| 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 Architect pinned to a top-tier model at `max` 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 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).
+Figures dated 2026-07-17 are from the team-finalized specification (§7); the Reviewer row was revised 2026-07-21 and the Architect row 2026-07-22 (§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
 
@@ -70,6 +70,7 @@ Figures dated 2026-07-17 are from the team-finalized specification (§7); the Ar
 | **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 |
 | **Intra-module tickets dispatched out of dependency order** — `milestone-dag.mjs` emitted each module's tickets in ID (filename) order, not topologically by their own `blocked_by` edges; when a module's declared order deviates from ID order, run-milestone dispatched a ticket before the sibling it is blocked_by, the Builder stopped at its plan's precondition gate, and the whole module failed (chain-blocking its dependents) | `[internal]` — Ruihang2017/Groundwork2, autonomous `/start-all`, 2026-07-18 (catalog issue #31; module `05-jobs-fit`, `0502 blocked_by 0503` but ID order put 0502 first) | Fixed 2026-07-19: `milestone-dag.mjs` topologically sorts tickets within each module by intra-module `blocked_by` (cross-module edges stay module-level; ID order only as tiebreak), with an intra-module cycle failing loudly like the module-level one. Same Kahn sort now serves both levels. | 2026-07-19 |
+| **Architect and Reviewer share a model** (both Fable 5 since the 2026-07-22 trial) — the Reviewer is blinder to "the plan itself was wrong" than when the two differed, because it shares the planner's blind spots about the plan | Accepted design cost of the Architect trial (catalog issue #48), 2026-07-22 — not an observed incident | Materially weaker than a Reviewer/Builder tier collapse: the judge is still a different model from the *implementer*, which is the constraint §2 makes hard. Watch for plan-level defects reaching merge (wrong-thing-built rather than built-wrong); if they appear, split the two models again — that evidence ends the trial | 2026-07-22 |
 | **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
@@ -120,7 +121,7 @@ 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-opus-4-8 @ max; writes the plan, no production code
+    │   ├── architect.md       # claude-fable-5 @ max; writes the plan, no production code
     │   ├── builder.md         # claude-opus-4-8 @ xhigh; inherits all tools
     │   ├── reviewer.md        # claude-fable-5 @ xhigh; read/run-only (no Write/Edit)
     │   └── triage.md          # claude-sonnet-5 @ xhigh; nightly classification + ticket synthesis
@@ -154,6 +155,7 @@ 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-22 | **Architect model on trial** (catalog issue #48, maintainer decision): Architect `claude-opus-4-8 @ max` → `claude-fable-5 @ max`; Builder and Reviewer unchanged. Rationale: the Reviewer checks the implementation against the plan, not whether the plan was right, so an under-specified-but-consistent plan passes review silently — planning strength has value review cannot backstop. The maintainer's original proposal also moved the Reviewer to Opus 4.8; that was **rejected** as the §4 tier-collapse failure mode (Builder is Opus 4.8, and §2 makes different-tier-from-the-Builder a hard requirement), so only the Architect changed. Accepted cost recorded as a new §4 row: Architect and Reviewer now share a model. Explicitly a **trial** — no benchmark basis claimed (no verified Fable-5-vs-Opus-4.8 planning evidence exists on record); judge on real bounce rate and drift, revert or re-pin on evidence. Same commit: §3 row + §3 as-of, metadata As-of/expiry, scaffold-tree pin, snippet, integrity pins, §4, self-host re-sync. | Maintainer decision (Horace Hou), 2026-07-22. | Horace Hou (decision) / 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) |

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

@@ -12,7 +12,7 @@
 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-opus-4-8` @ `max`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
+- **`/plan-ticket <ticket>`** — Architect (`claude-fable-5` @ `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` @ `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.