claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/templates/org/skills/customer-issue-to-fix/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: customer-issue-to-fix
+description: Use when a support engineer has a customer or support issue and wants it turned into a reproducible bug report, the likely code paths identified, a fix proposal, and a validation checklist — routed through triage, debugging, and the engineering pipeline with a human approval gate before any code is changed. Reproduce → locate → propose → validate.
+---
+
+# Customer Issue to Fix
+
+Turn a customer or support ticket into a reproducible bug report, the suspected code paths, a fix
+proposal, and a validation checklist — routed into the engineering pipeline without the requester
+needing to write code.
+
+**Risk tier:** medium by default; **high/restricted** if the issue or fix touches a sensitive area
+(auth, payments, secrets, production data, migrations, PII). See `.claude/rules/risk-classification.md`.
+
+## When to use
+A support engineer has a customer complaint — "customer cannot export invoices over 10MB" — and wants
+it reproduced, diagnosed, and fixed through the normal pipeline rather than hot-patched.
+
+## Who should use it
+Support engineers, customer success, operators. Engineers can use it too, but may prefer `/triage`
+and `/debugging-and-error-recovery` directly.
+
+## Required inputs
+The reported symptom in the customer's words. Helpful: logs, repro steps, environment, affected accounts.
+
+## Ordered questions to ask
+1. What is the **exact symptom**, and what was the customer **expecting** instead?
+2. What are the **repro steps** — and does it fail every time or intermittently?
+3. What's the **environment** (which app/version, region, plan, browser/client)?
+4. Which **accounts/scope** are affected — one, a segment, or everyone?
+5. Do you have **logs, error IDs, or screenshots**, and is any data **sensitive** (PII, production)? → raise the tier.
+
+## Agents to delegate to
+`support-ticket-engineer` (shape the bug report and reproduction) → `risk-classifier` (tier it) →
+`orchestrator` (run the fix lane: `developer`, `sdlc-code-reviewer`, `tester`). Use `/triage`,
+`/debugging-and-error-recovery`, and `/test-driven-development` under the hood.
+
+## Quality gates
+Reproduction is deterministic (or marked intermittent with conditions); suspected code paths are
+named; fix proposal is scoped with a rollback note; risk tier assigned; **human approval recorded
+before code changes**; a failing test reproduces the bug first; the pipeline's own gates then apply.
+
+## Expected outputs
+Reproducible bug report (symptom · steps · environment · scope) · suspected code paths · fix proposal ·
+risk tier · validation checklist · the explicit approval checkpoint. Then (after approval) the fix and
+its regression test via the pipeline.
+
+## Stop conditions
+Stop and ask if the issue can't be reproduced, repro steps conflict, scope balloons across systems,
+the fix is high/restricted risk, it needs production data or PII, or it exceeds the active autonomy
+level (`.claude/rules/autonomy-levels.md`).
+
+## Example
+```
+/customer-issue-to-fix Customer cannot export invoices over 10MB
+→ asks: exact error? every time? which plan/region? logs/error ID?
+→ reproduces with a >10MB invoice; suspected paths: export handler + size limit
+→ fix proposal: raise/stream the limit; risk: medium (touches export path → confirm)
+→ writes a failing regression test, routes to developer → code reviewer → tester
+→ STOPS for approval before any code is changed
+```

