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

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

@@ -0,0 +1,56 @@
+---
+name: migration-specialist
+description: Database migration specialist for relational (PostgreSQL) schemas. Authors safe, reversible, zero-downtime schema migrations and backfills, and reviews migrations before they ship. Use whenever a change alters the database schema.
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: sonnet
+color: magenta
+tier: specialist
+---
+
+You are the **Migration Specialist** for relational schemas. When a change touches the database
+shape, you turn the intended schema change into a migration that is **safe to run against live
+data**, **reversible**, and **decoupled from the deploy** so it never causes downtime.
+
+## You Do NOT
+
+- Decide the target schema — that's the `postgres-specialist` / spec. You make *getting there* safe.
+- Hand-edit a live database. Every change is a versioned, repeatable migration in the project's
+  migration tool (whatever `.claude/rules/postgres-patterns.md` / `CLAUDE.md` declares).
+
+## Inputs expected
+
+- The desired schema change (from the spec or `postgres-specialist`) and the current schema.
+- The project's migration command and conventions from `CLAUDE.md` and
+  `.claude/rules/postgres-patterns.md`.
+
+## Outputs required
+
+1. **Forward migration** — the up step, written so it can run while the old code is still serving
+   (additive first: add nullable column / new table / new index, then backfill, then enforce).
+2. **Reverse migration** — a real down step that restores the prior state, or an explicit,
+   documented reason it is irreversible (with the data-loss consequence spelled out).
+3. **Backfill plan** — for new non-null columns or new constraints: batched backfill, then the
+   constraint added `NOT VALID` → `VALIDATE`, so large tables don't lock.
+4. **Expand/contract sequencing** — when a rename or type change is needed, the expand → migrate →
+   contract steps across releases, with what must deploy between them.
+5. **Index changes** — created `CONCURRENTLY` where the table is hot; noted as non-transactional.
+
+## Constraints
+
+- A migration must be runnable independently of the application deploy and safe if it runs slightly
+  before or after it (backward/forward compatible for one release).
+- Long locks are defects: avoid table rewrites and validating constraints in one shot on large
+  tables. Prefer additive + backfill + validate.
+- Verify the down path actually works — apply, roll back, re-apply against a scratch database using
+  the project's migration command before declaring done.
+
+## Quality gate & self-check
+
+Run the **RARV** cycle (`.claude/rules/rarv-cycle.md`); Verify means you *ran* up→down→up and it is
+green, not that it looks right. Update `.claude/CONTINUITY.md` at handoff and classify risks by
+`.claude/rules/quality-gates.md` — an irreversible or table-locking migration is at least High.
+
+## Escalation
+
+Escalate when the change cannot be made both zero-downtime and single-release (it needs an
+expand/contract spanning deploys), or when a safe migration is impossible without accepted data loss.

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

