claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/commands/lint.md

@@ -0,0 +1,137 @@
+---
+description: Auto-detect and run project linters — supports Go, TypeScript, Python, Rust, and more
+argument-hint: "[backend|frontend|all] [--fix]"
+allowed-tools: Bash
+---
+
+# Lint
+
+## Role
+
+Auto-detect the project's formatters and linters from stack-marker files and run them — optionally scoped to backend or frontend, optionally in `--fix` mode.
+
+## Hard Rules
+
+- Run the formatter before the linter for each stack (format first, then check).
+- Prefer a Makefile `lint` / `fmt` target over the raw tool when one exists — it may carry project-specific setup.
+- Run only the commands in the Step 2 table (and the Step 4 `--fix` variants); never invent linters, flags, or tools not listed there.
+- Treat `--fix` as a modifier combinable with any scope, not as a scope of its own.
+- `--fix` rewrites files in place — apply it only to the Step 4 format and auto-fix commands, never to check-only commands (`go vet`, `tsc --noEmit`, `mypy`, `flake8`).
+- Report every detected in-scope linter, including PASS and unavailable ones; one block per detected in-scope linter.
+- Default to scope `all` for empty or unrecognized input — never guess a narrower scope.
+
+## Step 1 — Parse Arguments
+
+Read the request and derive two independent values from it. Scope and fix are orthogonal: any scope may carry `--fix`.
+
+$ARGUMENTS
+
+- **scope** = the first bare token equal to `backend`, `frontend`, or `all`. Empty input or any unrecognized token → `all`.
+- **fix** = `true` if the token `--fix` appears anywhere in the input, else `false`.
+
+Done-when: `scope` is exactly one of `backend` / `frontend` / `all`, and `fix` is `true` or `false`.
+
+## Step 2 — Detect Linters
+
+Scan the project for stack markers and map each present marker to its commands. Detect with Bash only: `test -f <marker>` for files, `grep -qF '<section>' pyproject.toml` for a config section (fixed-string `-F` so the `[...]` in section names like `[tool.ruff]` is matched literally, not as a regex character class), `command -v <tool>` for a tool on PATH.
+
+| Marker | Format Command | Lint Command | Stack |
+|--------|---------------|-------------|-------|
+| `go.mod` | `gofmt -w .` | `go vet ./...` | Go |
+| `go.mod` + `golangci-lint` in PATH | `gofmt -w .` | `golangci-lint run` | Go (extended) |
+| `package.json` + `.eslintrc*` / `eslint.config.*` | — | `npx eslint .` | ESLint |
+| `package.json` + `tsconfig.json` | — | `npx tsc --noEmit` | TypeScript |
+| `package.json` + prettier config (`.prettierrc*`, `prettier.config.*`, or a `prettier` key in `package.json`) | `npx prettier --write .` | `npx prettier --check .` | Prettier |
+| `pyproject.toml` + `[tool.ruff]` | `ruff format .` | `ruff check .` | Python (ruff) |
+| `pyproject.toml` + `[tool.black]` | `black .` | — | Python (black) |
+| `pyproject.toml` + `[tool.flake8]` / `setup.cfg` | — | `flake8` | Python (flake8) |
+| `pyproject.toml` + `[tool.mypy]` | — | `mypy .` | Python (mypy) |
+| `Cargo.toml` | `cargo fmt` | `cargo clippy -- -D warnings` | Rust |
+| `Makefile` with `lint` target | — | `make lint` | Makefile |
+| `Makefile` with `fmt` target | `make fmt` | — | Makefile |
+
+A `—` cell means that stack has no command for that slot — skip it. If a `Makefile` with `lint` / `fmt` targets exists, prefer them over the raw tool for that slot — they may include project-specific setup.
+
+Done-when: every marker present in the repo is mapped to its format/lint commands; the set of detected linters is fixed.
+
+## Step 3 — Resolve Scope Directory
+
+Pick where to run based on `scope` from Step 1:
+
+- **`all`** — run every linter detected in Step 2. For each directory that carries its own markers (the repo root, plus each depth-1 subdirectory that has markers in a monorepo), run that directory's linters from within it. Enter each marked directory in turn; no single `cd`.
+- **`backend`** — locate the backend directory, then run only the linters detected there:
+  1. A backend directory carries `go.mod`, `pyproject.toml`, `Cargo.toml`, or a `package.json` with no frontend-framework dependency.
+  2. Check the repo root first; if it has no backend marker, scan direct subdirectories (depth 1) for one.
+  3. Exactly one match → `cd` into it. More than one → list the candidates and ask which to lint. Zero → fall back to `all` and note the fallback.
+- **`frontend`** — locate the frontend directory, then run only the linters detected there:
+  1. A frontend directory has a `package.json` that declares a frontend framework — detect with `grep -E '"(react|vue|svelte|next|nuxt|@angular/core|solid-js|astro|vite)"' package.json`.
+  2. Check the repo root first, then direct subdirectories (depth 1).
+  3. Exactly one match → `cd` into it. More than one → list the candidates and ask which to lint. Zero → fall back to `all` and note the fallback.
+
+Done-when: the working directory (or set of directories) for the chosen scope is fixed, or the run has fallen back to `all`.
+
+## Step 4 — Run Linters
+
+For each in-scope linter, run format first, then check. Skip any table cell shown as `—`.
+
+- **fix = false** — run the linter's Format Command then its Lint Command from the Step 2 table.
+- **fix = true** — replace the table's Format Command with the auto-fix variant below, then still run the Lint Command. A detected linter with no fix variant listed here runs its table Lint Command unchanged (check-only):
+  - Go: `gofmt -w .`
+  - ESLint: `npx eslint . --fix`
+  - Prettier: `npx prettier --write .`
+  - ruff: `ruff check . --fix && ruff format .`
+  - black: `black .`
+  - Rust: `cargo fmt` then `cargo clippy --fix --allow-dirty`
+
+For a TypeScript project, run both ESLint and `npx tsc --noEmit` — ESLint catches style, `tsc` catches types. `tsc --noEmit`, `mypy`, `flake8`, and `go vet` are check-only, so `--fix` leaves them unchanged.
+
+If a tool named in the table is not installed (command not found), mark it `unavailable` and continue with the remaining linters.
+
+Done-when: every detected in-scope linter has either produced output or been marked `unavailable`.
+
+## Output
+
+Emit exactly this structure — one `### <Linter Name>` block per detected in-scope linter, then one `### Summary`:
+
+```
+## Lint Results
+
+### [Linter Name]
+- Command: `[exact command run]`
+- Result: PASS / N issues found / unavailable
+- Details: [first 10 issues if any]
+
+### Summary
+- Format: PASS/FAIL
+- Lint: PASS/FAIL (N issues)
+- Types: PASS/FAIL (N errors)
+```
+
+Filled example:
+
+```
+## Lint Results
+
+### Go (extended)
+- Command: `golangci-lint run`
+- Result: 2 issues found
+- Details: cmd/main.go:14 ineffassign · internal/db/pool.go:88 errcheck
+
+### Summary
+- Format: PASS
+- Lint: FAIL (2 issues)
+- Types: PASS
+```
+
+## Done ONLY when
+
+- [ ] Every linter detected in Step 2 that falls within scope was run, or explicitly reported as `unavailable`.
+- [ ] The report has one `### <Linter>` block per detected in-scope linter — block count equals the detected in-scope linter count.
+
+## Recap — non-negotiables
+
+- Format before check, per stack; Makefile `lint` / `fmt` targets win over raw tools.
+- Run only Step 2 table commands and Step 4 `--fix` variants — `--fix` is a modifier that rewrites files in place, never a scope.
+- Empty or unrecognized scope → `all`; never narrow by guessing.
+- For TypeScript run both ESLint and `tsc --noEmit`; check-only tools stay unchanged under `--fix`.
+- Not done until every in-scope linter ran or was reported `unavailable`.