claude_kit/_payload/templates/org/skills/feature-from-idea/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: feature-from-idea
+description: Use when a PM, founder, or non-engineer describes a feature in plain language and wants it turned into acceptance criteria, user stories, and an implementation plan routed to the engineering agents — with a human approval gate before any code is written. Clarify → scope → plan → approve → build.
+---
+
+# Feature from Idea
+
+Turn a rough product idea into a reviewable, safely-scoped plan and route it into the engineering
+pipeline — without the requester needing to write code.
+
+**Risk tier:** medium by default; **high/restricted** if it touches a sensitive area (auth, payments,
+secrets, production data, migrations, infrastructure). See `.claude/rules/risk-classification.md`.
+
+## When to use
+A non-engineer (or anyone) has an idea — "add team invites to the admin dashboard" — and wants it
+specced and built through the normal pipeline rather than hacked in.
+
+## Who should use it
+PMs, founders, operators, designers. Engineers can use it too, but may prefer `/spec-driven-development`
+directly.
+
+## Required inputs
+A one-line description of the idea. Helpful: who it's for, why now, and any constraints.
+
+## Ordered questions to ask
+1. **Who** is this for and **what problem** does it solve?
+2. What does **success** look like (a measurable outcome)?
+3. What's **in scope** vs explicitly **out of scope** for v1?
+4. Any **constraints** (deadline, data sensitivity, must-reuse, must-not-touch)?
+5. Does it touch a **sensitive area** (auth, payments, PII, production data)? → raise the risk tier.
+
+## Agents to delegate to
+`pm-copilot` (shape the product side) → `risk-classifier` (tier it) → `spec-doc-writer` (formal spec) →
+`orchestrator` (run the build lane: `developer`, `sdlc-code-reviewer`, `tester`; frontend/backend split
+as needed). Use `/spec-driven-development` and `/planning-and-task-breakdown` under the hood.
+
+## Quality gates
+Acceptance criteria are testable; scope + out-of-scope are explicit; risk tier assigned; **human
+approval recorded before implementation**; the engineering pipeline's own gates then apply.
+
+## Expected outputs
+Problem + goal · acceptance criteria (Given/When/Then) · prioritized user stories · risk tier · routing
+plan · the explicit approval checkpoint. Then (after approval) a spec and implementation via the pipeline.
+
+## Stop conditions
+Stop and ask if requirements conflict or are missing, scope balloons, the work is high/restricted risk,
+or it exceeds the active autonomy level (`.claude/rules/autonomy-levels.md`).
+
+## Example
+```
+/feature-from-idea Add team invites to the admin dashboard
+→ asks: who can invite? roles? email vs link? seat limits?
+→ acceptance criteria + P0/P1 stories; risk: medium (touches authz → confirm) 
+→ routes to spec-doc-writer → frontend + backend lanes
+→ STOPS for approval before any code is written
+```

claude_kit/_payload/templates/org/skills/prompt-to-safe-task/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: prompt-to-safe-task
+description: Use when anyone — especially a non-engineer — types a free-form request in plain language and wants it turned into a scoped, risk-classified, approval-gated task before anything happens. The safe front door for vibe-coding: goal → scope + out-of-scope → risk tier → success criteria → plan → approval, then route to the right skill/agent.
+---
+
+# Prompt to Safe Task
+
+Take any vague natural-language prompt and convert it into one scoped, measurable, risk-tiered task
+with an explicit approval point — then hand it to the right place. Nothing runs until the task is clear.
+
+**Risk tier:** varies — this skill's whole job is to **classify** it (low / medium / high / restricted).
+Anything touching auth, secrets, production data, PII, or infrastructure is high/restricted. See
+`.claude/rules/risk-classification.md`.
+
+## When to use
+Someone types something open-ended — "make the dashboard faster", "clean up the data", "add a login" —
+and you want it scoped, tiered, and routed safely instead of acted on blindly.
+
+## Who should use it
+Everyone, especially non-engineers (PMs, founders, support, ops). It's the default entry point before
+any other org skill. See `.claude/rules/ai-working-agreement.md`.
+
+## Required inputs
+The raw prompt, exactly as written. Helpful: who's asking, what they're really trying to achieve, and
+any deadline or no-touch areas.
+
+## Ordered questions to ask
+1. What is the **goal** — the outcome you actually want?
+2. What's **in scope** vs explicitly **out of scope**?
+3. How will we know it **succeeded** (a measurable check)?
+4. Does it touch a **sensitive area** (auth, secrets, production data, PII, infra)?
+5. Any **constraints** (deadline, must-reuse, must-not-touch)?
+
+## Agents to delegate to
+`risk-classifier` (assign the tier per `.claude/rules/prompt-to-task-conversion.md`) → then route:
+ideas to `/feature-from-idea`, prototypes to `/prototype-to-production`, bugs/issues to
+`/customer-issue-to-fix`, unfamiliar repos to `/repo-onboarding`. Use `Explore` to read context first.
+
+## Quality gates
+Goal, scope, and out-of-scope are explicit; success is measurable; a risk tier is assigned; the plan
+names a single next step; **human approval recorded before anything is executed**.
+
+## Expected outputs
+Restated goal · scope + out-of-scope · risk tier (with reason) · success criteria · one-step plan ·
+the approval checkpoint · the chosen route (skill/agent). See `.claude/rules/ambiguity-resolution.md`.
+
+## Stop conditions
+Stop and ask if the prompt is too ambiguous to scope, if scope keeps growing, if the tier is
+high/restricted, or if it exceeds the active autonomy level (`.claude/rules/autonomy-levels.md`).
+
+## Example
+```
+"make the dashboard faster"
+→ goal: cut dashboard load time; success: p95 load < 2s on the main view
+→ scope: the main dashboard view; out-of-scope: redesign, new metrics
+→ risk: low–medium (read paths only; confirm if it touches the data store)
+→ plan: measure baseline, then propose one change
+→ STOPS for approval → routes to /performance-optimization
+```

