agent-templates 0.1.0

package/scripts/build-site.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// build-site.mjs — generates the catalog's GitHub Pages site from the catalog's own
+// data (patterns/*/README.md + package.json). Never hand-edit the output: the page
+// must not be able to drift from the pattern metadata.
+//
+// Usage: node scripts/build-site.mjs [--out <dir>]     (default: site/)
+// Output: <out>/index.html (self-contained) + <out>/.nojekyll
+//
+// Style: claymorphism per catalog issue #17 — cream background, pastel clay palette,
+// puffy cards, soft extruded shadows, rounded chunky type, emoji as clay icons.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = fileURLToPath(new URL('..', import.meta.url))
+const argv = process.argv.slice(2)
+const outIx = argv.indexOf('--out')
+const OUT = outIx !== -1 && argv[outIx + 1] ? argv[outIx + 1] : join(ROOT, 'site')
+
+const GITHUB = 'https://github.com/Ruihang2017/agent-templates'
+const NPM = 'https://www.npmjs.com/package/agent-templates'
+const QUICKSTART = 'npx agent-templates@latest adopt three-agent-architect-builder-reviewer .'
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+const strip = (s) => String(s).replace(/\*\*/g, '').replace(/`/g, '').trim()
+
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+
+function parsePattern(dir) {
+  const path = join(ROOT, 'patterns', dir, 'README.md')
+  if (!existsSync(path)) return null
+  const md = readFileSync(path, 'utf8')
+  const pick = (re) => (md.match(re) || [])[1] || ''
+
+  const title = strip(pick(/^# Pattern: (.+)$/m)) || dir
+  const statusRaw = strip(pick(/\|\s*\*\*Status\*\*\s*\|\s*([^|]+)\|/))
+  const status = (statusRaw.match(/[a-z]+/) || ['proposed'])[0]
+  const asOf = strip(pick(/\|\s*\*\*As-of date\*\*\s*\|\s*([^|]+)\|/))
+
+  // the one-line topology summary: first plain paragraph after the metadata table
+  let summary = ''
+  const lines = md.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i].trim()
+    if (!l || l.startsWith('#') || l.startsWith('|') || l.startsWith('<!--')) continue
+    summary = strip(l)
+    break
+  }
+
+  // model/effort rows from §3
+  const roles = []
+  const sec3 = md.split(/^## 3\. Model \+ effort[^\n]*$/m)[1]
+  if (sec3) {
+    for (const row of sec3.split(/^## /m)[0].split('\n')) {
+      const m = row.match(/^\|\s*([A-Z][^|]*?)\s*\|\s*([^|]+?)\s*\|\s*`([^`]+)`\s*\|/)
+      if (m && !/^Role/.test(m[1])) roles.push({ role: strip(m[1]), model: strip(m[2]), effort: m[3] })
+    }
+  }
+
+  // first three "Use when" bullets from §1
+  const useWhen = []
+  const sec1 = md.split(/\*\*Use when:\*\*/)[1]
+  if (sec1) {
+    for (const l of sec1.split(/\*\*Do not use when:\*\*/)[0].split('\n')) {
+      const m = l.match(/^- (.+)$/)
+      if (m && useWhen.length < 3) useWhen.push(strip(m[1]))
+    }
+  }
+
+  return { dir, title, status, asOf, summary, roles, useWhen }
+}
+
+const patterns = readdirSync(join(ROOT, 'patterns'), { withFileTypes: true })
+  .filter((d) => d.isDirectory() && existsSync(join(ROOT, 'patterns', d.name, 'scaffold')))
+  .map((d) => parsePattern(d.name))
+  .filter(Boolean)
+
+const STATUS_STYLE = {
+  proposed: ['var(--blue)', 'var(--blue-d)', '🧪'],
+  trialed: ['var(--butter)', 'var(--butter-d)', '🌱'],
+  adopted: ['var(--sage)', 'var(--sage-d)', '✅'],
+  deprecated: ['var(--pink)', 'var(--pink-d)', '🗄️'],
+}
+const ROLE_EMOJI = { Architect: '📐', Builder: '🔨', Reviewer: '🔍' }
+const roleEmoji = (r) => ROLE_EMOJI[Object.keys(ROLE_EMOJI).find((k) => r.startsWith(k))] || '🌙'
+
+const patternCards = patterns
+  .map((p) => {
+    const [bg, fg, ico] = STATUS_STYLE[p.status] || STATUS_STYLE.proposed
+    return `
+      <article class="card pattern">
+        <div class="pattern-head">
+          <h3>${esc(p.title)}</h3>
+          <span class="pill status" style="background:${bg};color:${fg}">${ico} ${esc(p.status)} · as of ${esc(p.asOf)}</span>
+        </div>
+        <p class="summary">${esc(p.summary)}</p>
+        <div class="roles">
+          ${p.roles.map((r) => `<span class="pill role">${roleEmoji(r.role)} <b>${esc(r.role)}</b>&nbsp;· ${esc(r.model)} <code>@${esc(r.effort)}</code></span>`).join('\n          ')}
+        </div>
+        ${p.useWhen.length ? `<ul class="usewhen">${p.useWhen.map((u) => `<li>${esc(u)}</li>`).join('')}</ul>` : ''}
+        <div class="links">
+          <a class="btn small sage" href="${GITHUB}/tree/main/patterns/${esc(p.dir)}">📖 Pattern write-up</a>
+          <a class="btn small lav" href="${GITHUB}/tree/main/patterns/${esc(p.dir)}/scaffold">🧰 Scaffold</a>
+        </div>
+      </article>`
+  })
+  .join('\n')
+
+const STEPS = [
+  ['📦', 'Adopt', `<code>${esc(QUICKSTART)}</code> — scaffold, templates, docs skeleton, CLAUDE.md, in one idempotent command.`],
+  ['🗺️', 'Break down', '<code>/breakdown-prd</code> — the Architect turns your PRD into sub-PRDs and cold-startable tickets, then stops.'],
+  ['🚦', 'Gate 1 — you decide', 'Review the breakdown, then <code>/start-milestone</code>: tickets become tracker issues and the pipeline starts.'],
+  ['🤖', 'Autonomous middle', 'Plan → build → fresh-context review (bounce-capped in code) → merge on CLEAR → issue closed → delivery verified.'],
+  ['🔎', 'Gate 2 — smoke test', 'Agents own unit/integration/E2E all along; you test once, when the PRD is done. A nightly sweep fixes issues while you sleep.'],
+]
+
+const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>agent-templates — multi-agent patterns, ready to drop in</title>
+<meta name="description" content="A catalog of multi-agent development architecture patterns: design write-ups plus drop-in scaffolding, E2E-tested, published on npm.">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&family=Nunito:ital,wght@0,400;0,600;0,700;1,400&display=swap" rel="stylesheet">
+<style>
+  :root{
+    --bg:#f7f0e6; --card:#fdf8f2; --ink:#5b4a3f; --muted:#96826f;
+    --sage:#cfe3d0; --sage-d:#5f9c6c; --peach:#f9d3b5; --peach-d:#d97f45;
+    --pink:#f7c6d0; --pink-d:#cf6d87; --butter:#f7e0a8; --butter-d:#a97e1c;
+    --blue:#c5d7ee; --blue-d:#5c82b6; --lav:#d9cdf0; --lav-d:#8266bd;
+    --clay:0 10px 24px rgba(91,74,63,.13), inset 0 3px 8px rgba(255,255,255,.95), inset 0 -4px 8px rgba(91,74,63,.07);
+    --clay-sm:0 6px 14px rgba(91,74,63,.12), inset 0 2px 5px rgba(255,255,255,.9), inset 0 -2px 5px rgba(91,74,63,.06);
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.6 "Nunito",system-ui,sans-serif;
+    background-image:radial-gradient(600px 300px at 85% -50px, rgba(247,198,208,.35), transparent 70%),
+                     radial-gradient(500px 260px at -60px 30%, rgba(207,227,208,.4), transparent 70%),
+                     radial-gradient(520px 300px at 110% 75%, rgba(217,205,240,.32), transparent 70%);}
+  h1,h2,h3{font-family:"Baloo 2","Nunito",sans-serif;line-height:1.15;margin:0}
+  a{color:inherit;text-decoration:none}
+  .wrap{max-width:1060px;margin:0 auto;padding:28px 20px 60px}
+  header.nav{display:flex;align-items:center;gap:14px;flex-wrap:wrap;margin-bottom:26px}
+  .logo{font-family:"Baloo 2",sans-serif;font-weight:800;font-size:1.35rem;background:var(--card);
+    padding:10px 20px;border-radius:999px;box-shadow:var(--clay-sm);border:1.5px solid #fff}
+  .nav .spacer{flex:1}
+  .btn{display:inline-flex;align-items:center;gap:8px;font-weight:700;padding:10px 20px;border-radius:999px;
+    box-shadow:var(--clay-sm);border:1.5px solid #fff;transition:transform .15s ease, box-shadow .15s ease;cursor:pointer}
+  .btn:hover{transform:translateY(-2px)}
+  .btn.small{padding:8px 14px;font-size:.9rem}
+  .btn.sage{background:var(--sage);color:var(--sage-d)} .btn.peach{background:var(--peach);color:var(--peach-d)}
+  .btn.blue{background:var(--blue);color:var(--blue-d)}  .btn.lav{background:var(--lav);color:var(--lav-d)}
+  .card{background:var(--card);border-radius:28px;box-shadow:var(--clay);border:1.5px solid #fff;padding:26px 28px}
+  .hero{display:grid;grid-template-columns:1.5fr 1fr;gap:22px;align-items:stretch;margin-bottom:22px}
+  .hero .main{background:linear-gradient(145deg,#fbe3cd, #f9d3b5);}
+  .hero h1{font-size:clamp(1.9rem,4.5vw,2.9rem);color:#7a4b28;margin-bottom:10px}
+  .hero p.lede{color:#8a5a35;font-size:1.06rem;max-width:34em;margin:0 0 18px}
+  .cta{display:flex;gap:12px;flex-wrap:wrap;margin-bottom:18px}
+  .quick{background:rgba(255,255,255,.75);border-radius:18px;box-shadow:var(--clay-sm);border:1.5px solid #fff;
+    padding:12px 16px;display:flex;gap:10px;align-items:center;flex-wrap:wrap}
+  .quick code{font:600 .85rem/1.4 ui-monospace,Consolas,monospace;color:#7a4b28;word-break:break-all}
+  .hero .side{display:flex;flex-direction:column;gap:14px;justify-content:center}
+  .side .fact{display:flex;gap:12px;align-items:center;background:var(--card);border-radius:20px;
+    box-shadow:var(--clay-sm);border:1.5px solid #fff;padding:12px 16px;font-weight:600}
+  .side .fact .ico{font-size:1.5rem}
+  .chips{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:16px;margin:22px 0}
+  .chip{border-radius:24px;padding:18px 20px;box-shadow:var(--clay);border:1.5px solid #fff}
+  .chip .big{font-family:"Baloo 2",sans-serif;font-weight:800;font-size:1.7rem;display:block}
+  .chip small{font-weight:700;opacity:.75}
+  .chip.c1{background:var(--sage);color:var(--sage-d)} .chip.c2{background:var(--peach);color:var(--peach-d)}
+  .chip.c3{background:var(--butter);color:var(--butter-d)} .chip.c4{background:var(--blue);color:var(--blue-d)}
+  section{margin-top:34px}
+  section > h2{font-size:1.6rem;margin-bottom:14px}
+  .pattern{margin-bottom:18px}
+  .pattern-head{display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap;align-items:center;margin-bottom:8px}
+  .pattern h3{font-size:1.3rem}
+  .pill{display:inline-flex;align-items:center;gap:6px;padding:6px 14px;border-radius:999px;font-weight:700;
+    font-size:.85rem;box-shadow:var(--clay-sm);border:1.5px solid #fff}
+  .summary{color:var(--muted);margin:6px 0 14px;font-weight:600}
+  .roles{display:flex;gap:10px;flex-wrap:wrap;margin-bottom:12px}
+  .pill.role{background:#f3ece1;color:var(--ink)} .pill.role code{color:var(--lav-d)}
+  .usewhen{margin:0 0 14px;padding-left:22px;color:var(--muted)} .usewhen li{margin:4px 0}
+  .links{display:flex;gap:10px;flex-wrap:wrap}
+  .steps{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:16px}
+  .step{border-radius:24px;padding:20px;box-shadow:var(--clay);border:1.5px solid #fff;background:var(--card)}
+  .step .n{display:inline-flex;width:44px;height:44px;align-items:center;justify-content:center;font-size:1.4rem;
+    border-radius:16px;box-shadow:var(--clay-sm);border:1.5px solid #fff;margin-bottom:10px}
+  .step:nth-child(1) .n{background:var(--sage)} .step:nth-child(2) .n{background:var(--butter)}
+  .step:nth-child(3) .n{background:var(--peach)} .step:nth-child(4) .n{background:var(--lav)}
+  .step:nth-child(5) .n{background:var(--pink)}
+  .step h3{font-size:1.05rem;margin-bottom:6px} .step p{margin:0;font-size:.9rem;color:var(--muted)}
+  .step code{font-size:.8rem;color:var(--lav-d);word-break:break-all}
+  footer{margin-top:44px;text-align:center;color:var(--muted);font-weight:600;font-size:.9rem}
+  footer a{color:var(--lav-d)}
+  @media (max-width:760px){.hero{grid-template-columns:1fr}}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header class="nav">
+    <span class="logo">🏗️ agent-templates</span>
+    <span class="spacer"></span>
+    <a class="btn sage" href="${GITHUB}">⭐ GitHub</a>
+    <a class="btn peach" href="${NPM}">📦 npm <span data-npm-version>v${esc(pkg.version)}</span></a>
+  </header>
+
+  <div class="hero">
+    <div class="card main">
+      <h1>Multi-agent patterns,<br>ready to drop in.</h1>
+      <p class="lede">Field-proven architectures for AI-agent development — each one a design write-up <b>plus</b> working scaffolding. Humans decide at two gates; the agents do the rest.</p>
+      <div class="cta">
+        <a class="btn blue" href="${GITHUB}/blob/main/ADOPTING.md">🚀 Adoption guide</a>
+        <a class="btn lav" href="${GITHUB}/blob/main/CLAUDE.md">📜 Operating manual</a>
+      </div>
+      <div class="quick"><code id="qs">${esc(QUICKSTART)}</code><button class="btn small butter" style="background:var(--butter);color:var(--butter-d)" onclick="navigator.clipboard.writeText(document.getElementById('qs').textContent).then(()=>{this.textContent='Copied ✓'})">Copy</button></div>
+    </div>
+    <div class="side">
+      <div class="fact"><span class="ico">🧾</span> Every model/effort claim carries a source label and an expiry date</div>
+      <div class="fact"><span class="ico">🛡️</span> Role boundaries enforced by hooks, not prose</div>
+      <div class="fact"><span class="ico">🌙</span> Nightly sweep triages and fixes issues while you sleep</div>
+    </div>
+  </div>
+
+  <div class="chips">
+    <div class="chip c1"><span class="big">${patterns.length}</span><small>pattern${patterns.length === 1 ? '' : 's'} in the catalog</small></div>
+    <div class="chip c2"><span class="big" data-npm-version>v${esc(pkg.version)}</span><small>on npm · MIT</small></div>
+    <div class="chip c3"><span class="big">E2E</span><small>gated merges — deterministic, zero-token tests</small></div>
+    <div class="chip c4"><span class="big">2</span><small>human gates: sign-off &amp; smoke test</small></div>
+  </div>
+
+  <section>
+    <h2>🧩 Patterns</h2>
+    ${patternCards}
+  </section>
+
+  <section>
+    <h2>🛤️ From a bare PRD.md to shipped</h2>
+    <div class="steps">
+      ${STEPS.map(([ico, t, d], i) => `<div class="step"><span class="n">${ico}</span><h3>${i + 1}. ${t}</h3><p>${d}</p></div>`).join('\n      ')}
+    </div>
+  </section>
+
+  <footer>
+    Generated from the pattern catalog by <a href="${GITHUB}/blob/main/scripts/build-site.mjs">scripts/build-site.mjs</a>
+    · ${new Date().toISOString().slice(0, 10)} · <a href="${GITHUB}/blob/main/LICENSE">MIT</a>
+    · <a href="${GITHUB}/issues/new/choose">Feedback → issues</a>
+  </footer>
+</div>
+<script>
+fetch('https://registry.npmjs.org/agent-templates').then(r=>r.json()).then(d=>{
+  var v=d['dist-tags']&&d['dist-tags'].latest;
+  if(v){document.querySelectorAll('[data-npm-version]').forEach(function(e){e.textContent='v'+v})}
+}).catch(function(){})
+</script>
+</body>
+</html>
+`
+
+mkdirSync(OUT, { recursive: true })
+writeFileSync(join(OUT, 'index.html'), html)
+writeFileSync(join(OUT, '.nojekyll'), '')
+console.log(`site: ${join(OUT, 'index.html')} (${patterns.length} pattern(s), pkg v${pkg.version})`)

package/scripts/cli.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// agent-templates CLI — the npx entry point (package.json "bin").
+// Dispatches to the catalog tooling; carries no logic of its own.
+//
+//   agent-templates list                                      show available patterns
+//   agent-templates adopt <pattern> <target-dir> [options]    install a pattern (see adopt.mjs)
+//
+// Without cloning the catalog:
+//   npx github:Ruihang2017/agent-templates list
+//   npx github:Ruihang2017/agent-templates adopt three-agent-architect-builder-reviewer .
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = fileURLToPath(new URL('..', import.meta.url))
+const [cmd, ...rest] = process.argv.slice(2)
+
+if (cmd === 'adopt') {
+  const r = spawnSync(process.execPath, [join(ROOT, 'scripts', 'adopt.mjs'), ...rest], { stdio: 'inherit' })
+  process.exit(r.status === null ? 1 : r.status)
+}
+
+if (cmd === 'list') {
+  const dir = join(ROOT, 'patterns')
+  const patterns = existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, 'scaffold')))
+        .map((d) => d.name)
+    : []
+  console.log(patterns.length ? patterns.join('\n') : '(no patterns found)')
+  process.exit(0)
+}
+
+const usage = `agent-templates — multi-agent pattern catalog
+
+usage:
+  agent-templates list
+  agent-templates adopt <pattern> <target-dir> [--platform gh|glab] [--force]
+
+without cloning:
+  npx github:Ruihang2017/agent-templates list
+  npx github:Ruihang2017/agent-templates adopt three-agent-architect-builder-reviewer .
+
+docs: ADOPTING.md in the catalog root`
+if (!cmd) {
+  console.log(usage)
+  process.exit(0)
+}
+console.error(`unknown command: ${cmd}\n\n${usage}`)
+process.exit(1)

package/templates/pattern-README.template.md

@@ -0,0 +1,65 @@
+# Pattern: <Human-Readable Pattern Name>
+
+<!-- Copy this file to patterns/<kebab-name>/README.md and fill EVERY section.
+     Format reference: patterns/three-agent-architect-builder-reviewer/README.md
+     Rules: CLAUDE.md "Grounding rules" — every model/effort claim carries a source label;
+     no training-data impressions; as-of date moves with every recommendation change. -->
+
+| Field | Value |
+|---|---|
+| **Pattern name** | `<kebab-name>` (= directory name) |
+| **Status** | `proposed` <!-- proposed → trialed → adopted → deprecated --> |
+| **As-of date** | YYYY-MM-DD |
+| **Expiry trigger** | First successor release to any listed model, or YYYY-MM-DD (+6 months), whichever comes first |
+| **Sign-off** | <name, role, date> |
+
+<One- or two-sentence summary of the agent topology: who does what, in what order.>
+
+## 1. When to use / when not to use
+
+**Use when:**
+- <concrete task shape>
+
+**Do not use when:**
+- <concrete task shape — every pattern has a floor below which its overhead dominates>
+
+## 2. Agent roles & boundaries
+
+| Agent | Does | Never does |
+|---|---|---|
+| **<Role>** | <responsibility> | <hard boundary> |
+
+<Who judges whom; which contexts must stay isolated; which boundaries are hard requirements vs tunable.
+State which agent owns unit / integration / E2E tests — agents own all three levels (repo testing policy);
+the human only smoke-tests at PRD completion.>
+
+## 3. Model + effort assignment (as of YYYY-MM-DD)
+
+| Role | Model | Effort | Reasoning | Source labels |
+|---|---|---|---|---|
+| <Role> | <exact model name> | <effort level> | <why this model/effort for this role> | <`[official]` / `[vendor-benchmark]` / `[third-party]` / `[internal]` / `[unverified]` / `[team-policy]` + link or "link not captured — attach at first re-verification"> |
+
+## 4. Known failure modes / pitfalls
+
+| Pitfall | Context | Mitigation | Recorded |
+|---|---|---|---|
+| <symptom> | <the specific harness/project/conditions it was observed in — or "design constraint (not a measured incident)"> | <mitigation> | YYYY-MM-DD |
+| Harness-specific failures for these exact model+effort combinations | **None recorded yet** (as of YYYY-MM-DD) | Record here with harness name, conditions, and date when observed | — |
+
+## 5. Upstream / downstream integration
+
+**Upstream (work intake):** <how work enters — master PRD → sub-PRD → ticket; which docs each agent reads; where ADRs come in.>
+
+**Downstream (deliverables):** <what leaves — PR, verdict, docs; what gates a merge.>
+
+**Human gates:** <where humans decide (e.g. the start signal), where they must NOT be needed, and the exception path that pulls a human back in.>
+
+## 6. Scaffold
+
+<List of files under scaffold/ and what each is for. Point to scaffold/INSTALL.md for install steps. Note the date the scaffold's config keys were last verified against Claude Code docs.>
+
+## 7. Provenance & change log
+
+| Date | Change | Basis | Author |
+|---|---|---|---|
+| YYYY-MM-DD | Initial entry | <source record / doc links> | <who> |

package/templates/ticket.template.md

@@ -0,0 +1,104 @@
+<!-- Universal ticket template — all patterns, plus the catalog repo itself.
+     Format distilled 2026-07-17 from the team's field-proven tickets: fx-eye-tracking
+     discipline, realtime-pilot PIL-15, MeritAI FND-9.
+     Copy to docs/prd/<NN-module>/tickets/<ID>-<slug>.md and fill every section.
+     Cold-start rule: a ticket is DEFECTIVE if executing it requires the planning
+     conversation. Inline the needed facts AND link their authoritative source.
+     The body below the frontmatter becomes the tracker issue body verbatim
+     (.claude/scripts/publish-tickets.mjs); the file stays the content source of truth. -->
+---
+id: MOD-NN            # unique + stable; becomes the issue-title prefix "[MOD-NN]" (the dedupe key)
+title: Short imperative title
+module: NN-module     # = parent directory name under docs/prd/
+lane: NN-module       # parallel lane; lanes may run concurrently ONLY with disjoint file-scopes
+size: S               # S | M | L
+agent: builder        # primary executing stage; justify in the "Why" line below
+status: draft         # draft -> ready -> done
+date: YYYY-MM-DD
+blocked_by: []        # ticket ids this one cannot start before (machine-readable dependency DAG)
+blocks: []            # ticket ids waiting on this one
+---
+
+# MOD-NN — Short imperative title
+
+Implements <PRD §X FR-Y> per <ADR-NNNN (status, owner, date, via PR #N)> — or: "No ADR —
+the decision is already made in <ref>; this is build ticket <n of m> against it."
+Parent sub-PRD: [NN-module README](../README.md). Master spec: [PRD](../../../PRD.md).
+Depends on: [MOD-NM — other ticket](MOD-NM-other-ticket.md) <!-- mirrors blocked_by; delete if none -->
+**Why `builder`:** <one line — the basis for the agent assignment, e.g. "a narrowly-scoped
+addition to an existing module, not a new subsystem">.
+
+## Background + basis
+
+<!-- Why this ticket exists. CITE every claim: PRD §, ADR section, stable decision ID, or a
+     merged PR — a conclusion may not appear from nowhere. QUOTE the load-bearing sentences
+     of the ADR/spec so the Builder does not re-derive intent.
+     Carry known caveats forward EXPLICITLY ("accepted for the pilot: X — documented, not
+     enforced, per PRD §Y") instead of re-litigating or silently dropping them. -->
+
+## Goal
+
+<!-- One paragraph: the artifact(s)/behavior to produce and where they land — stated so
+     completion is mechanically checkable. -->
+
+## Non-goals
+
+<!-- Bullet list. EACH exclusion names its owner or standing reason, so nobody guesses:
+     - No schema files — those are MOD-02.
+     - No init authentication — stays documented-not-enforced per PRD §9.4. Do not add it
+       as a side effect of this ticket. -->
+
+## File-scope (write-owns)
+
+<!-- Exact paths/globs this ticket may write, PLUS the explicit does-not-touch list.
+     State the serial-safety analysis: which tickets last touched these files, whether that
+     work is merged, and that no in-flight ticket contends for them. Must not overlap any
+     other in-flight ticket — disjoint file-scopes are what make parallel lanes safe.
+     Internal organization inside the scope is the Builder's choice. -->
+
+- <paths this ticket owns>
+- Does not touch: <paths owned elsewhere — name the owning ticket/module>
+
+## Deliverables
+
+<!-- Numbered, code-level precision: exact functions/exports, call sites, ordering
+     constraints ("directly after X and before Y"), naming conventions, and the behavioral
+     guarantee ("either fully visible or fully absent"). Fix the boundary AND the
+     load-bearing mechanics; leave internals free. -->
+
+1. <deliverable>
+
+## Acceptance checklist (classified)
+
+<!-- Every criterion is a checkbox with exactly one class tag. The tag VOCABULARY is
+     project-defined in the target repo's CLAUDE.md — defaults: [machine] runnable
+     code/logic check · [fixture] replay of recorded data · [human] irreducibly human
+     judgment. Field vocabularies in use: [offline]/[live-model] (realtime pilot),
+     [machine]/[fixture]/[hardware-human] (fx-eye-tracking).
+     Rules: cover the pyramid where applicable — unit / integration / E2E; agents own all
+     three levels, the human only smoke-tests at PRD completion. Include the standing
+     suite-green item. If the ticket must conclude an open question, make the WRITEBACK
+     itself an acceptance item. Mark optional orchestrator-owned live checks "not required
+     to merge". Declare absent classes explicitly ("No [human] criteria — pure logic"). -->
+
+- [ ] `[machine]` <criterion> (<cross-ref to AC/decision id>)
+- [ ] `[machine]` <project test-suite command> green
+
+## Test plan
+
+<!-- The exact steps the Reviewer runs. NAME the harness/mocks/fixtures and the existing
+     test file whose construction pattern to copy. Say what is asserted, on what. Every
+     [machine]/[fixture] row must be reproducible offline. -->
+
+## Feedback obligation
+
+<!-- The writeback protocol, made concrete — three layers:
+     1. General rule: if implementation falsifies this spec, update this ticket / the
+        sub-PRD / the ADR first (version +0.1, changelog line), then change code. Silent
+        divergence = incomplete.
+     2. ENUMERATE the foreseeable frictions, each with its exact writeback target and path:
+        "if X cannot be expressed as Y → update docs/design-Z.md and ADR-NNNN's
+        consequences section FIRST, before touching src/W — a bigger surface than this
+        ticket's goal must not change silently."
+     3. If a decided protocol is outright falsified: that overturns a team decision —
+        escalate for re-review; never swap the approach silently inside the ticket. -->

package/templates/tracker/github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a defect. Nightly triage reads this — the more mechanical the reproduction, the likelier an overnight fix.
+title: ''
+labels: ''
+assignees: ''
+---
+
+## Symptom
+
+<!-- What happens. Paste the exact error output / wrong value. -->
+
+## Reproduction
+
+<!-- Exact steps or commands; the smallest input that triggers it. -->
+
+## Expected
+
+<!-- What should happen instead, stated checkably. Cite the spec (PRD §/ADR) if you know it. -->
+
+## Affected area (best guess)
+
+<!-- Files/modules if you know them; leave empty if unsure — triage will trace it. -->
+
+## Acceptance
+
+<!-- What proves it fixed. Ideally a runnable check, e.g. "npm test stays green and f(x) returns y".
+     The pipeline turns this into the ticket's classified acceptance checklist. -->

package/templates/tracker/github/ISSUE_TEMPLATE/decision-record.md

@@ -0,0 +1,25 @@
+---
+name: Decision record
+about: Records what was done and why — the durable memory that commits cannot carry. Used by agents and humans alike.
+title: 'Decision record: '
+labels: decision-record
+assignees: ''
+---
+
+**What** (merged in <commit/PR/MR>, YYYY-MM-DD): <one paragraph — the change as shipped.>
+
+**Key decisions & why**
+
+<!-- One bullet per decision: the decision, its reason, and the rejected alternative when
+     one was seriously considered. Cite sources — official docs, ADRs, maintainer direction
+     with date — the same grounding discipline as everything else. -->
+
+-
+
+**Evidence**
+
+<!-- Test results, verification records, links to the docs where each decision landed. -->
+
+**Links**
+
+<!-- Related issues / PRs / ADRs / tickets. -->

package/templates/tracker/github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,36 @@
+---
+name: Task
+about: Request a bounded piece of work. Mirrors the pipeline's ticket format so triage can convert it mechanically.
+title: ''
+labels: ''
+assignees: ''
+---
+
+## Traceability
+
+<!-- What this implements or follows from: PRD §/FR, an ADR, a discussion, an upstream
+     pattern — with links. If the decision is already made somewhere, say where. -->
+
+## Background + basis
+
+<!-- Why this is needed. Cite claims; quote the load-bearing sentences rather than
+     paraphrasing from memory. -->
+
+## Goal
+
+<!-- One paragraph: the artifact(s) to produce and where they land — checkable. -->
+
+## Non-goals
+
+<!-- Each exclusion names its owner or standing reason: "No X — that is MOD-02" /
+     "No Y — stays out of scope per PRD §Z; do not add it as a side effect." -->
+
+## Affected area (best guess)
+
+<!-- Files/modules if known; the Architect finalizes the file-scope and the
+     does-not-touch list. -->
+
+## Acceptance
+
+<!-- Checkable criteria, one per line, tagged with the repo's class vocabulary if you can
+     (defaults: [machine]/[fixture]/[human]). Prefer runnable checks ("command X exits 0"). -->

package/templates/tracker/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,54 @@
+## Summary
+
+<!-- What does this PR do? One sentence. -->
+
+## Related issue / ticket
+
+<!-- Closes #N — plus the ticket id, e.g. [MOD-NN]. The ticket FILE stays the content
+     source of truth; the issue holds state. -->
+
+## Type
+
+<!-- Check one; matches conventional-commit prefixes. -->
+
+- [ ] `feat` — new feature
+- [ ] `fix` — bug fix
+- [ ] `refactor` — restructuring, no behavior change
+- [ ] `docs` — documentation / ADR only
+- [ ] `test` — new or updated tests
+- [ ] `ci` / `chore` — tooling, maintenance
+
+## Changes
+
+<!-- Bullets: what changed AND why. Include what was tried and rejected if it shaped the result. -->
+
+-
+
+## Design note
+
+<!-- Hard-to-reverse or non-obvious changes: link the ADR (docs/adr/NNNN-*.md) — add one if
+     this is a durable decision. Otherwise summarize inline: problem · affected components ·
+     contract/schema changes · risks. -->
+
+## Pipeline evidence
+
+<!-- Assumes the installed pattern; the three-agent pattern's items are shown — adapt if
+     this repo runs a different pattern. -->
+
+- [ ] Plan: `docs/plans/<ticket-id>.md` (link)
+- [ ] Builder: REAL test output attached (unit / integration / E2E as the ticket requires) — never "should pass"
+- [ ] Reviewer verdict: **CLEAR**, from a fresh context (link or paste the note; bounces: <n>)
+- [ ] Deviations from the plan recorded (or "none")
+- [ ] Post-merge: `/verify-delivery <ticket-id>` runs — the issue closes only after it passes
+
+## Constraint check
+
+<!-- At install time, copy this repo's non-negotiables from its CLAUDE.md here as
+     checkboxes. Tick what this PR touches; mark the rest N/A. Two universal items: -->
+
+- [ ] No hardcoded secrets (keys, tokens, credentials) in code / config / logs / docs
+- [ ] Docs / ADR / ticket updated if behavior or a decision changed (feedback obligation)
+
+## Evidence
+
+<!-- Test output, before/after screenshots (UI), command + output (CLI/API), or a short repro. -->

package/templates/tracker/gitlab/issue_templates/bug-report.md

@@ -0,0 +1,23 @@
+<!-- GitLab description template ("bug-report"). Nightly triage reads this —
+     the more mechanical the reproduction, the likelier an overnight fix. -->
+
+## Symptom
+
+<!-- What happens. Paste the exact error output / wrong value. -->
+
+## Reproduction
+
+<!-- Exact steps or commands; the smallest input that triggers it. -->
+
+## Expected
+
+<!-- What should happen instead, stated checkably. Cite the spec (PRD §/ADR) if you know it. -->
+
+## Affected area (best guess)
+
+<!-- Files/modules if you know them; leave empty if unsure — triage will trace it. -->
+
+## Acceptance
+
+<!-- What proves it fixed. Ideally a runnable check, e.g. "npm test stays green and f(x) returns y".
+     The pipeline turns this into the ticket's classified acceptance checklist. -->