@@ -0,0 +1,58 @@
+---
+name: postgres-specialist
+description: PostgreSQL data-layer specialist. Designs relational schemas, indexes, and queries; reviews data access for correctness, performance, and integrity. Use for schema design, query/index tuning, and Postgres-specific review on the backend lane.
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: sonnet
+color: blue
+tier: specialist
+---
+
+You are the **PostgreSQL Specialist** — the data-layer expert on the backend lane. You design and
+review relational schemas, indexes, and queries so the persistence layer is correct, fast, and
+durable. 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
+  data model and the queries that serve it.
+- Author migrations as deliverables — that's the `migration-specialist`. You specify the schema
+  change; they make it safe and reversible.
+- Assume a deployment shape (containers, managed service, 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/postgres-patterns.md` and the
+  framework rule (e.g. `.claude/rules/fastapi-patterns.md`) — plus `CLAUDE.md` for the commands.
+- The current schema / models and the access paths (repositories, queries) under review.
+
+## Outputs required
+
+1. **Schema design** — tables, columns, types, nullability, defaults, and the constraints that make
+   invalid states unrepresentable (PK/FK, `UNIQUE`, `CHECK`, `NOT NULL`). Prefer the database to
+   enforce invariants over application code.
+2. **Index plan** — the indexes each access path needs (and the composite/partial/covering ones it
+   doesn't), with the query they serve. Call out write-amplification trade-offs.
+3. **Query review** — N+1s, unbounded scans, missing pagination, lock/contention risks; rewrite or
+   `EXPLAIN`-justify hot queries. Parameterized queries only (no string interpolation).
+4. **Integrity & concurrency notes** — transaction boundaries, isolation level where it matters,
+   and how concurrent writers stay consistent.
+
+## Constraints
+
+- Follow `.claude/rules/postgres-patterns.md` for naming, types, and the resource recipe.
+- Every schema change implies a migration — hand the change to the `migration-specialist`; never
+  mutate a live schema ad hoc.
+- Evidence for performance claims: an `EXPLAIN (ANALYZE, BUFFERS)` or a measured query, not a guess.
+
+## Quality gate & self-check
+
+Run the **RARV** cycle (`.claude/rules/rarv-cycle.md`) with a green Verify (constraints hold, the
+indexes match the queries, no unparameterized SQL) and update `.claude/CONTINUITY.md` at handoff.
+Classify findings by the severity model in `.claude/rules/quality-gates.md`.
+
+## Escalation
+
+Escalate when the spec's access patterns can't be served without denormalization or a schema the
+spec doesn't allow, when a needed index would unacceptably slow writes, or when correctness requires
+an isolation level the rest of the system doesn't use.

claude_kit/_payload/templates/stacks/db/postgres/rules/database-performance.md

@@ -0,0 +1,64 @@
+# Database Performance (PostgreSQL + SQLAlchemy 2.0 async)
+
+Performance rules for the data layer. The dominant failure modes in a multi-tenant async app are **N+1 queries**, **missing composite indexes on tenant-scoped lookups**, and **offset pagination on large tables**. Treat these as defects, not nice-to-haves.
+
+> Overlay rule — installed only when PostgreSQL is selected. Complements the general patterns in
+> `.claude/rules/postgres-patterns.md`. Adapted from a portfolio project's database-performance rule.
+
+## N+1 Queries — the #1 offender
+
+```python
+# BAD — lazy-loads relationship once per row (N+1)
+orgs = (await db.execute(select(Organization))).scalars().all()
+for o in orgs:
+    print(o.members)            # fires a query each iteration
+
+# GOOD — eager-load in one round trip
+stmt = select(Organization).options(selectinload(Organization.members))
+orgs = (await db.execute(stmt)).scalars().all()
+```
+
+- **`selectinload`** for collections (one-to-many / many-to-many) — second query with `IN (...)`, no row multiplication.
+- **`joinedload`** for to-one (many-to-one / one-to-one) — single JOIN.
+- Never access a relationship inside a loop without eager-loading it first.
+- Watch async lazy-loading: a lazy attribute access outside the session/greenlet raises — eager-load deliberately.
+
+## Indexes — especially tenant-scoped
+
+- Every tenant-scoped table needs a **composite index leading with the tenant key** (e.g. `organization_id`): `Index("ix_<table>_org_<col>", "organization_id", "<filter_or_sort_col>")`. A bare tenant-key index is not enough when you also filter/sort by another column.
+- Index foreign keys used in JOINs and columns used in `WHERE`, `ORDER BY`, and `UNIQUE` constraints.
+- Unique constraints in a multi-tenant app are usually **per-tenant**: `UniqueConstraint("organization_id", "email")`, not global on `email`.
+- Add the index in the **same migration** as the column/query (see the migration patterns in `.claude/rules/postgres-patterns.md`).
+
+## Pagination
+
+- Prefer **keyset (cursor) pagination** for large or hot lists: `WHERE (organization_id = :org) AND (created_at, id) < (:cursor_ts, :cursor_id) ORDER BY created_at DESC, id DESC LIMIT :n`.
+- `OFFSET` degrades linearly — acceptable only for small, bounded result sets (admin tables). Never `OFFSET` into the thousands.
+- Always `ORDER BY` a unique tiebreaker (e.g. `id`) so pages are stable.
+
+## Query hygiene
+
+- Select only what you need; avoid loading large columns/relationships you won't use. Use `load_only(...)` / `selectinload` selectively.
+- **Bulk** insert/update/delete instead of per-row loops (`insert().values([...])`, `update().where(...)`).
+- Compute `COUNT` with care — `SELECT count(*)` over a huge filtered set is expensive; cache or approximate where product allows.
+- Push filtering/aggregation into SQL; don't pull rows into Python to filter them.
+- Wrap a logical unit of work in one transaction; don't open a transaction per row.
+
+## Connection pool (asyncpg)
+
+- Tune `create_async_engine(pool_size=..., max_overflow=..., pool_pre_ping=True, pool_recycle=...)` to fit the DB's `max_connections` and worker count. Default `pool_size=5` is often too small under load and too large × many workers.
+- Don't hold a DB session across an external `await` (HTTP call) — you pin a pooled connection while idle.
+
+## How to verify
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS) <query>;   -- look for Seq Scan on big tables, high rows, nested loops over many rows
+```
+- Enable SQLAlchemy echo or query logging in dev to count queries per request — a request firing 30 queries for 10 rows is an N+1.
+- Add a regression guard for hot endpoints: assert the query count stays bounded. (See the `load-testing` skill to drive that load.)
+
+## Severity (per `.claude/rules/quality-gates.md`)
+
+- Unbounded N+1 on a list endpoint, or a tenant-scoped query with no supporting index on a large table → **High**.
+- `OFFSET` pagination on an unbounded list, missing FK index used in a hot JOIN → **Medium**.
+- Over-fetching columns, sub-optimal pool sizing → **Low**.

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

@@ -0,0 +1,43 @@
+# PostgreSQL patterns
+
+Database conventions. Installed into `.claude/rules/` only when **PostgreSQL** is selected. Read
+`.claude/rules/design-patterns.md` and your backend overlay rule first; this file makes the data
+layer concrete for Postgres.
+
+## Access
+
+- Use a connection **pool** (the framework's default async engine/pool) — never a connection per
+  request created by hand. One engine per process.
+- The **session/transaction is owned at the request boundary** (a dependency or middleware):
+  commit on success, roll back on error. Repositories `flush`, never `commit`.
+- Parameterise every query. Never build SQL by string-concatenating user input — use bound
+  parameters or the ORM. This is the first line against SQL injection.
+
+## Schema & migrations
+
+- Schema changes go through **versioned migrations** (e.g. Alembic). The database is the source of
+  truth; the migration history is how it got there.
+- **Review every autogenerated migration before applying it.** Autogenerate compares your models to a
+  *running* database and misses server defaults, type/enum changes, and renames.
+- Typical loop (run from the backend project, against a reachable Postgres):
+  - New migration: `alembic revision --autogenerate -m "<message>"` — then read the generated file.
+  - Apply: `alembic upgrade head`
+  - If no database is reachable, hand-write the migration using an existing one as a template.
+- For new non-null columns on populated tables, set a dialect-safe `server_default`
+  (`sa.false()`, `sa.text("now()")`) so existing rows get a value, then drop the default if it
+  shouldn't persist.
+
+## Modeling
+
+- Prefer explicit types: `timestamptz` for instants (store UTC), `numeric` for money (never float),
+  native `enum` or a checked text column for small closed sets, `jsonb` for documents.
+- Add **indexes** for every foreign key and every column used in a `WHERE`/`ORDER BY` on a hot path.
+  Add a unique constraint where the domain requires uniqueness — don't enforce it only in code.
+- Use foreign keys with deliberate `ON DELETE` behavior; don't leave referential integrity to the app.
+
+## Operations
+
+- Keep credentials in env (`DATABASE_URL`); never commit them. Document required vars in
+  `.env.example`.
+- Long/locking migrations (new index, type change) on large tables: prefer `CREATE INDEX
+  CONCURRENTLY` and back-fill in batches; call this out in the release/runbook notes.

claude_kit/_payload/templates/stacks/frontend/react/rules/react-patterns.md

@@ -0,0 +1,63 @@
+# React frontend patterns
+
+Stack-specific conventions for the frontend. This overlay is installed into `.claude/rules/` only
+when the **React** frontend is selected. Read the generic
+`.claude/rules/frontend-best-practices.md`, `.claude/rules/code-organization.md`, and
+`.claude/rules/responsive-and-accessibility.md` first; this file makes them concrete for React.
+
+## Stack
+
+- **React** + **TypeScript** (strict), a modern build/dev server (Vite or your project's choice).
+- Data: a shared HTTP client instance (e.g. `src/api/client.ts`); typed API modules under `src/api/`.
+- Tests: a component testing stack (Vitest/Jest + React Testing Library + `@testing-library/jest-dom`).
+- Tooling: ESLint (flat config) and `tsc --noEmit` for type checking.
+
+Run the project's own scripts for these tasks (see the **Commands** section of `CLAUDE.md`):
+install, run/dev, test, lint, type-check, build.
+
+## Architecture
+
+```
+src/
+  api/client.ts          one configured HTTP client instance (base URL, headers, interceptors)
+  api/<resource>.ts      typed request functions (one module per resource)
+  types/<resource>.ts    shared types — mirror the backend response/request schemas
+  features/<feature>/    a folder per feature:
+    use<Feature>.ts        data hook: state + fetching + actions
+    <Feature>Page.tsx      presentational component (renders the hook's data)
+    <Feature>Page.test.tsx component tests with the API module mocked
+  test/setup.ts          test matcher registration + cleanup
+```
+
+Rules of thumb:
+- **Container/presentational split.** Data fetching and state live in a hook (`use<Feature>`);
+  components render props/hook output and own only local UI state (form fields, toggles).
+- **Never call the HTTP library directly.** Import the shared client so base URL and headers are
+  configured once. Put request functions in `src/api/<resource>.ts`, fully typed.
+- **Types mirror the backend.** Keep `src/types/<resource>.ts` in sync with the backend schemas.
+  A field added on the backend is added here — and in any test fixtures/mocks that build that type
+  (`tsc --noEmit` flags the ones you miss).
+- **Config via env.** Read backend URLs from build-time env (e.g. `import.meta.env.VITE_*`), declared
+  in the env typings. Never hard-code hosts in components.
+- **Accessibility.** Label inputs (`aria-label` or `<label>`), use `role="alert"` for errors, and
+  give actionable controls accessible names — tests select by role/label, which enforces this.
+
+## Adding a feature (the recipe)
+
+1. **Types** — `src/types/<feature>.ts`, matching the backend schema.
+2. **API** — `src/api/<feature>.ts`: typed functions using the shared client.
+3. **Hook** — `src/features/<feature>/use<Feature>.ts`: state + fetching + actions.
+4. **Component** — `src/features/<feature>/<Feature>Page.tsx`: presentational; consumes the hook.
+5. **Wire it in** — render the page from `App.tsx` (or the router).
+6. **Tests** — `<Feature>Page.test.tsx`: mock the API module, then assert rendering, the empty
+   state, and the create/update flow. Select by role/label, not test ids.
+
+## Conventions
+
+- **Type everything.** No `any`; exported functions and hooks have explicit return types and doc
+  comments per `.claude/rules/documentation.md`. Type-check and lint must pass.
+- **Keep tests behavioral.** Mock the API module, drive the UI like a user, and assert what the user
+  sees — not implementation details. When testing-library cleanup is not automatic, register an
+  explicit `afterEach(cleanup)` in `test/setup.ts`.
+- **Small components.** If a component grows past one responsibility, split it; move shared logic
+  into a hook.