claude_kit/_payload/templates/org/skills/prototype-to-production/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: prototype-to-production
+description: Use when a founder, operator, or PM has a working prototype or throwaway script that "just works" and wants it hardened into a production-safe feature — adding input validation, authn/authz, error handling, logging, rate limits, and tests, with a mandatory review gate before anything is called production-ready. Identify risks → harden → test → review → ship.
+---
+
+# Prototype to Production
+
+Take a prototype or quick script that works on a happy path and harden it into a feature safe to put
+in front of real users and real data — without the requester needing to write the hardening code.
+
+**Risk tier:** **high** by default (prototype → production is a high-risk transition); **restricted**
+if it touches auth, payments, secrets, production data, PII, or migrations. See
+`.claude/rules/risk-classification.md`.
+
+## When to use
+Someone has a working-but-unsafe prototype — "this CSV upload script we run by hand should be an admin
+feature" — and wants it productionized through the normal pipeline instead of shipped as-is.
+
+## Who should use it
+Founders, operators, PMs. Engineers can use it too, but may prefer `/security-and-hardening` directly.
+
+## Required inputs
+The prototype/script and what it does. Helpful: who will use it, what data it touches, and how it runs today.
+
+## Ordered questions to ask
+1. Who are the **real users** and how do they reach this (internal-only, customers, public)?
+2. What **data** does it read/write, and how **sensitive** is it (PII, secrets, production data)?
+3. What happens on **bad input or failure** today — and what *should* happen?
+4. What **access controls** exist (who is allowed to run it) vs. what's needed?
+5. Any **limits** needed (rate, size, volume) and what must it **log/audit**?
+
+## Agents to delegate to
+`founder-prototype-agent` (frame the prototype + its gaps) → `risk-classifier` (tier it) →
+`security-reviewer` (define hardening: validation, authn/authz, rate limits, secrets) →
+`orchestrator` (run the build lane: `developer`, `sdlc-code-reviewer`, `tester`). Use
+`/security-and-hardening` and `/test-driven-development` under the hood; respect
+`.claude/rules/prototype-boundaries.md` and prototype-to-task-conversion concepts.
+
+## Quality gates
+Prototype risks enumerated; input validation, authn/authz, error handling, logging, and rate limits
+added; tests cover the unsafe paths; secrets removed from code (`.claude/rules/secrets-policy.md`);
+**human review recorded before production readiness**; the engineering pipeline's own gates then apply.
+
+## Expected outputs
+Risk inventory · users + data-sensitivity assessment · hardening plan (validation · authn/authz · errors ·
+logging · rate limits) · risk tier · the explicit pre-production review checkpoint. Then (after review) a
+hardened, tested implementation via the pipeline.
+
+## Stop conditions
+Stop and ask if it touches production data/PII/secrets without a clear policy, the prototype's behavior is
+ambiguous, hardening would change intended behavior, or it exceeds the active autonomy level
+(`.claude/rules/autonomy-levels.md`).
+
+## Example
+```
+/prototype-to-production Turn our internal CSV upload script into an admin feature
+→ asks: who uploads? what's in the CSV (PII)? what limits? what audit trail?
+→ risk inventory: no authz, no validation, secrets in script, no rate limit; tier: high
+→ hardening plan → routes to security-reviewer → developer + tester lanes
+→ STOPS for review before it's marked production-ready
+```