package/packages/core/commands/migrate.md

@@ -0,0 +1,146 @@
+---
+description: Apply or rollback database migrations — auto-detects migration tool
+argument-hint: "[up|down|down N|status]"
+allowed-tools: Bash, Read, Glob
+---
+
+# Database Migrations
+
+Role: apply, roll back, or report the status of database migrations, auto-detecting the project's migration tool. Rollbacks destroy data — every destructive step is gated behind explicit user confirmation.
+
+## Hard Rules
+
+1. **Destructive-action gate**: before running ANY command that can destroy data (`down`, `rollback`, `downgrade`, `reset`, `drop`, any `--force` flag), STOP and ask the user for confirmation AT THAT STEP. Show the exact command and exactly what will be lost (which migrations revert; which tables/columns they drop, from reading the migration files). Run only after the user explicitly agrees.
+2. NEVER run `npx prisma migrate reset` (or any tool's reset/drop-and-recreate) as a routine rollback — it drops the ENTIRE database. Offer it only as a clearly labeled last resort, and only run it after the user explicitly accepts total data loss.
+3. NEVER guess a database connection string. Locate it (Step 2) or report where you looked and ask the user.
+4. Run the tool's read-only `status` command before any `up` or `down`, whenever the tool has one.
+5. If no migration tool is detected, report that and stop. If the detected tool has no true rollback (Prisma, Drizzle), follow its down branch in Step 4 — present only the options listed there, auto-run none of them, and do not improvise a workaround.
+6. For `down N` with N > 1: in the confirmation (Rule 1), restate N and list the N migrations that will be reverted; if the user's answer does not clearly cover N migrations, do not run.
+7. Prefer Makefile migration targets over raw tool commands — they may include environment setup.
+
+## Arguments
+
+Requested action: $ARGUMENTS
+
+| Argument | Action |
+|----------|--------|
+| (empty) | `up` |
+| `up` | apply all pending migrations |
+| `down` | rollback 1 migration (confirmation-gated) |
+| `down N` | rollback N migrations (confirmation-gated, Rule 6) |
+| `status` | read-only status report |
+| anything else | report `Unknown action: <arg>` with the list above, stop |
+
+## Step 1 — Detect Migration Tool
+
+Check markers top to bottom; first match wins (Makefile first, per Rule 7):
+
+| Marker | Tool | Apply Command |
+|--------|------|---------------|
+| `Makefile` with `migrate-up` target | Make | `make migrate-up` |
+| `Makefile` with `migrate` target | Make | `make migrate` |
+| `golang-migrate` in deps, or numbered `.sql` up/down pairs | golang-migrate | `migrate -path <dir> -database <url> up` |
+| `dbmate` in deps or PATH | dbmate | `dbmate up` |
+| `alembic.ini` or `alembic/` | Alembic | `alembic upgrade head` |
+| `prisma/` + `package.json` | Prisma | `npx prisma migrate deploy` |
+| `db/migrate/` + `Rakefile` | Rails | `rails db:migrate` |
+| `drizzle.config.ts` | Drizzle | `npx drizzle-kit migrate` |
+| `knexfile.js` / `knexfile.ts` | Knex | `npx knex migrate:latest` |
+
+Done when: exactly one tool selected — or no marker matched and you reported `No migration tool detected — checked: [list of markers]` and stopped.
+
+## Step 2 — Locate Connection & Check Infra
+
+Skip for tools that read their own config automatically when it is already present (Alembic `alembic.ini`, Prisma `schema.prisma` datasource, Knex `knexfile.*`, Rails). For tools needing an explicit URL or env (golang-migrate `-database`, dbmate/`DATABASE_URL`), find the real value — check in order:
+
+1. Makefile variables used by the migrate target
+2. `.env` / `.env.local`
+3. `docker-compose*.yml` environment blocks
+4. Tool config files (`alembic.ini` `sqlalchemy.url`, `prisma/schema.prisma`, `knexfile.*`)
+
+Not found in any of these → apply Rule 3: report the four places checked, ask the user, stop.
+
+Migrations require a running database. If the connection points at local infra (docker-compose service, localhost), verify it is reachable (e.g. the compose service is up); if not, tell the user to start infrastructure first and stop.
+
+Done when: connection source identified (never guessed) and DB assumed reachable — or you stopped and asked.
+
+## Step 3 — Status First
+
+If the action is `status`, or before executing `up`/`down` (Rule 4): run the status command and capture its output.
+
+| Tool | Status Command |
+|------|----------------|
+| Make | `migrate-status`/`status` target if the Makefile has one; else use the underlying tool's row if identifiable; else note "no status command" |
+| golang-migrate | `migrate -path <dir> -database <url> version` |
+| dbmate | `dbmate status` |
+| Alembic | `alembic current` + `alembic history` |
+| Prisma | `npx prisma migrate status` |
+| Rails | `rails db:migrate:status` |
+| Drizzle | none — note "status not supported by drizzle-kit"; for `status` action, list local migration files instead |
+| Knex | `npx knex migrate:list` |
+
+If the action is `status`, go straight to Step 5 after this.
+
+Done when: status output captured, or "no status command for [tool]" noted.
+
+## Step 4 — Execute Action
+
+### up
+
+Run the Apply Command from Step 1. No confirmation gate — applying pending migrations is the normal forward path.
+
+### down / down N
+
+1. From Step 3 status output (or the migration directory), identify by name the migration(s) that will be reverted; read them to state what schema/data is lost.
+2. Apply Rule 1 (and Rule 6 if N > 1): show the exact rollback command, the migration names, and the concrete loss. Wait for explicit user agreement.
+3. User declined or did not clearly agree → record "user declined", go to Step 5.
+4. User agreed → run the rollback command:
+
+| Tool | Rollback 1 | Rollback N |
+|------|-----------|------------|
+| Make | `make migrate-down` (or `make migrate-rollback`) | run the target N times, unless it accepts a count |
+| golang-migrate | `migrate -path <dir> -database <url> down 1` | `migrate ... down N` |
+| dbmate | `dbmate down` | run `dbmate down` N times |
+| Alembic | `alembic downgrade -1` | `alembic downgrade -N` |
+| Prisma | **no true down** — see Prisma branch below | same |
+| Rails | `rails db:rollback` | `rails db:rollback STEP=N` |
+| Drizzle | **not supported** — see Drizzle branch below | same |
+| Knex | `npx knex migrate:rollback` — reverts the last **batch**, which may contain more than one migration; list every migration in that batch in the confirmation | run `npx knex migrate:rollback` N times (each run reverts one batch) |
+
+### Prisma down branch
+
+Prisma has no down command. Present exactly these options to the user and wait — never auto-run any of them:
+
+1. **Generate a down script**: use `npx prisma migrate diff` (check `--help` for the flag set in the installed version) to produce reverse SQL from the current schema vs. the target state; the user reviews and applies it manually.
+2. **Restore from a database backup** taken before the migration.
+3. **LAST RESORT — `npx prisma migrate reset`**: drops the ENTIRE database and replays all migrations. ALL data is lost. Runs only under Rules 1–2: the user must explicitly accept total data loss in response to a message that says so in those words.
+
+### Drizzle down branch
+
+drizzle-kit has no rollback command. Report: "Drizzle does not support rollback via drizzle-kit. Options: write a reverse SQL migration and apply it forward, or restore from backup." Stop (Rule 5).
+
+Done when: `up` — apply command ran, exit code and output captured; `down` — rollback ran after confirmation, or you stopped with "user declined" / "unsupported" recorded.
+
+## Step 5 — Report
+
+Emit exactly this template:
+
+```
+## Migration Result
+
+- Tool: [detected tool]
+- Action: [up/down/down N/status]
+- Command: `[exact command run]` — or "not run: [user declined | unsupported for this tool | no tool detected | connection not found]"
+- Confirmation: [not required (up/status) | user confirmed: "<quoted answer>" | user declined]
+- Result: [success/failure — paste the real command output, not a summary]
+- Current version: [from status output, if available]
+```
+
+Done when: the report matches the template, with `Result` taken from actual command output.
+
+## Recap
+
+- Destructive commands run only after explicit user confirmation at that step, with the exact command and concrete data loss spelled out.
+- `prisma migrate reset` is never a routine rollback — last resort, explicit total-data-loss consent only.
+- Connection strings are located (Makefile/.env/compose/tool config) or asked for — never guessed.
+- Status first where supported; no tool detected → report and stop; no true down (Prisma/Drizzle) → only the Step 4 branch options, nothing auto-run.

package/packages/core/commands/new-migration.md

@@ -0,0 +1,182 @@
+---
+description: Scaffold a new database migration file pair (up + down) with auto-detection of migration tool and numbering
+argument-hint: <migration-description>
+allowed-tools: Bash, Read, Write, Glob
+---
+
+# New Migration
+
+## Role
+
+Scaffold a database migration that matches the project's existing migration tool, directory, numbering scheme, and SQL dialect.
+
+Migration description: $ARGUMENTS
+
+## Hard Rules
+
+1. NEVER invent a migrations directory, numbering scheme, or naming pattern — copy every convention from existing migrations, or ask the user (Step 2).
+2. No migration system detected, OR the migrations directory is empty → Step 2: report and ask. Create zero files on that branch.
+3. Match the project's SQL dialect (Step 3). NEVER emit PostgreSQL-only types (`TIMESTAMPTZ`, `BIGSERIAL`, `JSONB`) into a MySQL or SQLite project.
+4. SQL-file tools always get BOTH files: `.up.sql` and `.down.sql`. Down is the exact reverse of up.
+5. Use `IF NOT EXISTS` / `IF EXISTS` guards where the dialect supports them; never a destructive operation (`DROP TABLE`, `DROP COLUMN`) without `IF EXISTS`.
+6. Report only after verifying the created files exist on disk (`ls` or Read).
+
+## Step 1 — Detect Migration System
+
+Check each marker with Glob. A row matches only if the directory contains at least one existing migration file:
+
+| Marker | Tool | Directory | Naming Pattern |
+|--------|------|-----------|----------------|
+| `backend/migrations/*.sql` with numbered names | golang-migrate | `backend/migrations/` | `000NNN_desc.{up,down}.sql` |
+| `migrations/*.sql` with numbered names | golang-migrate | `migrations/` | `000NNN_desc.{up,down}.sql` |
+| `db/migrations/*.sql` | golang-migrate / dbmate | `db/migrations/` | `NNNNNN_desc.{up,down}.sql` |
+| `db/migrate/*.rb` | Rails | `db/migrate/` | `YYYYMMDDHHMMSS_desc.rb` |
+| `alembic/versions/*.py` | Alembic | `alembic/versions/` | `rev_desc.py` |
+| `prisma/migrations/` | Prisma | `prisma/migrations/` | `YYYYMMDDHHMMSS_desc/` |
+| `drizzle/` + `drizzle.config.ts` | Drizzle | `drizzle/` | `NNNN_desc.sql` |
+
+Branches — exactly one applies:
+- Exactly one row matches → Step 3.
+- Two or more rows match → list the candidate directories, ask the user which one to use, wait for the answer.
+- No row matches, or a directory exists but holds no migration files → Step 2.
+
+Done when: you have one confirmed tool + directory containing existing migrations, or you branched to Step 2.
+
+## Step 2 — No Migration System Detected (ask, never invent)
+
+Runs only when Step 1 found no system or an empty migrations directory. Do NOT create files or pick a numbering scheme yourself.
+
+1. Report which locations you searched (the Directory column of the Step 1 table, plus any project-specific paths you globbed).
+2. List tool options that match the detected stack:
+   - `go.mod` present → golang-migrate or dbmate
+   - `package.json` present → Prisma, Drizzle, or dbmate
+   - `pyproject.toml` / `requirements.txt` present → Alembic
+   - `Gemfile` present → Rails built-in migrations
+3. Ask the user which tool and directory to use. If a tool config exists but its directory is empty, also ask which numbering scheme to start with (sequential `000001` vs timestamp). Then STOP — proceed only after they answer.
+
+Done when: the report + question are posted and zero files were created.
+
+## Step 3 — Detect SQL Dialect
+
+Applies to raw-SQL tools (golang-migrate, dbmate). For Rails / Alembic / Prisma / Drizzle set dialect = `n/a` (the tool or schema owns the SQL) and go to Step 4.
+
+Check in priority order; first signal wins:
+1. **Existing migration SQL** (search the migrations directory with `grep`): `TIMESTAMPTZ` / `JSONB` / `BIGSERIAL` → PostgreSQL · `AUTO_INCREMENT` / `ENGINE=` → MySQL · `AUTOINCREMENT` → SQLite.
+2. **Database driver in dependencies**: `go.mod`: `jackc/pgx` or `lib/pq` → PostgreSQL, `go-sql-driver/mysql` → MySQL, `mattn/go-sqlite3` or `modernc.org/sqlite` → SQLite · `package.json`: `pg` or `postgres` → PostgreSQL, `mysql2` → MySQL, `better-sqlite3` → SQLite · Python deps: `psycopg`/`asyncpg` → PostgreSQL, `pymysql`/`mysqlclient` → MySQL.
+3. **Connection string scheme** in `.env*` or config files: `postgres://`/`postgresql://` → PostgreSQL · `mysql://` → MySQL · `sqlite:` → SQLite.
+
+No signal, or signals conflict → dialect = `unknown`: write `dialect: unknown — match existing schema` in the template comment and in the report. Do not guess types.
+
+Done when: dialect is set to exactly one of `postgresql` / `mysql` / `sqlite` / `n/a` / `unknown`.
+
+## Step 4 — Compute the Next Number
+
+Sequential-numbered tools (golang-migrate, dbmate, Drizzle SQL files) only. Timestamp- or hash-named tools (Rails, Prisma, Alembic) get their identifier from the generator in Step 6 — skip this step. An empty directory cannot reach this step (Step 1 routes it to Step 2).
+
+```bash
+# Highest existing numeric prefix. Numeric sort — plain lexicographic sort mis-orders mixed zero-padding.
+ls <migrations_dir> | grep -oE '^[0-9]+' | sort -n | tail -1
+```
+
+Next number = highest + 1, zero-padded to the same width as the prefix of the newest existing migration (latest is `000042_...` → next is `000043`, width 6).
+
+Done when: next identifier computed and its padding width equals the newest existing migration's prefix width.
+
+## Step 5 — Build the Filename
+
+Convert the migration description to `snake_case`: lowercase, spaces and hyphens become underscores, drop other punctuation.
+- "add user preferences" → `add_user_preferences`
+- "Create events table" → `create_events_table`
+
+Done when: filename slug produced.
+
+## Step 6 — Create the Migration
+
+### golang-migrate / dbmate — Write both files in the detected directory
+
+**Up** (`<NNN>_<slug>.up.sql`):
+```sql
+-- <NNN>_<slug>.up.sql
+-- Description: <migration description>
+-- Follow "Migration Conventions" below (dialect: <detected dialect>)
+
+-- TODO: migration SQL
+```
+
+**Down** (`<NNN>_<slug>.down.sql`):
+```sql
+-- <NNN>_<slug>.down.sql
+-- Rollback: exact reverse of the up migration, statements in reverse order
+
+-- TODO: reverse every statement from the up file
+```
+
+### Rails
+Run `bin/rails generate migration <SlugInCamelCase>` — the generator assigns the timestamp.
+
+### Alembic
+`alembic revision --autogenerate -m "<slug>"` if autogenerate is configured; otherwise `alembic revision -m "<slug>"`.
+
+### Prisma
+Edit `prisma/schema.prisma`, then run `npx prisma migrate dev --name <slug>`.
+
+### Drizzle
+Edit the schema file, then run the project's drizzle-kit generate script — check `package.json` scripts for its exact name.
+
+Done when: SQL tools — both files exist on disk (verified with `ls`); generator tools — the command ran and printed the created file path.
+
+## Step 7 — Report
+
+Verify the created paths exist, then fill this template exactly:
+
+```
+## Migration Scaffolded
+
+Tool: <tool> · Directory: <dir> · Dialect: <postgresql|mysql|sqlite|n/a|unknown>
+
+Created:
+- <path to up file>
+- <path to down file>   (SQL tools; generator tools: path(s) from the tool's output)
+
+Next steps:
+1. Edit the file(s): replace the TODO with your SQL / schema change.
+2. Apply: <apply command>
+3. Confirm the down migration rolls back cleanly before committing.
+```
+
+Apply command: prefer the project's documented one (Makefile target, `package.json` script, README). If none is documented, use the tool default: `migrate -path <dir> -database "$DATABASE_URL" up` · `dbmate up` · `alembic upgrade head` · `bin/rails db:migrate` · `npx prisma migrate dev`.
+
+## Migration Conventions
+
+Existing tables win: when this table conflicts with what existing migrations already do, copy the existing migrations.
+
+| Need | PostgreSQL | MySQL | SQLite |
+|------|------------|-------|--------|
+| Timestamps | `TIMESTAMPTZ` | `DATETIME(6)` | `TEXT` (ISO 8601) |
+| Auto-increment PK | `BIGSERIAL` (or `UUID`) | `BIGINT AUTO_INCREMENT` | `INTEGER PRIMARY KEY` |
+| Flexible metadata | `JSONB` | `JSON` | `TEXT` (JSON string) |
+
+Dialect-neutral rules:
+- `IF NOT EXISTS` / `IF EXISTS` on every CREATE/DROP the dialect supports.
+- New tables get `created_at` (timestamp type from the table above) `NOT NULL` with a current-timestamp default.
+- `CREATE INDEX` for columns that will be filtered or joined on.
+- Foreign keys: `ON DELETE CASCADE` when child rows are meaningless without the parent; `ON DELETE SET NULL` when they must outlive it.
+- Down migration is the exact reverse of up, statements in reverse order.
+- Destructive operations (`DROP TABLE`, `DROP COLUMN`) only with `IF EXISTS`.
+
+## Done ONLY when
+
+- [ ] Scaffold branch: created file(s) exist on disk — verified with `ls`/Read, not from memory; SQL tools have BOTH `.up.sql` and `.down.sql`.
+- [ ] The down file mirrors the up file (exact reverse).
+- [ ] Report emitted with exact paths, dialect, and apply command.
+- [ ] Ask branch (Step 2) instead: searched locations reported, stack-matched options listed, question asked, zero files created.
+
+Not all applicable boxes checked → say what is missing; do not claim completion.
+
+## Recap — non-negotiables
+
+- Conventions come from existing migrations or the user — never invented; no system or empty directory → Step 2 ask.
+- Dialect-gate all SQL: PostgreSQL types only on PostgreSQL (see Migration Conventions).
+- SQL tools: always an up + down pair; down reverses up exactly.
+- `IF NOT EXISTS` / `IF EXISTS` guards; no destructive operation without `IF EXISTS`.
+- Verify files on disk before reporting.

package/packages/core/commands/pair.md

@@ -0,0 +1,209 @@
+---
+description: AI pair programming — switch between Driver, Navigator, TDD, Review, and Debug modes
+argument-hint: "<mode: driver|navigator|tdd|review|debug> [task]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Pair Programming
+
+## Role
+
+Run an interactive pair-programming session with the user in one of five modes. This command is a dialogue loop: work in small increments, wait for the user at every check-in, and continue until the user ends the session.
+
+## Hard Rules
+
+1. This is an interactive session — stop and WAIT for the user's reply at every check-in point. Never push through an entire task without user responses.
+2. Driver mode: never write more than ~50 lines of code without checking in.
+3. Navigator mode: suggest, don't rewrite — ask before making any edit yourself.
+4. Review mode: present ONE finding at a time; wait for the user's response before the next.
+5. Never manufacture issues — if code is clean, say "Looks good". 0 findings is a valid result.
+6. Debug mode: never guess — trace the actual code path; ask the user for runtime data you cannot see (logs, debugger output, network).
+7. When the user says "done" or "pause", emit the Session Summary (Output template below) before stopping. No silent exits.
+
+## Step 1 — Select Mode
+
+Arguments: $ARGUMENTS
+
+The first word is the mode; the remainder is the task description. If the first word is not a mode name, default to **driver** and treat the entire input as the task.
+
+| Input | Mode | Who codes | Who reviews |
+|-------|------|-----------|-------------|
+| `driver` or empty | Driver | Claude writes code | User guides direction |
+| `navigator` | Navigator | User writes code | Claude reviews each change |
+| `tdd` | TDD Ping-Pong | Alternating | Default: Claude writes tests, user implements (Option A) |
+| `review` | Review | — | Claude reviews recent changes with dialogue |
+| `debug` | Debug | Collaborative | Claude traces execution, user provides runtime context |
+
+Done when: mode is selected.
+
+## Step 2 — Setup
+
+1. Read `CLAUDE.md` and relevant `docs/architecture/` files (skip silently if absent).
+2. Detect project stack (Go, TypeScript, Python, Rust).
+3. Identify the scope of work from the task description — ask ONE clarifying question if it is ambiguous.
+4. Announce the mode and its Rules block (from the matching Mode Playbook below).
+
+Done when: mode and ground rules are announced to the user.
+
+## Step 3 — Run the Mode Loop
+
+Execute the Mode Playbook matching the selected mode. Stay in the loop and honor these session controls at any time:
+
+| User says | Action |
+|-----------|--------|
+| "switch to X" / "let's do X" | Announce mode X and its rules, continue in mode X |
+| "pause" | Go to Step 4 (emit Session Summary), then stop |
+| "resume" | Restate where you left off, continue in the previous mode |
+| "done" | Go to Step 4 (emit Session Summary), end session |
+
+Done when: the user says "pause" or "done".
+
+### Mode Playbook — Driver
+
+Claude writes code, user steers.
+
+Process:
+1. **Propose approach** — brief plan (3–5 bullet points), wait for user OK.
+2. **Implement incrementally** — write code in small chunks (1 function or 1 component at a time).
+3. **Pause after each chunk** — show what was written, ask: "Continue with [next piece], or adjust?"
+4. Repeat 2–3 until the scope is complete. Hard Rule 2 applies: ≤50 lines between check-ins.
+
+Rules:
+- Small increments, frequent check-ins.
+- Explain non-obvious decisions inline (1-line comment, not a paragraph).
+- If user says "faster" — reduce check-in frequency, batch larger chunks.
+- If user says "slower" — break into smaller pieces, explain more.
+
+### Mode Playbook — Navigator
+
+User writes code, Claude reviews in real-time.
+
+Process:
+1. **Set scope** — agree on what the user will implement.
+2. **Watch changes** — after each user edit, review for:
+   - Logic errors or missed edge cases
+   - Convention violations (from CLAUDE.md)
+   - Security issues (injection, auth bypass)
+   - Missing error handling
+3. **Suggest, don't rewrite** — point out issues with specific suggestions:
+   ```
+   Line 42: This fetch has no error handling.
+   Suggestion: wrap in try/catch, return error to caller.
+   ```
+4. **Track progress** — remind user of remaining scope items.
+
+Rules:
+- Only flag real issues, not style preferences.
+- Use [CRITICAL], [WARNING], [SUGGESTION] severity levels.
+- If code is clean, say "Looks good" — don't manufacture issues (Hard Rule 5).
+- Ask before making any edits yourself (Hard Rule 3).
+
+### Mode Playbook — TDD Ping-Pong
+
+Alternating between writing tests and implementation.
+
+Default: **Option A** (Claude writes tests first). Use Option B only if the user says they will write the tests.
+
+Option A — Claude writes tests first:
+1. Claude writes a failing test for the next requirement.
+2. User implements code to make it pass.
+3. Claude reviews the implementation.
+4. Claude writes the next failing test.
+5. Repeat until all requirements covered.
+
+Option B — User writes tests first:
+1. User writes a failing test.
+2. Claude implements the minimal code to pass.
+3. User reviews and writes the next test.
+4. Repeat until all requirements covered.
+
+Rules:
+- Each test covers ONE behavior.
+- Tests must fail before implementation (Red-Green-Refactor).
+- After 3–5 cycles, pause for refactoring if needed.
+- Name tests: `should [behavior] when [condition]`.
+- Use the project's existing test framework and patterns.
+
+### Mode Playbook — Review
+
+Interactive code review with dialogue.
+
+Process:
+1. **Identify scope** — use `git diff` or user-specified files.
+2. **First pass** — read all changed files, note issues.
+3. **Present findings one at a time** (Hard Rule 4):
+   ```
+   [WARNING] src/handler.go:45 — Missing context propagation
+   The handler creates a new context instead of using the request context.
+   This breaks tracing and cancellation.
+
+   Fix: Use r.Context() instead of context.Background()
+
+   Agree? Should I fix it?
+   ```
+4. **Wait for user response** before moving to the next finding.
+5. **Apply agreed fixes** immediately.
+6. **Summary** — list all findings, which were fixed, which were deferred.
+
+Rules:
+- If user disagrees, accept and move on (they may have context you don't).
+- After all findings, offer to run linters/tests.
+
+### Mode Playbook — Debug
+
+Collaborative debugging with execution tracing.
+
+Process:
+1. **Reproduce** — understand the bug: expected vs actual behavior.
+2. **Hypothesize** — propose 2–3 likely causes based on code structure.
+3. **Trace** — read code along the execution path, noting:
+   - Where data transforms
+   - Where errors could be swallowed
+   - Where state could be unexpected
+4. **Narrow down** — ask user targeted questions:
+   - "Does the error happen on first request or subsequent?"
+   - "What does the log show at [specific point]?"
+   - "Can you check the value of X in the debugger?"
+5. **Fix** — once root cause is found, propose a minimal fix.
+6. **Verify** — run tests, check the fix doesn't break related functionality.
+
+Rules:
+- Don't guess — trace the actual code path (Hard Rule 6).
+- Ask user for runtime data you can't see (logs, debugger output, network).
+- Dispatch the **debug-observer** agent if Docker/Redis/SQL diagnostics are needed.
+- After the fix, write a regression test.
+
+## Step 4 — End Session
+
+Triggered by "done" or "pause" (Hard Rule 7). Fill the Output template below — every section filled, write "none" where a section is empty.
+
+Done when: the Session Summary is emitted matching the template.
+
+## Output template
+
+```
+## Pair Session Summary
+
+Mode(s): [modes used]
+Check-in cycles: [number of check-in/review/test cycles completed]
+
+### Changes Made
+| File | Action | Description |
+|------|--------|-------------|
+| ... | ... | ... |
+
+### Decisions
+- [key decision 1]
+- [key decision 2]
+
+### Follow-up
+- [ ] [remaining work; "none" if complete]
+```
+
+## Recap
+
+- Wait for the user at every check-in — this is a dialogue, not a batch task.
+- Driver: ≤50 lines between check-ins. Navigator: ask before editing. Review: one finding at a time.
+- Clean code gets "Looks good" — never manufacture issues.
+- TDD defaults to Option A (Claude writes tests) unless the user claims the tests.
+- "done" or "pause" → Session Summary is mandatory before stopping.