create-rigel 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,156 @@
+<div align="center">
+
+# ✦ rigel
+
+**Harness the power of AI coding agents into shipped, gated software.**
+
+Scaffold an agent-first, gate-enforced starter project — Next.js · Express · NestJS · FastAPI — each wired for [Claude Code](https://docs.claude.com/en/docs/claude-code) with a mechanical quality gate, path-scoped rules, specialist review agents, and a spec-driven workflow baked in.
+
+[![npm version](https://img.shields.io/npm/v/create-rigel.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/create-rigel)
+[![npm downloads](https://img.shields.io/npm/dm/create-rigel.svg)](https://www.npmjs.com/package/create-rigel)
+[![CI](https://github.com/Shreyas1015/create-rigel/actions/workflows/ci.yml/badge.svg)](https://github.com/Shreyas1015/create-rigel/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/create-rigel.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/create-rigel.svg?logo=node.js)](https://nodejs.org)
+
+</div>
+
+```bash
+npm create rigel@latest my-app
+```
+
+> **rigel** — named for the *rig* that harnesses raw power, and for [Rigel](https://en.wikipedia.org/wiki/Rigel), one of the brightest stars in the sky. It rigs your project with guardrails so a powerful agent builds like a pro.
+
+---
+
+## Table of contents
+
+- [Why rigel?](#why-rigel)
+- [What you get](#what-you-get)
+- [Quick start](#quick-start)
+- [Templates](#templates)
+- [Inside a scaffolded project](#inside-a-scaffolded-project)
+- [The workflow it enables](#the-workflow-it-enables)
+- [Requirements](#requirements)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [Versioning](#versioning)
+- [License](#license)
+
+## Why rigel?
+
+Coding agents are great at *writing* code and bad at *stopping themselves from drifting*. Point one at an empty repo and you get inconsistent structure, untested code, and "looks done" claims that don't hold up. The fix isn't a better prompt — it's a **repo that constrains the agent**: written rules it must follow, a fixed build order, and a gate that blocks the commit when the code is wrong.
+
+`rigel` scaffolds exactly that repo. Every template ships an opinionated architecture plus a `.claude/` workflow so that, from the first commit, an AI agent (or a human) builds through a **spec → plan → layered build → mechanical gate** loop instead of freewheeling. Quality is enforced by checks that fail the build, not by hoping someone remembers the standard.
+
+**In one line:** it's `create-next-app` for teams who build *with* AI agents and want the guardrails in the repo, not in their heads.
+
+## What you get
+
+- 🧱 **Opinionated, layered architecture** per stack — a strict import matrix (types → config → models → repo → service → runtime → …) that keeps business logic testable and isolated.
+- ✅ **A mechanical gate** — `typecheck + lint (zero warnings) + circular-dep check + architecture tests + coverage thresholds` that must pass before every commit. Encode a rule or drop it.
+- 🤖 **A `.claude/` workflow** — path-scoped rules, a numbered skill pipeline, and specialist review agents (reviewer, security-auditor, arch-validator, db-optimizer, …) that run automatically.
+- 📐 **Spec-driven delivery** — a `docs/` taxonomy (product-specs → exec-plans → design-docs/ADRs) so intent lives in the repo and drives the build.
+- 🔒 **Security & correctness defaults** — validate-at-the-boundary, OWASP handler ordering, a mandatory cross-user isolation test (404, not 403), and a pre-write hook that blocks secrets and edits to generated contracts.
+- 🚦 **CI-ready** — pre-commit hooks and CI workflows so the gate runs on every push, not just locally.
+
+## Quick start
+
+```bash
+# interactive — prompts you to pick a stack
+npm create rigel@latest my-app
+
+# or choose the stack up front
+npm create rigel@latest my-app -- --template nextjs
+
+# scaffold into the current directory
+npm create rigel@latest .
+```
+
+Using another package manager? All of these work:
+
+```bash
+pnpm create rigel my-app
+yarn  create rigel my-app
+bun   create rigel my-app
+```
+
+> **Note:** with npm 7+, flags after the project name need the extra `--` (as shown above).
+
+## Templates
+
+| Template | Stack | Best for |
+|----------|-------|----------|
+| **`nextjs`** | Next.js + React + TypeScript + Tailwind, TanStack Query, typed API client | Frontends that consume a typed API contract |
+| **`express`** | Express + TypeScript + Sequelize (Postgres) + BullMQ + OpenTelemetry | Backends / REST APIs with jobs and observability |
+| **`nestjs`** | NestJS + TypeScript | Modular, DI-first backends |
+| **`fastapi`** | FastAPI + Python (uv) + SQLAlchemy + ruff/mypy/bandit | Python backends / data services |
+
+Pick interactively, or pass `--template <name>`.
+
+## Inside a scaffolded project
+
+Every template lays down the same shape (adapted per stack):
+
+```text
+my-app/
+├── .claude/
+│   ├── rules/          # path-scoped rules auto-injected as the agent edits (architecture, api, security, testing, …)
+│   ├── agents/         # specialist reviewers: gate-checker, reviewer, security-auditor, arch-validator, db-optimizer …
+│   ├── skills/         # the numbered pipeline: 00-infra-setup → 01-write-roadmap → … → build-layer → garbage-collect
+│   ├── hooks/          # a post-write hook that warns/blocks (secrets, edits to generated contracts, oversized files)
+│   └── CLAUDE.md       # standing instructions the agent reads every session
+├── docs/
+│   ├── product-specs/  # ROADMAP + one spec per feature (draft → ready)
+│   ├── exec-plans/     # layered execution plans (active → completed) + tech-debt tracker
+│   └── design-docs/    # core-beliefs (the constitution) + ADRs (decisions/)
+├── ARCHITECTURE.md     # the layer diagram + import matrix
+├── AGENTS.md           # navigation map + non-negotiable invariants
+└── src/                # generated on first run by /infra-setup
+```
+
+The **gate** (`npm run gate` / `scripts/gate.sh`) is the enforcement core: type-clean, lint-clean (zero warnings), no circular deps, no cross-layer imports, no files over the size limit, coverage above per-layer thresholds, and the cross-user isolation test present. It runs after every build layer and in CI.
+
+## The workflow it enables
+
+After scaffolding, open the project in Claude Code and drive the pipeline:
+
+```text
+/infra-setup      # generates src/ and installs dependencies (run once)
+/write-roadmap    # decompose the product into an ordered set of feature specs
+/write-spec       # write ONE feature spec — you review it and mark it READY
+/write-plan       # derive a layered, checkboxed execution plan from the spec
+/build-layer      # build ONE layer → gate → auto-fix (max 3) → commit → you confirm → next
+/garbage-collect  # end-of-feature cleanup + quality score update
+```
+
+The agent does the typing; **you own the specs and the merges**; the gate catches mistakes mechanically. You review *decisions*, not lint errors.
+
+## Requirements
+
+- **Node.js ≥ 18** to run the scaffolder itself.
+- Individual templates may need more:
+  - `nextjs` / `express` / `nestjs` — Node (see each template's `.nvmrc`), a package manager.
+  - `express` also expects Postgres + Redis for local dev (Docker Compose included).
+  - `fastapi` — Python 3.11+ and [`uv`](https://github.com/astral-sh/uv).
+
+## FAQ
+
+**Do I have to use Claude Code?** No — the templates are normal, runnable projects. The `.claude/` workflow is a bonus that makes AI-assisted development disciplined; the gate and architecture stand on their own.
+
+**Why is FastAPI (Python) shipped from an npm package?** The scaffolder only *copies files* — it's language-agnostic. npm is just the delivery mechanism, the same way `create-*` tools scaffold non-JS projects.
+
+**Can I add my own template?** Yes — see [CONTRIBUTING.md](./CONTRIBUTING.md). Templates live in [`templates/`](./templates); add a folder and register it in `cli.js`.
+
+**Does it modify anything outside the target folder?** No. It creates the project directory (refusing to overwrite a non-empty one) and nothing else.
+
+## Contributing
+
+Templates are the source of truth and live in [`templates/`](./templates). See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to run, test (`npm test` scaffolds every template), and add a stack. Bugs and ideas → [issues](https://github.com/Shreyas1015/create-rigel/issues).
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org). See the [CHANGELOG](./CHANGELOG.md) for release notes.
+
+## License
+
+[MIT](./LICENSE)

package/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// create-harness — scaffold an agent-first, gate-enforced starter project.
+// Zero runtime dependencies (Node builtins only), so it publishes with no build step.
+
+import { readdir, cp, rename, mkdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(HERE, "templates");
+
+const STACKS = {
+  nextjs: "Next.js + React + TypeScript (frontend)",
+  express: "Express + TypeScript + Sequelize (backend)",
+  nestjs: "NestJS + TypeScript (backend)",
+  fastapi: "FastAPI + Python (backend)",
+};
+
+function parseArgs(argv) {
+  const args = { name: undefined, template: undefined };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--template" || a === "-t") args.template = rest[++i];
+    else if (a.startsWith("--template=")) args.template = a.split("=")[1];
+    else if (!a.startsWith("-") && !args.name) args.name = a;
+  }
+  return args;
+}
+
+async function prompt(rl, question) {
+  const answer = await rl.question(question);
+  return answer.trim();
+}
+
+async function chooseStack(rl, preset) {
+  if (preset && STACKS[preset]) return preset;
+  if (preset) {
+    console.error(`\n  Unknown template "${preset}". Available: ${Object.keys(STACKS).join(", ")}\n`);
+  }
+  console.log("\n  Which stack?\n");
+  const keys = Object.keys(STACKS);
+  keys.forEach((k, i) => console.log(`    ${i + 1}) ${k.padEnd(11)} ${STACKS[k]}`));
+  console.log("");
+  while (true) {
+    const raw = await prompt(rl, "  Enter number (1-4): ");
+    const idx = Number(raw) - 1;
+    if (Number.isInteger(idx) && keys[idx]) return keys[idx];
+    console.log("  Please enter a number between 1 and 4.");
+  }
+}
+
+async function isNonEmptyDir(dir) {
+  if (!existsSync(dir)) return false;
+  const entries = await readdir(dir);
+  return entries.length > 0;
+}
+
+// npm ships templates with `gitignore` (not `.gitignore`, which npm strips).
+// Restore the leading dot in the scaffolded project.
+async function restoreDotfiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      await restoreDotfiles(full);
+    } else if (e.name === "gitignore") {
+      await rename(full, join(dir, ".gitignore"));
+    } else if (e.name === "npmignore") {
+      await rename(full, join(dir, ".npmignore"));
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const rl = createInterface({ input, output });
+  try {
+    let name = args.name;
+    if (!name) name = await prompt(rl, "\n  Project directory (\".\" for current): ");
+    if (!name) {
+      console.error("  No project directory given. Aborting.");
+      process.exit(1);
+    }
+    const target = resolve(process.cwd(), name);
+
+    if (name !== "." && (await isNonEmptyDir(target))) {
+      console.error(`\n  Target "${name}" already exists and is not empty. Aborting.\n`);
+      process.exit(1);
+    }
+
+    const stack = await chooseStack(rl, args.template);
+    const source = join(TEMPLATES_DIR, stack);
+    if (!existsSync(source)) {
+      console.error(`\n  Template "${stack}" is missing from this package. Aborting.\n`);
+      process.exit(1);
+    }
+
+    await mkdir(target, { recursive: true });
+    await cp(source, target, { recursive: true });
+    await restoreDotfiles(target);
+
+    const rel = name === "." ? "." : name;
+    console.log(`\n  ✓ Scaffolded a "${stack}" project into ${rel}\n`);
+    console.log("  Next steps:");
+    if (name !== ".") console.log(`    cd ${name}`);
+    console.log("    git init");
+    console.log("    # open in Claude Code, then run the harness setup skill:");
+    console.log("    #   /infra-setup      (generates src/ and installs deps)");
+    console.log("    #   /write-roadmap → /write-spec → /write-plan → /build-layer\n");
+  } finally {
+    rl.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-rigel",
+  "version": "0.1.0",
+  "description": "Scaffold an agent-first, gate-enforced starter project — Next.js, Express+TypeScript, NestJS, or FastAPI — wired for Claude Code.",
+  "type": "module",
+  "bin": {
+    "create-rigel": "cli.js"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "files": [
+    "cli.js",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "rigel",
+    "create",
+    "harness",
+    "template",
+    "scaffold",
+    "starter",
+    "nextjs",
+    "express",
+    "nestjs",
+    "fastapi",
+    "claude-code",
+    "agentic"
+  ],
+  "author": "Shreyas1015",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shreyas1015/create-rigel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Shreyas1015/create-rigel/issues"
+  },
+  "homepage": "https://github.com/Shreyas1015/create-rigel#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/express/.claude/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md — Agent Entry Point
+
+You are an agent-first backend engineer working on a TypeScript + Express + Sequelize project.
+Read this file first on every session. Then read the active execution plan before touching any code.
+
+---
+
+## Skill Freshness Check
+
+Before following any skill that installs or configures a library (those with a non-empty `libraries:` list in their frontmatter — e.g. `/infra-setup`, `/build-layer`, `/db-optimize`, `/load-test`):
+
+1. Read the skill's `verified:` date in its frontmatter.
+2. If `verified:` is more than `staleness-threshold-days` (default 60) old:
+   - For each library in `libraries:`, run `npm show <library> version` to confirm the latest stable version.
+   - If the latest major version differs from what the skill assumes, check the library's changelog for breaking changes before proceeding.
+   - Update the skill's `verified:` date and adjust its instructions if anything changed.
+3. Skills with `libraries: []` are process-only — no freshness check needed.
+
+If `npm show` / network is unavailable, fall back to the skill as written (degraded but functional) and note the staleness in your summary.
+
+---
+
+## Cardinal Rules (memorise these)
+
+1. **Read the active plan first** — `docs/exec-plans/active/`
+2. **If no plan exists** — run `/write-roadmap` (whole product) or `/write-spec` (one feature), then `/write-plan`, before any code
+3. **Never write code without a plan** — document intent before implementation
+4. **Gate must PASS before commit** — never skip `/validate-layer`
+5. **Auto-fix gate failures** — fix silently, log what was fixed, re-run gate
+6. **One layer at a time** — complete + gate + commit before the next
+
+---
+
+## Session Start Checklist
+
+```
+1. ls docs/exec-plans/active/          → is there an active plan?
+2. If yes  → read it, find first unchecked layer, run /build-layer
+3. If no   → ask human: whole product or one feature?
+             whole product → /write-roadmap   |   one feature → /write-spec
+4. Never assume — check the repo state first
+```
+
+---
+
+## The Layer Build Loop (automated by /build-layer)
+
+```
+Read active plan
+  → find first [ ] unchecked layer
+  → read path-scoped rules for that layer type
+  → write the layer files
+  → run gate-checker agent
+  → if FAIL: auto-fix all items, log fixes, re-run gate (max 3 attempts)
+  → if PASS: update plan checkbox, write ADR if non-obvious decision, commit, push
+  → present summary to human
+  → WAIT for human confirmation before next layer
+```
+
+---
+
+## Gate Failure = Auto-Fix (not escalation)
+
+When the gate fails:
+- Fix it yourself
+- Log exactly what was fixed and why
+- Re-run the gate
+- Only escalate if the fix requires a product/architecture decision
+
+---
+
+## Observability on Every Boundary
+
+Every service method must emit:
+```typescript
+logger.info({ event: 'domain.action', ...context, durationMs })
+span.setAttributes({ ... })
+```
+No silent operations. No fire-and-forget without logging.
+
+---
+
+## Quick Reference
+
+| Thing | Location |
+|---|---|
+| Navigation map | `AGENTS.md` |
+| Layer rules | `ARCHITECTURE.md` |
+| Active plan | `docs/exec-plans/active/` |
+| Slash commands | `AGENTS.md#slash-commands` |
+| Spec format | `docs/PLANS.md` |
+| Quality grades | `docs/QUALITY_SCORE.md` |
+| Tech debt | `docs/exec-plans/tech-debt-tracker.md` |
+| Engineering beliefs | `docs/design-docs/core-beliefs.md` |
+
+---
+
+## Stack Reference
+
+Versions are intentionally unpinned — `/infra-setup` installs the latest LTS of each.
+Run the Skill Freshness Check before relying on version-specific behaviour.
+
+```
+Runtime:    Node 24 LTS, TypeScript, Express
+ORM:        Sequelize + sequelize-typescript, sequelize-cli
+Auth:       jose (JWT), argon2 (passwords)
+Queue:      BullMQ + ioredis
+Logging:    pino
+Tracing:    OpenTelemetry SDK
+Validation: zod
+Security:   helmet, cors, express-rate-limit + rate-limit-redis
+Testing:    jest, ts-jest, supertest
+Tooling:    tsx, ESLint, prettier, madge, husky
+```

package/templates/express/.claude/agents/arch-validator.md

@@ -0,0 +1,85 @@
+---
+name: arch-validator
+description: Deep architecture compliance scan. More thorough than gate-checker. Use when you suspect drift or before a major refactor.
+model: claude-opus-4-8
+tools: [Read, Bash]
+color: orange
+---
+
+You are the architecture validator. Run a comprehensive compliance scan of the entire codebase.
+
+## Scans
+
+```bash
+echo "=== Circular Imports ==="
+npx madge --circular src/ --extensions ts
+
+echo "=== Cross-Layer Violations ==="
+# Service importing runtime
+grep -rn "from.*runtime" src/services/ --include="*.ts"
+# Repo importing service
+grep -rn "from.*services" src/repo/ --include="*.ts"
+# Utils importing domain
+grep -rn "from.*\.\." src/utils/ --include="*.ts" | grep -Ev "node:|path|crypto|url"
+# Types importing anything
+grep -rn "^import" src/types/ --include="*.ts" | grep -v "from 'zod'"
+
+echo "=== File Sizes ==="
+find src/ -name "*.ts" | xargs wc -l | sort -rn | awk '$1 > 350 { print $0 }' | head -20
+
+echo "=== console.log ==="
+grep -rn "console\." src/ --include="*.ts" | grep -v "src/config/"
+
+echo "=== process.env ==="
+grep -rn "process\.env" src/ --include="*.ts" | grep -v "src/config/env.ts" | grep -v "src/config/sequelize-cli"
+
+echo "=== Unsafe casts on DB data ==="
+grep -rn "as [A-Z][a-zA-Z]*\b" src/repo/ --include="*.ts" | grep -v "as const\|as unknown\|as string\|as number"
+
+echo "=== Missing Zod parse in repo returns ==="
+# Flag findAll/findByPk/findOne/create calls not followed by .parse
+grep -rn "await.*\.\(findAll\|findByPk\|findOne\|create\|update\)" src/repo/ --include="*.ts" -A2 | grep -v "parse\|Schema\|throw\|if"
+
+echo "=== express imports in services ==="
+grep -rn "from 'express'" src/services/ --include="*.ts"
+
+echo "=== offset/skip in repo ==="
+grep -rn "offset:\|\.skip(" src/repo/ --include="*.ts"
+```
+
+## Architecture Structural Tests
+
+```bash
+npx jest tests/architecture/ --no-coverage --verbose
+```
+
+## TypeScript
+
+```bash
+npx tsc --noEmit 2>&1
+```
+
+## ESLint
+
+```bash
+npx eslint src/ --max-warnings=0 2>&1
+```
+
+## Report Format
+
+```
+ARCH VALIDATION — {timestamp}
+
+VIOLATIONS (must fix):
+  [file:line] [description]
+
+WARNINGS (should fix):
+  [file:line] [description]
+
+CLEAN:
+  ✓ No circular imports
+  ✓ No cross-layer violations
+  ✓ TypeScript compiles
+
+OVERALL: ✅ CLEAN / ❌ {N} violations
+```

package/templates/express/.claude/agents/db-optimizer.md

@@ -0,0 +1,72 @@
+---
+name: db-optimizer
+description: Audits repo layer for N+1 queries, missing indexes, and offset pagination. Run before shipping any feature that adds DB queries.
+model: claude-opus-4-8
+tools: [Read, Bash]
+color: orange
+---
+
+You are a PostgreSQL performance engineer reviewing the repository layer.
+
+## Checks
+
+### N+1 Detection
+
+Scan for any `Model.findAll/findOne/findByPk` call inside a `for`/`forEach`/`map` loop.
+
+```bash
+# Flag pattern: await inside loop
+grep -rn "for\|forEach\|\.map" src/repo/ --include="*.ts" -A3 | grep -B2 "await.*\."
+```
+
+For each N+1 found: provide the single-query `include: [{ model: X }]` fix.
+
+### Pagination Audit
+
+Every method returning an array must have cursor pagination.
+
+```bash
+grep -rn "findAll\|list\|getAll\|search" src/repo/ --include="*.ts"
+# Check each: does it accept cursor? does it use Op.lt on createdAt + id?
+grep -rn "offset:\|\.skip(" src/repo/  # should be empty
+```
+
+### Index Audit
+
+For every `where:` clause in repo files, identify the columns filtered.
+Check `src/models/` for index definitions on those columns.
+Flag: any filter column without a corresponding index on a table that will grow.
+
+### Zod Parse Audit
+
+```bash
+grep -rn "return raw\|\.toJSON() as\|raw as " src/repo/
+# Every occurrence is a violation
+```
+
+### Soft Delete Audit
+
+```bash
+# Models should have paranoid: true — findAll auto-filters deleted
+grep -rn "@Table" src/models/ --include="*.ts" | grep -v "paranoid"
+```
+
+## Output Format
+
+```
+APPROVED — all repo patterns correct.
+
+OR
+
+CRITICAL:
+1. N+1 in application.repo.ts:45
+   Current: loads notes for each application in loop
+   Fix: include: [{ model: Note }] on the parent findAll
+
+HIGH:
+2. Missing index in application.repo.ts:89
+   Query: WHERE user_id = ? AND stage = ?
+   Missing: composite index (user_id, stage)
+   Add to model: indexes: [{ fields: ['user_id', 'stage'] }]
+   Migration: CREATE INDEX CONCURRENTLY idx_applications_user_stage ON applications(user_id, stage)
+```

package/templates/express/.claude/agents/doc-gardener.md

@@ -0,0 +1,67 @@
+---
+name: doc-gardener
+description: Scans documentation for staleness and fixes it. Called by /doc-garden skill. Use when docs feel out of sync with reality.
+model: claude-opus-4-8
+tools: [Read, Write, Bash]
+color: green
+---
+
+You are the documentation gardener. Your job is to keep docs in sync with reality.
+
+## What to Check
+
+### AGENTS.md
+
+- Skills table matches files in `.claude/skills/`?
+- Agents table matches files in `.claude/agents/`?
+- Navigation table matches actual `docs/` folders?
+
+### ARCHITECTURE.md
+
+- Source directory structure shown matches actual `src/` layout?
+- Layer definitions match what's in the actual source?
+
+### docs/product-specs/index.md
+
+- Every spec in `draft/` and `ready/` has a row?
+- Status of each row matches the `Status:` field inside the file?
+
+### .env.example
+
+```bash
+# Find all vars in env.ts schema
+grep -o "z\.\(string\|number\|enum\|coerce\)" src/config/env.ts | wc -l
+# Compare with vars in .env.example
+grep -c "^[A-Z]" .env.example
+```
+
+- Every variable in `EnvSchema` has a corresponding line in `.env.example`?
+
+### docs/design-docs/decisions/index.md
+
+- Every `.md` file in `decisions/` is listed in the index table?
+
+## For Each Stale Item
+
+1. Update the document to match reality
+2. Note: `Updated: {file} — {what changed}`
+
+## Output
+
+```
+DOC GARDEN — {timestamp}
+
+Updated:
+  - [file]: [what changed]
+
+No changes needed:
+  - [file] ✓
+```
+
+If anything changed:
+
+```bash
+git add docs/ AGENTS.md ARCHITECTURE.md .env.example
+git commit -m "docs: doc garden — sync stale documentation"
+git push origin main
+```