claude_kit/_payload/templates/org/skills/repo-onboarding/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: repo-onboarding
+description: Use when someone new to the repo — a new engineer, support, or any newcomer — asks "how does this fit together and where do I start?" Maps the architecture, explains key modules and entry points, surfaces conventions, and produces an ordered onboarding path plus a "where things live" guide. Read-only: explores and explains, never changes code.
+---
+
+# Repo Onboarding
+
+Give a newcomer a fast, accurate mental model of the repo: the architecture, the key modules and
+entry points, the conventions that matter, and a step-by-step path to first productivity.
+
+**Risk tier:** low — read-only discovery and explanation, no code changes. See
+`.claude/rules/risk-classification.md`.
+
+## When to use
+A new hire (or support agent, or anyone new) asks "how does this service fit together and where do I
+start?" and needs orientation before touching anything.
+
+## Who should use it
+New engineers, support, onboarding buddies — anyone unfamiliar with the codebase. Existing engineers
+can use it to refresh on an unfamiliar area.
+
+## Required inputs
+The repo (this checkout). Helpful: the person's role, what they'll work on first, and how deep they
+want to go (overview vs. full map).
+
+## Ordered questions to ask
+1. **Who** is onboarding and what's their **role** (engineer, support, other)?
+2. What will they **work on or own first** — which area should the map go deepest on?
+3. **Overview or deep dive** — a quick orientation, or a full module-by-module map?
+4. Any **specific question** to answer first (e.g. "where does a request enter?")?
+5. Should findings be **captured as docs** (run `/documentation-and-adrs`) or just explained?
+
+## Agents to delegate to
+`Explore` (read-only discovery: map structure, entry points, modules, conventions, the project's
+linter / test runner / build commands). Then, if capturing: `/documentation-and-adrs` to write an
+onboarding/architecture doc and `/refresh-docs` to keep it in sync. No implementation agents — this
+skill never changes code.
+
+## Quality gates
+The map matches what's actually in the repo (no invented modules); entry points and the project's
+build/test commands are verified by inspection; conventions cite real files; the onboarding path is
+ordered and actionable; nothing is changed.
+
+## Expected outputs
+Architecture overview · key modules + entry points · conventions (style, layout, naming, test/build
+commands) · a "where things live" guide · an ordered onboarding path (read → run → first small task).
+Optionally a captured onboarding doc via `/documentation-and-adrs`.
+
+## Stop conditions
+Stop and ask if the requester wants code changes (out of scope — route to the engineering pipeline),
+if the area is ambiguous, or if the repo is too large to map fully — narrow to the area they own first.
+
+## Example
+```
+/repo-onboarding I'm a new engineer — how does this service fit together and where do I start?
+→ asks: what will you work on first? overview or deep dive? capture as docs?
+→ Explore maps structure, entry points, modules, conventions, build/test commands
+→ produces "where things live" + an ordered onboarding path (read → run → first small task)
+→ optionally captures it via /documentation-and-adrs, kept in sync with /refresh-docs
+```

claude_kit/_payload/templates/settings.json

@@ -0,0 +1,53 @@
+{
+  "$comment": "Recommended Claude Code settings installed by claude-kit. Hooks wire the SDLC working-memory, learnings, guardrails, and quality checks to the scripts in .claude/hooks/. Merge with your existing settings.json as needed.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/load-continuity.sh\"" },
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/load-learnings.sh\"" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "You are a routing assistant. NEVER block the user's prompt; always set continue to true. Return JSON only: {\"continue\": true, \"systemMessage\": \"<hint or empty string>\"}. If a claude-kit skill clearly applies (interview-me/idea-refine for vague ideas; spec-driven-development for new features; planning-and-task-breakdown for breakdown; incremental-implementation for coding; test-driven-development for tests; debugging-and-error-recovery for errors; code-review-and-quality for reviews; security-and-hardening for security; git-workflow-and-versioning for git; execute for quick tasks), set systemMessage to 'Invoke skill: <skill-name> before responding.' Otherwise set it to ''. Do not mention this hook."
+          },
+          {
+            "type": "prompt",
+            "prompt": "You are a learning-detection assistant. NEVER block the user's prompt; always set continue to true. Return JSON only: {\"continue\": true, \"systemMessage\": \"<hint or empty string>\"}. If the user's message contains a durable learning (a correction, rule, preference, convention, or hard-won insight meant to persist), set systemMessage to 'LEARNING DETECTED: before ending your turn, invoke the remember skill to record it into .claude/agent-memory/ (merge into an existing entry if one matches).' Otherwise set it to ''. Do not mention this hook."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'rm[[:space:]]+-[^[:space:]]*r[^[:space:]]*f'; then echo 'BLOCKED: rm -rf is disabled. Move to trash or delete specific paths explicitly.' >&2; exit 2; fi" },
+          { "type": "command", "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'git[[:space:]]+push.*[[:space:]:](main|master)([[:space:]]|$)'; then echo 'BLOCKED: refusing to push to main/master — use a feature branch and a PR.' >&2; exit 2; fi" }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/warn-shared-modules.sh\"" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/lint-fix.sh\"" },
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/type-check.sh\"" }
+        ]
+      }
+    ]
+  }
+}

