agent-templates 0.4.3 → 0.4.5

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
 

package/package.json

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

@@ -154,6 +154,8 @@ 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-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/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

@@ -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)) {