agent-templates 0.1.0

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/run-milestone.js

@@ -0,0 +1,223 @@
+export const meta = {
+  name: 'run-milestone',
+  description: 'Autonomous milestone runner: each ticket flows architect -> builder -> reviewer (bounce-capped in code) -> deliver',
+}
+
+// Deterministic orchestrator for the three-agent pattern. Control flow that used to be
+// prose ("max 2 bounces", "never merge without CLEAR") is enforced HERE, in code.
+//
+// args:
+// {
+//   tickets: [{ id: 'FND-01', path: 'docs/prd/01-foo/tickets/FND-01-x.md', issue: 12 }],
+//   mode: 'supervised' | 'autonomous',
+//   defaultBranch: 'main',        // optional, default 'main'
+//   maxBounces: 2,                // optional, default 2
+//   continueOnFailure: false,     // optional; default fail-fast (tickets may depend on earlier ones)
+//   platform: 'gh' | 'glab'       // tracker CLI for the deliver step, default 'gh'
+// }
+//
+// Guarantees encoded below (each one exists because prose alone failed before):
+// - reviewer prompts carry ONLY artifact refs (ticket path, computed plan path, branch name)
+// - a reviewer infrastructure failure never consumes the bounce budget or dispatches a fix
+// - nothing counts as delivered unless merged AND issueClosed AND dodPassed are all true
+// - supervised mode STOPS the run after each CLEAR (later tickets may depend on the merge);
+//   re-running /start-milestone continues — already-closed issues are filtered out upstream
+
+const cfg = Object.assign(
+  { maxBounces: 2, continueOnFailure: false, defaultBranch: 'main', platform: 'gh' },
+  args
+)
+if (!Array.isArray(cfg.tickets) || cfg.tickets.length === 0) {
+  throw new Error('args.tickets must be a non-empty array of {id, path, issue}')
+}
+for (const t of cfg.tickets) {
+  if (!t || typeof t.id !== 'string' || !t.id || typeof t.path !== 'string' || !t.path) {
+    throw new Error('every ticket needs a non-empty string id and path; got: ' + JSON.stringify(t))
+  }
+}
+if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
+  throw new Error("args.mode must be 'supervised' or 'autonomous'")
+}
+if (!Number.isInteger(cfg.maxBounces) || cfg.maxBounces < 0) {
+  throw new Error('args.maxBounces must be an integer >= 0')
+}
+if (typeof cfg.defaultBranch !== 'string' || !cfg.defaultBranch) throw new Error('args.defaultBranch must be a non-empty string')
+if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
+
+const PLAN = {
+  type: 'object',
+  properties: { planPath: { type: 'string' }, summary: { type: 'string' } },
+  required: ['planPath', 'summary'],
+}
+const BUILD = {
+  type: 'object',
+  properties: {
+    branch: { type: 'string' },
+    testsPassed: { type: 'boolean' },
+    testOutput: { type: 'string' },
+    deviations: { type: 'string' },
+  },
+  required: ['branch', 'testsPassed', 'testOutput'],
+}
+const VERDICT = {
+  type: 'object',
+  properties: {
+    verdict: { enum: ['CLEAR', 'BOUNCE'] },
+    checkedNote: { type: 'string' },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          file: { type: 'string' },
+          line: { type: 'integer' },
+          scenario: { type: 'string' },
+          severity: { enum: ['blocker', 'major', 'minor'] },
+        },
+        required: ['file', 'scenario', 'severity'],
+      },
+    },
+  },
+  required: ['verdict'],
+}
+const DELIVERY = {
+  type: 'object',
+  properties: {
+    merged: { type: 'boolean' },
+    issueClosed: { type: 'boolean' },
+    dodPassed: { type: 'boolean' },
+    notes: { type: 'string' },
+  },
+  required: ['merged', 'issueClosed', 'dodPassed'],
+}
+
+const normalizePath = function (p) {
+  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim()
+}
+
+const results = []
+let stopRun = false
+
+for (const t of cfg.tickets) {
+  if (stopRun) break
+  const P = 'T:' + t.id
+  const branch = 'ticket/' + t.id
+  const planPath = 'docs/plans/' + t.id + '.md' // computed in code; agent-returned paths are verified, never trusted
+
+  log('[' + t.id + '] architect: planning')
+  const plan = await agent(
+    'You are running as the Architect stage of the three-agent pattern. Ticket file: ' + t.path +
+    '. Produce the implementation plan per your role definition and write it to EXACTLY ' + planPath +
+    '. Return planPath (must be ' + planPath + ') and a one-paragraph summary.',
+    { agentType: 'architect', label: 'plan:' + t.id, phase: P, schema: PLAN }
+  )
+  if (!plan || normalizePath(plan.planPath) !== planPath) {
+    results.push({ id: t.id, status: 'failed', stage: 'architect', detail: plan ? 'plan written to unexpected path: ' + plan.planPath : 'architect agent returned nothing' })
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+
+  log('[' + t.id + '] builder: implementing on ' + branch)
+  let build = await agent(
+    'Builder stage. Ticket: ' + t.path + '. Plan: ' + planPath + '. Create branch ' + branch +
+    ' from ' + cfg.defaultBranch + ', implement the plan there, commit, run the tests. Do NOT merge and do NOT touch the tracker. ' +
+    'Return branch (must be ' + branch + '), testsPassed, testOutput (paste real output), deviations.',
+    { agentType: 'builder', label: 'build:' + t.id, phase: P, schema: BUILD }
+  )
+  const buildBad = function (b) { return !b || !b.testsPassed || String(b.branch).trim() !== branch }
+  if (buildBad(build)) {
+    results.push({
+      id: t.id, status: 'failed', stage: 'builder',
+      detail: !build ? 'builder agent returned nothing' : (String(build.branch).trim() !== branch ? 'worked on wrong branch: ' + build.branch : build.testOutput),
+    })
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+
+  // Review loop — the bounce cap lives here, in code, not in prose.
+  const reviewOnce = function (tag) {
+    return agent(
+      'Reviewer stage. Inputs (artifact refs only): ticket ' + t.path + ', plan ' + planPath +
+      ', diff = branch ' + branch + ' vs ' + cfg.defaultBranch + '. Review per your role definition; ' +
+      'run the tests yourself — no test results are provided on purpose. Return verdict CLEAR or BOUNCE with findings ' +
+      '(a BOUNCE with zero findings is invalid).',
+      { agentType: 'reviewer', label: 'review:' + t.id + '#' + tag, phase: P, schema: VERDICT }
+    )
+  }
+  // A null/invalid reviewer result is an infrastructure failure, not a code finding:
+  // retry once (not counted against the bounce budget), then escalate — never sent to the builder.
+  const reviewValid = function (v) {
+    if (!v) return false
+    if (v.verdict === 'BOUNCE' && (!v.findings || v.findings.length === 0)) return false
+    return true
+  }
+
+  let bounces = 0
+  let verdict = await reviewOnce('0')
+  if (!reviewValid(verdict)) { log('[' + t.id + '] reviewer returned no usable verdict — retrying once'); verdict = await reviewOnce('0-retry') }
+  let reviewerBroken = !reviewValid(verdict)
+  let fixBroken = false
+
+  while (!reviewerBroken && verdict.verdict === 'BOUNCE' && bounces < cfg.maxBounces) {
+    bounces += 1
+    log('[' + t.id + '] bounce ' + bounces + '/' + cfg.maxBounces + ': back to builder with ' + verdict.findings.length + ' finding(s)')
+    build = await agent(
+      'Builder stage, bounce fix. Ticket: ' + t.path + '. Plan: ' + planPath + '. Stay on branch ' + branch +
+      ' — do NOT merge and do NOT touch the tracker. Reviewer findings — address ALL of them and add regression tests: ' +
+      JSON.stringify(verdict.findings) + '. Run the tests. Return branch (must be ' + branch + '), testsPassed, testOutput, deviations.',
+      { agentType: 'builder', label: 'fix:' + t.id + '#' + bounces, phase: P, schema: BUILD }
+    )
+    if (buildBad(build)) { fixBroken = true; break }
+    verdict = await reviewOnce(String(bounces))
+    if (!reviewValid(verdict)) { log('[' + t.id + '] reviewer returned no usable verdict — retrying once'); verdict = await reviewOnce(bounces + '-retry') }
+    reviewerBroken = !reviewValid(verdict)
+  }
+
+  if (reviewerBroken || fixBroken || verdict.verdict !== 'CLEAR') {
+    const stage = reviewerBroken ? 'reviewer-failed' : (fixBroken ? 'bounce-fix-build' : 'review')
+    results.push({
+      id: t.id, status: 'escalated', stage: stage, bounces: bounces,
+      findings: reviewValid(verdict) ? (verdict.findings || []) : [],
+      detail: fixBroken ? (!build ? 'fix builder returned nothing' : (String(build.branch).trim() !== branch ? 'fix worked on wrong branch: ' + build.branch : build.testOutput)) : (reviewerBroken ? 'reviewer produced no usable verdict after one retry' : 'bounce cap exhausted'),
+    })
+    log('[' + t.id + '] escalated to a human (stage: ' + stage + ', after ' + bounces + ' bounce(s))')
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+
+  if (cfg.mode === 'supervised') {
+    results.push({ id: t.id, status: 'awaiting-human-merge', branch: branch, bounces: bounces, note: verdict.checkedNote || '' })
+    log('[' + t.id + '] CLEAR — supervised mode: stopping the run for the human merge. Re-run /start-milestone after merging (closed issues are skipped).')
+    stopRun = true
+    continue
+  }
+
+  log('[' + t.id + '] deliver: merge + close issue + DoD')
+  const delivery = await agent(
+    'Delivery step (autonomous mode — pre-authorized by the human Gate 1 start signal). ' +
+    'Merge branch ' + branch + ' into ' + cfg.defaultBranch + ' with --no-ff and push. ' +
+    'Close tracker issue ' + (t.issue ? '#' + t.issue : 'for ticket ' + t.id + ' (find it by its "[' + t.id + ']" title prefix)') +
+    ' via ' + cfg.platform + ' and verify it is ACTUALLY closed afterwards. ' +
+    'Then run the Definition-of-Done checks from .claude/commands/verify-delivery.md for ticket ' + t.id +
+    ' (plan exists; tests green on the merged ' + cfg.defaultBranch + ' — run them yourself; CLEAR verdict recorded; merged to ' + cfg.defaultBranch + '; issue closed; writeback done). ' +
+    'Never report an item you did not check. Return merged, issueClosed, dodPassed, notes.',
+    { label: 'deliver:' + t.id, phase: P, schema: DELIVERY }
+  )
+  // Delivered requires ALL THREE flags — a hallucinated dodPassed alone must not count.
+  if (!delivery || !(delivery.merged && delivery.issueClosed && delivery.dodPassed)) {
+    const missing = !delivery ? 'delivery agent returned nothing' : ['merged', 'issueClosed', 'dodPassed'].filter(function (k) { return !delivery[k] }).join(', ') + ' = false'
+    results.push({ id: t.id, status: 'delivery-incomplete', detail: missing + (delivery && delivery.notes ? ' — ' + delivery.notes : '') })
+    if (!cfg.continueOnFailure) break
+    continue
+  }
+  results.push({ id: t.id, status: 'delivered', bounces: bounces })
+}
+
+const throughPipeline = results.filter(function (r) { return r.status === 'delivered' || r.status === 'awaiting-human-merge' }).length
+log('milestone run finished: ' + throughPipeline + '/' + cfg.tickets.length + ' tickets through the pipeline')
+
+return {
+  mode: cfg.mode,
+  results: results,
+  notStarted: cfg.tickets.length - results.length, // > 0 means the run stopped early (fail-fast or supervised pause)
+}

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

@@ -0,0 +1,65 @@
+# Installing the three-agent scaffold
+
+Source pattern: `agent-templates/patterns/three-agent-architect-builder-reviewer` — read its [README](../README.md) (especially the expiry trigger) before installing.
+
+## Quickstart
+
+From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-builder-reviewer <target-dir>` performs steps 1–6 below mechanically (idempotent; `--platform gh|glab`), then prints the next steps. Full walkthrough incl. the bare-PRD.md scenario: the catalog's [ADOPTING.md](../../../ADOPTING.md). The manual steps:
+
+## Steps
+
+1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry instead of overwriting.
+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`, the deliver stage, `/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).
+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).
+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.
+
+## Usage modes
+
+- **Mode A — one orchestrator session (default):** run `/plan-ticket` → `/build-ticket` → `/review-ticket` → `/verify-delivery` from a single main session. Each stage executes in its own subagent, so stage contexts stay isolated. The orchestrator passes only artifacts between stages — ticket path, plan path, diff ref — never transcripts or agent self-assessments, and it never does stage work itself (see "Orchestrator discipline" in `claude-md-snippet.md`; role leakage is a recorded failure mode).
+- **Mode B — three human-run sessions:** open a fresh Claude Code session per stage. Strongest isolation; use when the orchestrator session itself has grown long or has seen implementation detail.
+- **Milestone mode (the target operating model):** `/start-milestone <module> [supervised|autonomous]` — Gate 1 in one action: verify inputs, publish tickets as issues, then run all tickets through `.claude/workflows/run-milestone.js`. Each stage still runs in its own subagent; ordering, the bounce cap, and merge policy are code, not prompts. The human returns at Gate 2 (smoke test) or on escalation.
+
+## Nightly sweep (unattended)
+
+- **Entry:** `claude -p "/nightly-issues"` — slash commands expand in headless `-p` mode. `[official]`
+- **Permissions:** pre-approve exactly what the pipeline needs in the target repo's `.claude/settings.json` (`permissions.allow`, e.g. `Bash(git:*)`, `Bash(gh:*)` or `Bash(glab:*)`, `Bash(node:*)`, `Bash(npm:*)`), then run with `--permission-mode dontAsk` — the documented CI recommendation: pre-approved tools run, everything else is auto-denied instead of blocking. Subagents run in `acceptEdits` mode (their file edits are auto-approved). Avoid `bypassPermissions` outside isolated containers (documented warning). `[official]`
+- **Scheduling (Windows, primary):** Task Scheduler — runs whenever the machine is on at the trigger time:
+
+  ```
+  schtasks /create /tn "nightly-issues" /sc daily /st 02:00 ^
+    /tr "cmd /c cd /d C:\path\to\repo && claude -p \"/nightly-issues\" --permission-mode dontAsk >> .claude\nightly.log 2>&1"
+  ```
+
+  macOS/Linux: launchd / cron equivalents.
+- **Why not Claude Code's native cron** (`/loop`, Cron tools): documented constraints — the session must stay open, recurring tasks expire after 7 days, and firings jitter up to 30 minutes — the wrong shape for "machine on, no session open". For no-local-machine automation the docs point to Routines (Anthropic infrastructure) or CI schedules. `[official]`
+- **Morning email:** watch the repo / enable tracker notifications. The sweep posts per-issue outcome comments, labels (`triage:invalid` = flagged invalid, never auto-closed · `nightly:escalated` = won't retry until a human clears it · `needs-human`), closes delivered issues, and files a `Nightly report YYYY-MM-DD` issue — the tracker's own notification email is the delivery mechanism, no SMTP to configure.
+
+## Config-key verification record
+
+`model:` and `effort:` in `.claude/agents/*.md`, and command frontmatter (`description`, `argument-hint`, `$ARGUMENTS`/`$N` substitution), verified against the official Claude Code docs on **2026-07-17**:
+
+- <https://code.claude.com/docs/en/sub-agents.md> — agent frontmatter keys incl. `model` (full IDs and aliases; omitted = inherit) and `effort` (`low`/`medium`/`high`/`xhigh`/`max`); omitted `tools` inherits all tools.
+- <https://code.claude.com/docs/en/skills.md> — command/skill frontmatter incl. `model`, `effort`, `argument-hint`; argument substitution via `$ARGUMENTS` and `$N` (0-based).
+- <https://code.claude.com/docs/en/model-config.md> — effort levels incl. `max`; note the `effortLevel` *setting* accepts `low`–`xhigh` only (`max` is session-only), while agent/command frontmatter `effort` accepts `max`.
+
+Hook mechanism (the main-session write guard), verified **2026-07-17**:
+
+- <https://code.claude.com/docs/en/hooks.md> — PreToolUse settings schema (regex `matcher`, `type: command`); hooks fire for subagent tool calls too; the hook input carries `agent_id`/`agent_type` **only** when the call comes from a subagent, so their absence identifies the main session; deny via stdout JSON `hookSpecificOutput.permissionDecision: "deny"` (the reason string is fed back to the model), or exit code 2.
+- <https://code.claude.com/docs/en/permissions.md> — `permissions.deny` rules apply to subagents as well (subagents inherit the parent's permission stack); **no documented main-session-only permission scope exists**, which is why the guard is a hook rather than a deny rule.
+
+Workflow tool + `ultracode` (for the milestone runner), verified **2026-07-17**:
+
+- <https://code.claude.com/docs/en/workflows> — the Workflow tool (deterministic multi-agent scripts: `export const meta`, `agent()` / `parallel()` / `pipeline()`) is publicly documented; `.claude/workflows/` is the documented project location for saved workflow scripts (also <https://code.claude.com/docs/en/claude-directory>).
+- <https://code.claude.com/docs/en/model-config> — "Ultracode is a Claude Code setting rather than a model effort level": it applies `xhigh` effort plus automatic workflow orchestration. Persistable effort levels are `low`–`xhigh`; `max` and `ultracode` are session-only.
+
+Headless + scheduling facts (for the nightly sweep), verified **2026-07-17**:
+
+- <https://code.claude.com/docs/en/headless.md> — `claude -p "<prompt>"`; slash commands expand in `-p`; `--output-format`, `--max-turns`.
+- <https://code.claude.com/docs/en/permission-modes.md> and <https://code.claude.com/docs/en/permissions.md> — `--permission-mode dontAsk` is the documented CI recommendation (pre-approved tools only, rest auto-denied); `acceptEdits`; `bypassPermissions` only for isolated environments; `--allowedTools`; settings `permissions.allow`; subagents run in `acceptEdits`.
+- <https://code.claude.com/docs/en/workflows.md> — workflows are available in headless `claude -p`.
+- <https://code.claude.com/docs/en/scheduled-tasks.md> and <https://code.claude.com/docs/en/routines.md> — native `/loop`/Cron tools require an open session, recurring tasks expire after 7 days, jitter up to 30 min; Routines run on Anthropic infrastructure.
+
+Re-verify these keys when Claude Code major-versions, or when this record is more than 6 months old.

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

@@ -0,0 +1,37 @@
+<!-- Append this block to the target repo's CLAUDE.md.
+     Source pattern: agent-templates/patterns/three-agent-architect-builder-reviewer (as of 2026-07-17). -->
+
+## Delivery pipeline — three-agent Architect / Builder / Reviewer
+
+**Operating mode: `supervised`** <!-- switch to `autonomous` once the pattern holds on this repo -->
+
+- `supervised` — a human confirms each merge and each tracker close; issue **creation** is authorized by the `/start-milestone` sign-off itself. The milestone runner stops after each CLEAR verdict for the human merge — re-run `/start-milestone` to continue (closed issues are skipped). Use for a fresh adoption.
+- `autonomous` (target) — humans decide at exactly two gates: Gate 1, sign-off of master PRD → sub-PRDs → tickets before the pipeline starts; Gate 2, a smoke test of the delivered milestone. Between them the pipeline self-drives: merge on CLEAR, `/verify-delivery` repairs gaps (including closing the issue) automatically. A human is pulled in only on the exception path — 2 bounce cycles without convergence, a failed build, or an unrepairable verify-delivery item.
+
+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.
+- **`/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.
+- **`/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).
+- **`/nightly-issues [max]`** — unattended sweep (OS-scheduled, `claude -p`): triage open issues → auto-fix fixable ones through the pipeline → per-issue comments + labels + a `Nightly report <date>` issue for the morning read. Invalid issues are labeled `triage:invalid`, never auto-closed. Setup: scaffold INSTALL.md § Nightly sweep.
+
+Orchestrator discipline (hard rules for the main session):
+
+- The main session **orchestrates only**: it invokes the stage commands and relays artifacts (ticket path, plan path, diff ref). It never plans, implements, or reviews a ticket inline — that work belongs to the stage subagents, whatever the size of the change.
+- If a stage subagent fails or is unavailable, report the failure and stop. **Never absorb its role.**
+- This is **mechanically enforced**: a PreToolUse guard (`.claude/hooks/guard-main-session-writes.mjs`) denies Edit/Write in the main session; subagent calls pass. For a human-approved out-of-pipeline edit, create `.claude/allow-main-writes` (git-ignored) and delete it afterwards.
+- Known guard boundary: Bash is not covered. Bash in the main session is for orchestration only (git, tracker CLI, running commands) — never for writing files (`echo >`, `git apply`, heredocs). The guard stops reflexive edits, not determined bypasses; this rule covers the rest.
+- A ticket is done only when `/verify-delivery` passes all items — "the MR is merged" is not done (known failure: MRs merged with issues left open, observed 2026-07-17).
+
+Rules:
+
+- The Reviewer never runs in the Builder's session and never edits code; it receives only the ticket, the plan, and the diff ref — never transcripts.
+- Maximum 2 bounce cycles, then escalate to a human.
+- 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.
+- **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.

package/scripts/adopt.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// adopt.mjs — one-command pattern installer for new and existing projects.
+//
+// Usage (run from a checkout of the agent-templates catalog):
+//   node scripts/adopt.mjs <pattern-name> <target-dir> [--platform gh|glab] [--force]
+//
+// Installs into <target-dir>:
+//   .claude/                 from the pattern's scaffold (per-file; existing files skipped)
+//   templates/ticket.template.md   the universal ticket format
+//   .github/ or .gitlab/     universal tracker templates (issues + PR/MR) for the platform
+//   docs/PRD.md              copied from a root PRD.md if present and docs/PRD.md is absent
+//   docs/prd/ docs/adr/ docs/plans/   the docs skeleton the pipeline assumes
+//   CLAUDE.md                created from the snippet, or snippet appended once (marker-checked)
+//
+// Idempotent: re-running skips everything that exists (--force overwrites files, never
+// re-appends the snippet). Exit 0 = installed/verified; exit 1 = bad invocation.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CATALOG = fileURLToPath(new URL('..', import.meta.url))
+const argv = process.argv.slice(2)
+const FORCE = argv.includes('--force')
+
+const pIx = argv.indexOf('--platform')
+let PLATFORM = pIx !== -1 ? argv[pIx + 1] || '' : ''
+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))
+const [pattern, targetArg] = positional
+if (!pattern || !targetArg) {
+  console.error('usage: node scripts/adopt.mjs <pattern-name> <target-dir> [--platform gh|glab] [--force]')
+  process.exit(1)
+}
+
+const scaffold = join(CATALOG, 'patterns', pattern, 'scaffold')
+if (!existsSync(scaffold)) {
+  const available = existsSync(join(CATALOG, 'patterns'))
+    ? readdirSync(join(CATALOG, 'patterns')).filter((d) => existsSync(join(CATALOG, 'patterns', d, 'scaffold')))
+    : []
+  console.error(`unknown pattern: ${pattern}\navailable: ${available.join(', ') || '(none)'}`)
+  process.exit(1)
+}
+const target = resolve(targetArg)
+let targetOk = false
+try { targetOk = statSync(target).isDirectory() } catch {}
+if (!targetOk) {
+  console.error(`target is not a directory: ${target}`)
+  process.exit(1)
+}
+
+if (!PLATFORM) {
+  try {
+    const origin = execFileSync('git', ['-C', target, 'remote', 'get-url', 'origin'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    const host = (origin.match(/(?:@|:\/\/)([^/:]+)[/:]/) || [])[1] || ''
+    PLATFORM = host.includes('gitlab') ? 'glab' : 'gh'
+    console.log(`platform: ${PLATFORM} (autodetected from ${host || origin}; override with --platform)`)
+  } catch {
+    PLATFORM = 'gh'
+    console.log('platform: gh (no origin remote detected; override with --platform glab)')
+  }
+}
+if (PLATFORM !== 'gh' && PLATFORM !== 'glab') {
+  console.error(`unknown platform: ${PLATFORM} (expected gh or glab)`)
+  process.exit(1)
+}
+
+let installed = 0
+let skipped = 0
+const note = (line) => console.log(line)
+
+function* walk(dir) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const f = join(dir, e.name)
+    if (e.isDirectory()) yield* walk(f)
+    else yield f
+  }
+}
+
+const copyFile = (src, dst, label) => {
+  if (existsSync(dst) && !FORCE) {
+    console.log(`= exists  ${label}`)
+    skipped++
+    return false
+  }
+  mkdirSync(dirname(dst), { recursive: true })
+  cpSync(src, dst)
+  console.log(`+ install ${label}`)
+  installed++
+  return true
+}
+
+// 1. scaffold .claude/ (per-file so re-runs skip; settings.json conflicts get a manual-merge note)
+for (const src of walk(join(scaffold, '.claude'))) {
+  const rel = relative(scaffold, src).replaceAll('\\', '/')
+  const dst = join(target, rel)
+  const existed = existsSync(dst)
+  copyFile(src, dst, rel)
+  if (existed && !FORCE && rel === '.claude/settings.json') {
+    note('  (note) existing .claude/settings.json kept — merge the hooks.PreToolUse entry and permissions.allow from the scaffold manually')
+  }
+}
+
+// 2. universal ticket template
+copyFile(join(CATALOG, 'templates', 'ticket.template.md'), join(target, 'templates', 'ticket.template.md'), 'templates/ticket.template.md')
+
+// 3. platform tracker templates (issues + PR/MR)
+const trackerSrc = join(CATALOG, 'templates', 'tracker', PLATFORM === 'gh' ? 'github' : 'gitlab')
+const trackerDstRoot = join(target, PLATFORM === 'gh' ? '.github' : '.gitlab')
+for (const src of walk(trackerSrc)) {
+  const rel = relative(trackerSrc, src).replaceAll('\\', '/')
+  copyFile(src, join(trackerDstRoot, rel), `${PLATFORM === 'gh' ? '.github' : '.gitlab'}/${rel}`)
+}
+
+// 4. docs skeleton
+for (const d of ['docs/prd', 'docs/adr', 'docs/plans']) {
+  const dir = join(target, d)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, '.gitkeep'), '')
+    console.log(`+ mkdir   ${d}/`)
+    installed++
+  } else {
+    console.log(`= exists  ${d}/`)
+    skipped++
+  }
+}
+
+// 5. root PRD.md -> docs/PRD.md (copy, never move — the pipeline reads docs/PRD.md)
+const rootPrd = join(target, 'PRD.md')
+const docsPrd = join(target, 'docs', 'PRD.md')
+if (existsSync(rootPrd) && !existsSync(docsPrd)) {
+  cpSync(rootPrd, docsPrd)
+  console.log('+ install docs/PRD.md (copied from root PRD.md — the pipeline reads docs/PRD.md; delete the root copy when ready)')
+  installed++
+} else if (existsSync(docsPrd)) {
+  console.log('= exists  docs/PRD.md')
+  skipped++
+} else {
+  note('  (note) no PRD.md found — write docs/PRD.md before running /breakdown-prd')
+}
+
+// 6. CLAUDE.md: create from the snippet, or append it once (marker-checked, never duplicated)
+const snippet = readFileSync(join(scaffold, 'claude-md-snippet.md'), 'utf8')
+const MARKER = '## Delivery pipeline — three-agent Architect / Builder / Reviewer'
+const claudeMd = join(target, 'CLAUDE.md')
+if (!existsSync(claudeMd)) {
+  const header = `# ${basename(target)} — Project Constitution\n\n> Auto-loaded into every session. Installed by agent-templates adopt.mjs on ${new Date().toISOString().slice(0, 10)}.\n> Add your project facts and non-negotiable constraints above the pipeline section.\n\n`
+  writeFileSync(claudeMd, header + snippet)
+  console.log('+ install CLAUDE.md (seeded from the pattern snippet)')
+  installed++
+} else if (!readFileSync(claudeMd, 'utf8').includes(MARKER)) {
+  writeFileSync(claudeMd, readFileSync(claudeMd, 'utf8').trimEnd() + '\n\n' + snippet)
+  console.log('+ append  CLAUDE.md (pipeline snippet appended)')
+  installed++
+} else {
+  console.log('= exists  CLAUDE.md (pipeline snippet already present)')
+  skipped++
+}
+
+console.log(`\nadopt: ${installed} installed, ${skipped} already present. Pattern: ${pattern}, platform: ${PLATFORM}.`)
+console.log(`
+NEXT STEPS (details: ${join(CATALOG, 'ADOPTING.md')})
+  1. Review CLAUDE.md — set the Operating mode line (start: supervised) and add your
+     project facts; fill the Constraint check section of the PR/MR template.
+  2. Tracker: git remote + authenticated CLI (${PLATFORM} auth login). Node >= 18 on PATH.
+  3. In Claude Code, in the target repo:  /breakdown-prd
+     (Architect decomposes docs/PRD.md into sub-PRDs + tickets, then stops for your review)
+  4. Gate 1 — review the breakdown, then:  /start-milestone docs/prd/00-<module> supervised
+  5. Graduate to autonomous when the pattern holds; optional nightly sweep:
+     see the pattern's INSTALL.md § Nightly sweep.`)