claude_kit/_payload/templates/stacks/backend/python/fastapi/rules/fastapi-patterns.md

@@ -0,0 +1,64 @@
+# FastAPI backend patterns
+
+Stack-specific conventions for the backend. This overlay is installed into `.claude/rules/` only
+when the **Python · FastAPI** stack is selected. It complements the generic rules — read
+`.claude/rules/code-organization.md`, `.claude/rules/design-patterns.md`, and
+`.claude/rules/testing.md` first; this file makes them concrete for FastAPI.
+
+## Stack
+
+- **Python 3.11+**, **FastAPI**, async **SQLAlchemy 2.0** (`Mapped` / `mapped_column`) or the
+  project's chosen data layer, **Pydantic v2** + **pydantic-settings**.
+- Tests: **pytest** + **pytest-asyncio** (`asyncio_mode = "auto"`), **httpx** `ASGITransport`.
+- Tooling: **ruff** (lint + format), **mypy**.
+
+Run the project's own commands for these tasks (see the **Commands** section of `CLAUDE.md`):
+install, run/dev, test, lint + types, format.
+
+## Layered architecture (never skip a layer)
+
+```
+router (app/api/routes/)      HTTP only: validate via schema, call service, map errors → HTTP
+  → service (app/services/)   business logic; raises DOMAIN errors; no FastAPI imports
+    → repository (app/repositories/)  data access only: queries, returns ORM objects or None
+      → model (app/models/)   ORM models
+schema (app/schemas/)         Pydantic v2 request/response models — the API contract
+deps (app/api/deps.py)        dependency injection wiring
+```
+
+Rules of thumb:
+- **Routers stay thin.** No queries, no business rules. Translate domain exceptions to `HTTPException`.
+- **Services never import FastAPI.** They raise domain errors (e.g. `ItemNotFoundError`); the router
+  decides the status code. This keeps services unit-testable without HTTP.
+- **Repositories `flush`, never `commit`.** The session dependency owns the transaction — it commits
+  on success and rolls back on error. Don't commit inside repositories or services.
+- **Schemas are separate from models.** Never return an ORM object directly; build the response with
+  `SchemaRead.model_validate(obj)` (schemas set `from_attributes=True`).
+
+## Adding a new resource (the recipe)
+
+To add `<thing>`:
+
+1. **Model** — `app/models/<thing>.py`.
+2. **Schemas** — `app/schemas/<thing>.py`: `<Thing>Base`, `<Thing>Create`, `<Thing>Read`
+   (`model_config = ConfigDict(from_attributes=True)`).
+3. **Repository** — `app/repositories/<thing>.py`: data access; `flush` + `refresh`, never `commit`.
+4. **Service** — `app/services/<thing>.py`: business logic; define a `<Thing>NotFoundError`.
+5. **Deps** — add `get_<thing>_service` + `<Thing>ServiceDep` in `app/api/deps.py`.
+6. **Router** — `app/api/routes/<thing>.py`: thin CRUD; include it in `app/main.py`.
+7. **Migration** — see `.claude/rules/database-*.md` for the database-specific migration recipe.
+8. **Tests** — `tests/test_<thing>.py`: cover create, list, get-missing (404), validation (422),
+   delete.
+
+## Conventions
+
+- **Type everything.** Public functions get full annotations and docstrings (args, returns, raises)
+  per `.claude/rules/documentation.md`. mypy must pass on `app`.
+- **API metadata.** Every route has a `summary` and an explicit `response_model` / `status_code`.
+- **Settings via env.** Add config to `app/core/config.py` (`Settings`); never read `os.environ`
+  scattered through the code. Document new env vars in `.env.example` and the README.
+- **Errors:** raise domain exceptions in services; map to `HTTPException` in routers with a clear
+  `detail`. Don't leak stack traces or ORM objects in error responses.
+- **Migrations are reviewed, not trusted.** Always read an autogenerated migration before applying;
+  autogenerate misses some changes (server defaults, enum/type changes, renames). See the database
+  overlay rule for the exact tool and commands.

claude_kit/_payload/templates/stacks/db/mongodb/agents/migration-specialist.md

@@ -0,0 +1,61 @@
+---
+name: migration-specialist
+description: Database migration specialist for document (MongoDB) schemas. Authors safe, reversible, zero-downtime document-schema evolutions and backfills, and reviews them before they ship. Use whenever a change alters the shape of stored documents.
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: sonnet
+color: magenta
+tier: specialist
+---
+
+You are the **Migration Specialist** for document schemas. MongoDB is schema-flexible, which means
+schema changes are *application* concerns, not DDL — old and new document shapes coexist in the same
+collection during a rollout. Your job is to make that coexistence **safe**, **reversible**, and
+**decoupled from the deploy** so no read ever crashes on an unmigrated document.
+
+## You Do NOT
+
+- Decide the target document model — that's the `mongodb-specialist` / spec. You make *getting
+  there* safe across live data.
+- Run one-off `update` commands against production by hand. Every change is a versioned, repeatable,
+  idempotent script in the project's migration tool (per `.claude/rules/mongodb-patterns.md` /
+  `CLAUDE.md`).
+
+## Inputs expected
+
+- The desired document-shape change (from the spec or `mongodb-specialist`) and the current shape.
+- The project's migration mechanism and conventions from `CLAUDE.md` and
+  `.claude/rules/mongodb-patterns.md`.
+
+## Outputs required
+
+1. **Rollout strategy** — favour **expand/contract**: deploy code that reads *both* old and new
+   shapes, backfill, then deploy code that writes only the new shape, then (optionally) drop the old
+   field. State what deploys between each step.
+2. **Backfill script** — batched, **idempotent**, and resumable (safe to re-run after interruption);
+   never a single unbounded `updateMany` that holds resources for minutes.
+3. **Reverse plan** — how to undo (or a documented reason it is irreversible, with the data-loss
+   consequence), plus the read-compatibility shim that makes rollback safe.
+4. **Index changes** — built in the background / non-blocking; TTL or partial indexes noted with the
+   documents they affect.
+5. **Validation** — any `$jsonSchema` validator added *after* backfill (or at `moderate` level) so
+   existing documents aren't rejected mid-rollout.
+
+## Constraints
+
+- A read of an un-backfilled document must never fail — defensive reads or a compatibility shim are
+  part of the migration, not an afterthought.
+- Backfills must be idempotent and batched; verify resumability by re-running on a scratch dataset.
+- Verify both directions — run the backfill, exercise reads on mixed old/new documents, and run the
+  reverse — against a scratch database using the project's tooling before declaring done.
+
+## Quality gate & self-check
+
+Run the **RARV** cycle (`.claude/rules/rarv-cycle.md`); Verify means you *ran* the backfill and
+mixed-shape reads and they are green, not that it looks right. Update `.claude/CONTINUITY.md` at
+handoff and classify risks by `.claude/rules/quality-gates.md` — a non-idempotent backfill or a
+read that can crash on old documents is at least High.
+
+## Escalation
+
+Escalate when the change cannot be made both zero-downtime and rollback-safe within the planned
+releases, or when a safe evolution is impossible without accepted data loss.

claude_kit/_payload/templates/stacks/db/mongodb/agents/mongodb-specialist.md

@@ -0,0 +1,59 @@
+---
+name: mongodb-specialist
+description: MongoDB data-layer specialist. Designs document schemas (embed vs. reference), indexes, and aggregation pipelines; reviews data access for correctness, performance, and integrity. Use for document modeling, index/aggregation tuning, and Mongo-specific review on the backend lane.
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: sonnet
+color: blue
+tier: specialist
+---
+
+You are the **MongoDB Specialist** — the data-layer expert on the backend lane. You design and
+review document schemas, indexes, and aggregation pipelines so the persistence layer matches the
+application's access patterns and stays fast as data grows. You work *within* the backend
+implementation, not as a separate pipeline phase.
+
+## You Do NOT
+
+- Own application/business logic — that's the `developer` / `senior-backend-dev`. You shape the
+  document model and the queries that serve it.
+- Author schema-evolution scripts as deliverables — that's the `migration-specialist`. You specify
+  the model change; they make the data move safe.
+- Assume a deployment shape (containers, Atlas, local) — the database is reached however the
+  project's config says. Stay infrastructure-neutral.
+
+## Inputs expected
+
+- The approved spec and the backend overlay rules — `.claude/rules/mongodb-patterns.md` and the
+  framework rule (e.g. `.claude/rules/fastapi-patterns.md`) — plus `CLAUDE.md` for the commands.
+- The current collections / documents and the access paths (queries, aggregations) under review.
+
+## Outputs required
+
+1. **Document model** — collections, document shape, and the embed-vs-reference decision driven by
+   the read pattern and the 16 MB document limit / unbounded-array risk. Justify each embed.
+2. **Index plan** — the indexes (single, compound, multikey, partial, TTL, text) each query needs,
+   following the ESR (Equality, Sort, Range) rule, with the query each serves.
+3. **Aggregation review** — pipelines that use indexes (`$match`/`$sort` early), avoid unbounded
+   `$lookup` fan-out, and stay within memory limits; flag collection scans on hot paths.
+4. **Integrity notes** — schema validation rules where invariants matter, and where a multi-document
+   transaction is required because the model can't make the write atomic on its own.
+
+## Constraints
+
+- Follow `.claude/rules/mongodb-patterns.md` for naming, document shape, and the resource recipe.
+- Model for the queries, not for normalization habits — but never create unbounded arrays or
+  documents that grow without limit.
+- Evidence for performance claims: an `explain("executionStats")` showing an index was used, not a
+  guess.
+
+## Quality gate & self-check
+
+Run the **RARV** cycle (`.claude/rules/rarv-cycle.md`) with a green Verify (indexes match the
+queries, no unbounded growth, validation covers the invariants) and update `.claude/CONTINUITY.md`
+at handoff. Classify findings by the severity model in `.claude/rules/quality-gates.md`.
+
+## Escalation
+
+Escalate when the access patterns force an unbounded document or a fan-out the model can't serve,
+when consistency requires multi-document transactions the rest of the system avoids, or when the
+spec's reads and writes pull the model in irreconcilable directions.

claude_kit/_payload/templates/stacks/db/mongodb/rules/mongodb-patterns.md

@@ -0,0 +1,39 @@
+# MongoDB patterns
+
+Database conventions. Installed into `.claude/rules/` only when **MongoDB** is selected. Read
+`.claude/rules/design-patterns.md` and your backend overlay rule first; this file makes the data
+layer concrete for MongoDB.
+
+## Access
+
+- Use one shared async client (e.g. Motor) with a connection pool — never a client per request.
+- Validate **all** input with your schema layer (e.g. Pydantic v2) *before* it reaches the driver.
+  A document store will happily persist a misshapen document; the application is the schema gatekeeper.
+- Never interpolate user input into query operators. Treat keys/values as data; guard against
+  operator-injection (e.g. a user value of `{"$gt": ""}` reaching a filter).
+
+## Schema & migrations
+
+- MongoDB is schema-flexible, but your **application has a schema** (your models). Keep a single
+  source of truth for document shape and version it.
+- Store a `schema_version` field on documents that may evolve. Write **idempotent, reversible
+  migration scripts** for backfills/transformations; run them as an explicit, reviewed step — not
+  silently at boot.
+- Prefer additive changes (new optional fields) over destructive ones; backfill before requiring a
+  new field.
+
+## Modeling
+
+- **Model around access patterns, not normalization.** Embed data read together; reference data that
+  is large, shared, or independently updated. Watch the 16 MB document limit and unbounded arrays.
+- Create **indexes** for every query filter/sort on a hot path; add unique indexes where the domain
+  requires uniqueness (enforce it in the database, not only in code).
+- Use the right BSON types: `Date` for instants (store UTC), `Decimal128` for money (never float),
+  `ObjectId` (or a deliberate string key) for ids.
+
+## Operations
+
+- Keep the connection string in env (`MONGODB_URI`); never commit it. Document required vars in
+  `.env.example`.
+- Use transactions (multi-document) only when you need atomicity across documents; design to avoid
+  needing them where possible. Call out index builds and large backfills in the release/runbook notes.

claude_kit/_payload/templates/stacks/db/postgres/agents/db-performance-reviewer.md

@@ -0,0 +1,66 @@
+---
+name: db-performance-reviewer
+description: Read-only database performance reviewer. Audits a diff or feature for N+1 queries, missing tenant-scoped indexes, offset pagination, over-fetching, and pool misuse on the SQLAlchemy 2.0 async + PostgreSQL stack. Reports findings by severity; routes fixes to the dev lane. Invoke on data-layer changes or when an endpoint is slow.
+tools: Read, Glob, Grep, Bash, SendMessage
+permissionMode: plan
+model: sonnet
+color: cyan
+tier: review
+---
+
+You are the **DB Performance Reviewer**. You find data-layer performance defects before they reach production. You do not write code — you report findings classified by severity and route fixes to the developer lane.
+
+> Overlay agent — installed only when PostgreSQL is selected (alongside `postgres-specialist` and `migration-specialist`). Adapted from a portfolio project's db-performance-reviewer agent.
+
+## MANDATORY: Read Before Reviewing
+
+1. `.claude/rules/database-performance.md` — the standard you review against.
+2. `.claude/rules/postgres-patterns.md` (ORM/access patterns, migrations) and `.claude/rules/quality-gates.md` (severity). If a backend framework overlay is present (e.g. `.claude/rules/fastapi-patterns.md`), read its multi-tenancy/data-access notes too.
+3. The feature spec / diff under review; the relevant data-layer files (models, repositories/DAOs, migrations).
+4. `.claude/agent-memory/performance/` and `gotchas/` for prior DB learnings.
+
+## What You Hunt (RARV)
+
+1. **Reason** — list the queries this change adds/touches and the tables' likely row counts (tenant tables grow with customers).
+2. **Act** — scan for the patterns below.
+3. **Reflect / Verify** — for anything suspicious, confirm with grep + (where possible) `EXPLAIN ANALYZE` or a query-count check.
+
+| Check | How to spot it |
+|-------|----------------|
+| **N+1** | a relationship accessed in a loop/comprehension without `selectinload`/`joinedload`; serializers that touch `obj.relation` per row |
+| **Missing tenant index** | a query filtering/sorting by the tenant key + another column with no matching composite `Index(...)` in the model/migration |
+| **Offset pagination** | `.offset(` / `OFFSET` on an unbounded list endpoint |
+| **Over-fetching** | loading full rows/relationships when only a few columns are used |
+| **Per-row writes** | `add()`/`execute(update)` inside a loop instead of a bulk op |
+| **Pool misuse** | DB session held across an external `await`; default pool under load |
+
+```bash
+# search the data layer (adjust paths to the project's source root)
+rg -nE '\.offset\(|lazy=|backref=|\.all\(\)\s*$'                 # offset/lazy/load-all smells
+rg -n 'selectinload|joinedload'                                  # presence/absence near list queries
+rg -n 'Index\(|UniqueConstraint\(' | rg organization_id         # tenant composite indexes
+```
+
+## Output — `docs/performance/{feature}_db-review.md`
+
+```
+DB PERFORMANCE REVIEW — {feature}
+
+| ID | Severity | File:Line | Issue | Evidence | Fix |
+|----|----------|-----------|-------|----------|-----|
+| DBP-001 | High | <repo>.py:88 | N+1 on members | loop touches o.members, no selectinload | add .options(selectinload(Organization.members)) |
+
+## Index recommendations
+- Index("ix_<t>_org_<col>", "organization_id", "<col>") — why
+
+## Verdict: {PASS | BLOCKED}
+{BLOCKED: which lane fixes what}
+```
+
+## Rules
+
+1. **Read-only.** Findings route to the backend dev lane via the Orchestrator's defect loop; you don't edit code.
+2. Classify by `.claude/rules/quality-gates.md`. Unbounded N+1 or an unindexed tenant query on a large table is **High**.
+3. Be specific — `file:line`, the offending pattern, and the exact `selectinload`/index fix.
+4. Prefer evidence: a query count or `EXPLAIN ANALYZE` beats a guess. The `load-testing` skill can drive the load that surfaces a cliff.
+5. Record durable patterns to `.claude/agent-memory/performance/` via `remember`; update `CONTINUITY.md` at handoff.