rsc-universal 0.1.1

package/skills/plan/evals/README.md

@@ -0,0 +1,62 @@
+# Eval harness — `plan` skill
+
+These evals are run by an **agent harness** (an LLM agent with the rsc-sdd + stack skill catalog
+available), not a byte-exact shell script. `cases.yaml` is the fixture; this file is the procedure.
+Grading is judgment-based — a human or a judge-agent scores against the rubrics.
+
+`plan` is a process skill (the fourth SDD phase). It is judged on **routing accuracy** (does it
+fire only when there's a clarified spec to design from) and **capability** (does the plan it
+produces stay at the right altitude and cover the seven sections).
+
+## 1. Triggering accuracy
+
+Goal: `plan` fires when the user wants a technical design from a clarified spec, and stays silent
+on the adjacent SDD phases and on stack-mechanics requests.
+
+1. Load **only** the `plan` skill description into the agent, plus the bare names of the sibling
+   skills for routing: the rsc-sdd phases (constitution, specify, clarify, tasks, analyze,
+   implement, verify, review, ship, debug, worktrees, parallel) and the stack/other skills
+   (fastapi, nextjs, go, postgresdb, flutter, design, marketing, presentations,
+   course-storytelling, building-agents, secure-coding, deployment, harness, init). Do **not** load
+   any skill bodies.
+2. For each prompt in `should_trigger` and `should_not_trigger`, ask the agent which skill (if any)
+   it would invoke. Run **3–5 trials per prompt** at production temperature to catch flakiness.
+3. Score:
+   - `should_trigger` → PASS if `plan` is selected in the majority of trials.
+   - `should_not_trigger` → PASS if `plan` is **not** selected; bonus-correct if it routes to the
+     `route_to` sibling named in the case.
+4. **Pass bar: ≥ 90% of prompts pass** (at most 1 miss across the 13 prompts), and no
+   `should_not_trigger` prompt may fire `plan` in a majority of its trials. The two highest-value
+   near-misses to get right are `clarify` (the phase immediately before — an unclarified spec must
+   NOT trigger plan) and `tasks` (the phase immediately after).
+
+## 2. Capability uplift (with vs without)
+
+Goal: the skill measurably improves the plan, not just gates it.
+
+1. For the `capability` scenario, run the agent **twice**:
+   - **WITHOUT**: base agent, no `plan` skill loaded.
+   - **WITH**: same prompt, `plan` skill fully loaded (it may read its `references/plan-template.md`).
+2. Grade each output against the `must_include` checklist — count a point only if it is genuinely
+   satisfied, not merely gestured at. The load-bearing points are: the seven-section artifact at
+   the right path, language-neutral contracts (no framework code), a per-criterion testing
+   strategy, and a ranked risk register.
+3. Coverage = points satisfied / total points, per run.
+4. **Pass bar:**
+   - WITH-skill coverage **≥ 80%** of the rubric.
+   - WITH clearly beats WITHOUT. The signature uplift to look for: the WITHOUT run tends to write
+     framework code and a one-line "we'll add tests"; the WITH run stays stack-neutral, names test
+     levels per acceptance criterion, and produces a ranked risk register at the correct artifact
+     path.
+5. Run 2–3 trials per condition and average; note any rubric point the skill never produces — that
+   is a gap to fix in `SKILL.md` or `references/plan-template.md`.
+
+## Notes
+
+- Prompts deliberately vary phrasing; several omit the word "plan" so triggering rests on the
+  signal "clarified spec → technical design before code", not keyword matching.
+- Near-misses route to the genuinely correct sibling: fuzzy-idea → specify, vague-spec → clarify,
+  approved-plan-to-checklist → tasks, DDL/indexes → postgresdb, real handler+tests → go,
+  project-wide principles → constitution.
+- This is judgment-based, not byte-exact. Record trial counts and the judge (human or model)
+  alongside results for reproducibility.

package/skills/plan/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: plan
+
+should_trigger:
+  - prompt: "We've got the signed-off spec for the checkout-reservation feature. Now design the architecture and how the pieces talk to each other before anyone codes."
+    why: "Clarified spec in hand, asking for architecture + component contracts before code — the exact intent → tasks slot this skill fills."
+  - prompt: "Write the implementation plan for the new notifications service: components, the contracts between them, the data flow, and how we'll test it."
+    why: "Names every plan section (architecture, interfaces, data flow, testing strategy) without naming the phase — squarely in scope."
+  - prompt: "How should we build this? I want the data model, where each thing lives, what's transactional, and the order we can build it in."
+    why: "Data model + consistency boundaries + sequencing is the plan artifact; phrased as a 'how do we build' question, the structure-not-syntax altitude."
+  - prompt: "Before we start the feature, lay out the testing strategy — which seams get unit vs integration tests and what we have to mock to stay fast."
+    why: "Choosing test LEVELS per seam and what to fake is plan's testing-strategy section (strategy, not tooling)."
+  - prompt: "What are the main risks in this design and what could go wrong once we wire it to the payments provider? Rank them with mitigations."
+    why: "Ranked risk register with triggers/mitigations is plan §7; the non-obvious framing is 'what could go wrong', not the word 'plan'."
+  - prompt: "We have the spec and the clarifications are all resolved. What's the blueprint to get from here to shipping?"
+    why: "Explicitly post-clarify, asking for the technical blueprint — the handoff point clarify → plan, no stack named."
+  - prompt: "Sketch the box-and-arrow architecture and the interface each component promises, keeping it stack-neutral so the FastAPI/Go choice comes later."
+    why: "Architecture diagram + language-neutral contracts above the seam is precisely plan's altitude and its defer-to-stack rule."
+
+should_not_trigger:
+  - prompt: "I have a fuzzy idea for a referrals feature but no spec yet. Help me pin down what we're building and why."
+    route_to: "specify"
+    why: "Requirements capture from a fuzzy intent — that's specify; there's no spec to plan from yet."
+  - prompt: "The spec is written but vague on edge cases and what happens on a partial failure. Help me surface the ambiguities and resolve them."
+    route_to: "clarify"
+    why: "De-risking an existing spec by surfacing ambiguities is clarify, the gate that must pass before plan."
+  - prompt: "The plan's approved. Break it into an ordered checklist where each item has a done-check I can verify independently."
+    route_to: "tasks"
+    why: "Slicing an approved plan into an ordered, verifiable task list is the tasks phase, not planning."
+  - prompt: "Write the actual SQL schema, the indexes, and the EXPLAIN-verified migration for the orders table."
+    route_to: "postgresdb"
+    why: "Concrete DDL/indexes/migration mechanics are below the plan's altitude — the postgresdb stack skill owns them."
+  - prompt: "Implement the Go HTTP handler and the table-driven tests for the reservation endpoint we planned."
+    route_to: "go"
+    why: "Writing the actual handler + test code is implement-time stack mechanics (go), not the structure-level plan."
+  - prompt: "What are our project-wide non-negotiables — the stack canon and quality bars every feature must respect?"
+    route_to: "constitution"
+    why: "Capturing project-wide principles is the constitution phase; plan reads it but doesn't author it."
+
+capability:
+  - scenario: "User says: 'We have a clarified spec for an order-reservation feature (reserve stock for a cart for 15 minutes, then auto-release; must be idempotent per cart; calls an external payments provider). Write the implementation plan.' The agent has read the spec and constitution."
+    must_include:
+      - "Writes the artifact to 02-DOCS/wiki/sdd/plans/<slug>.md using the seven-section structure (context, architecture, interfaces, data model/flow, testing strategy, sequencing, risks)"
+      - "Architecture section names components with single responsibilities and marks the payments provider as EXTERNAL; states one top architectural decision with a reason tied to a constraint"
+      - "Interfaces section gives a language-neutral contract for reserve (inputs → outputs incl. error modes) and explicitly states the idempotent-on-cartId invariant and the 15-minute auto-release"
+      - "Data model + flow names entities at the model level (not DDL) and calls out the consistency/transactional boundary; defers concrete schema/indexes/migration to the postgresdb stack skill rather than writing SQL"
+      - "Testing strategy maps each acceptance criterion to a test level (unit/contract/integration/e2e), states what each asserts and what it mocks (e.g. the payments provider), and defers the test runner/tooling to the stack skill"
+      - "Risks section is ranked with trigger + impact + mitigation per risk (e.g. payments timeout, double-reservation race); does NOT claim zero risk"
+      - "Stays stack-neutral above the seam — no framework route decorators, ORM session code, or test-runner flags in the plan"
+      - "Ends by pointing to the tasks phase and notes indexing the plan in the root CLAUDE.md Knowledge map"

package/skills/plan/references/plan-template.md

@@ -0,0 +1,124 @@
+# Plan artifact template
+
+Copy this skeleton into `02-DOCS/wiki/sdd/plans/<slug>.md` and fill every section. The `<slug>`
+must match the spec's slug exactly — one plan per spec, same name. Delete the parenthetical
+guidance once a section is written; never leave an empty section (an empty section is a `tasks`
+phase that can't find its input). Keep everything at the *structure* altitude: contracts, shapes,
+flows, levels — not framework syntax.
+
+---
+
+```markdown
+# Plan — <feature name>
+
+> Spec: ../specs/<slug>.md · Constitution: ../constitution.md · Status: draft | approved
+> Last updated: YYYY-MM-DD
+
+## 1. Context & constraints
+
+(One or two lines each. Cite, don't re-paste, the spec and constitution.)
+
+- Acceptance criteria that shape the design: spec §Acceptance #1, #3 …
+- Non-functional bars: latency / throughput / scale / data residency …
+- Constitution rules in play: stack canon, quality bar, naming/convention rules …
+- Out of scope (from the spec) that the design must NOT creep into:
+
+## 2. Architecture
+
+(Box-and-arrow diagram + one sentence of single-responsibility per component. Mark each
+component as INTERNAL or EXTERNAL. The arrows are the seams you'll test and parallelize.)
+
+```text
+[ component A ] --<protocol>--> [ component B ]
+       |
+       v
+[ store / external ]
+```
+
+- **<component>** (internal/external) — single responsibility.
+- …
+
+**Top architectural decision:** <the one choice that matters> — chosen because <reason tied to a
+constraint above>. (If two designs are viable, state both, the trade-off, and the recommendation.)
+
+## 3. Interfaces & contracts
+
+(One block per seam. Operation, inputs → outputs incl. error modes, invariants. Language-neutral.)
+
+```text
+<component>.<operation>(<input>: <Type>) -> <Success> | <Error1> | <Error2>
+  - invariant: idempotent on … / transactional / ordered / …
+  - precondition: …
+  - postcondition: …
+```
+
+## 4. Data model & flow
+
+(Entities at the model level — key fields and relationships, not DDL. Then trace one primary
+scenario end to end. Concrete schema/indexes/migrations → ../<stack>/SKILL.md.)
+
+**Entities**
+
+- **<Entity>** — key fields; relationship to <Entity>.
+
+**Primary flow** (`<scenario from spec>`)
+
+1. <entry> receives <input> →
+2. <component> does <X>, reads/writes <store> →
+3. … → returns <output>.
+
+- Consistency boundaries: <what's transactional together> / <what's eventually consistent>.
+- Migration impact: new table? new column? backfill? destructive?
+
+## 5. Testing strategy
+
+(Per acceptance criterion: the level that proves it, what it asserts, what it fakes. Levels:
+unit / contract / integration / e2e. Tooling is the stack skill's job — name the strategy here.)
+
+| Acceptance criterion | Level | Asserts | Fakes / mocks |
+| --- | --- | --- | --- |
+| spec §Acceptance #1 | unit | … | … |
+| spec §Acceptance #2 | integration | … | … |
+
+- Where the e2e line is, and why.
+- What MUST be a real dependency (not mocked) for the test to mean anything.
+
+## 6. Sequencing & dependencies
+
+(Ordered, independently-verifiable steps. Mark serial vs. parallelizable. This becomes the
+`tasks` list.)
+
+1. <step> — depends on: none — [serial | parallelizable]
+2. <step> — depends on: #1 — …
+
+- Parallel candidates (disjoint scope, no shared state): #…, #… (fan-out via the parallel phase)
+- Hard ordering constraints and why.
+
+## 7. Risks & open decisions
+
+**Risks** (ranked, most likely/impactful first)
+
+| Risk | Trigger | Impact | Mitigation / spike to retire it |
+| --- | --- | --- | --- |
+| … | … | … | … |
+
+**Open decisions** (still genuinely undecided)
+
+- <decision> — closes when <input/answer> arrives. (Significant decisions taken during planning
+  go to ../decisions.md as well.)
+```
+
+---
+
+## Notes on filling it
+
+- **Altitude check.** If a section contains real framework code, you've dropped too low — restate
+  it as a contract or a flow and let the stack skill render it at `implement`.
+- **Citations over copies.** Reference `spec §…` and `constitution §…`; the plan is a derivative
+  view, not a duplicate. Duplicated text drifts out of sync.
+- **One decision, defended.** The architecture section's job is to make the load-bearing call and
+  defend it, not to enumerate every option without choosing.
+- **Empty section = defect.** Every one of the seven must say something real before `tasks` runs.
+  If a section genuinely has no content (e.g. no migration), write "none — <why>", not silence.
+- **Index it.** After writing, add the plan to the root `CLAUDE.md` `## Knowledge map` so the
+  harness wiki and later phases can find it.

package/skills/planetscale/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: planetscale
+description: "Use when operating PlanetScale serverless MySQL (Vitess) — setting up a database/branch and wiring the pscale CLI, shipping a schema change through branches and deploy requests, debugging a stuck/queued deploy or a cutover that won't finish, designing tables without foreign keys, or picking the serverless HTTP driver for an edge runtime. Triggers: 'schema change without downtime on PlanetScale', 'my migration is stuck in the deploy queue', 'the cutover hung', 'can I still revert 40 minutes after deploy', 'the 30-minute revert window', 'PlanetScale won't let me add a foreign key', 'relationMode prisma', 'MySQL connection times out on Vercel Edge', 'cambio de esquema sin downtime', 'no me deja usar foreign keys'. NOT raw MySQL query tuning, EXPLAIN, or index choice (that is postgresdb's MySQL-engine analogue / the mysql sibling), and NOT generic expand-contract migration theory (that is db-migrations)."
+tags: [planetscale, vitess, mysql, deploy-requests, serverless-db]
+recommends: [mysql, db-migrations, prisma-orm, drizzle-orm, github-actions, postgresdb]
+origin: risco
+---
+
+# PlanetScale — Vitess serverless MySQL: branches, deploy requests, no FKs
+
+PlanetScale is serverless, MySQL-compatible database-as-a-service built on **Vitess** — the same
+horizontal-scaling layer that runs YouTube. You do not `ALTER TABLE` against production. Schema
+changes live on an isolated **branch** (a full copy of the schema), reach production through a
+**deploy request** (a pull request for your schema), and apply via **Online DDL**: Vitess builds a
+shadow table holding the new schema, replicates rows and in-flight writes old→new with VReplication,
+then **cuts over** with no table lock. Because Online DDL and sharding are the platform's center of
+gravity, you **design without foreign keys** (FKs are now an opt-in but unsharded-only feature). This
+skill owns that workflow — not MySQL the engine.
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Standing up a PlanetScale database, branch, or org and wiring the `pscale` CLI.
+- Shipping a schema change safely: dev branch → DDL → deploy request → diff → review → deploy → revert window.
+- A deploy request that is stuck/queued, a cutover that won't finish, or a lint error blocking deploy.
+- Designing relations when FKs are unavailable/discouraged: emulated relations, app-level integrity, ORM `relationMode`.
+- Choosing a connection path for edge/serverless (Cloudflare Workers, Vercel Edge, Lambda) where TCP MySQL is blocked.
+- Wiring deploy requests into CI (GitHub Actions) or a branch-per-PR preview database.
+
+**When NOT to use:**
+
+- A slow query, an `EXPLAIN` plan, an index decision, JSON columns, locking — that is MySQL-engine
+  work. The closest built sibling for engine-level relational guidance is `../postgresdb/SKILL.md`
+  (Postgres, but the engine-thinking transfers); pure MySQL tuning routes to the `mysql` sibling.
+  Heuristic: **would this answer be identical on RDS MySQL? Then it is not this skill.**
+- PostgreSQL engine/design — even PlanetScale's managed Postgres SQL semantics → `../postgresdb/SKILL.md`.
+  PlanetScale sells Postgres too, but this skill is strictly the **Vitess/MySQL branch+deploy-request** flow.
+- Engine-agnostic migration *theory* (expand-contract, backfill ordering) → the `db-migrations` sibling.
+  Here you get the concrete PlanetScale realization, not the theory.
+- Neon's Postgres copy-on-write branches → the `neon` sibling. Supabase's Postgres BaaS → `supabase`.
+- ORM client ergonomics (Prisma `updateMany`, Drizzle query builder) → `prisma-orm` / `../drizzle-orm/SKILL.md`.
+  This skill owns only the PlanetScale-specific knobs those ORMs expose (`relationMode`, serverless driver adapter).
+
+Deep dives: [deploy-requests](references/deploy-requests.md) (lifecycle states, queue/gating, lint
+errors, revert edge cases, declarative vs imperative) · [no-foreign-keys](references/no-foreign-keys.md)
+(emulated relations, ORM `relationMode`, the unsharded FK opt-in, Bad→Good schemas).
+
+## Mental model
+
+| PlanetScale concept | Git analogue | What it actually is |
+| --- | --- | --- |
+| Branch | branch | A full, isolated copy of the schema. `main` is your production branch. |
+| Deploy request | pull request | The gate that carries schema from a dev branch to production. |
+| Schema diff | the PR diff | The exact DDL the deploy will run, computed by PlanetScale. |
+| Online DDL | (no git analogue) | Shadow table + VReplication + non-blocking cutover. No `ALTER` lock. |
+| Schema revert | revert commit | A **~30-minute** window after deploy to undo while preserving post-deploy writes. |
+
+The revert window is the one thing people get wrong: it is **not** forever, and it has carve-outs
+(dropped tables/columns and FK-constraint changes are not cleanly revertible). After ~30 minutes the
+deploy is permanent. Plan rollbacks as new forward deploys, not as "I'll just revert later."
+
+## The deploy-request workflow
+
+Production branches should have **safe migrations** enabled — that is what forces every schema change
+through a deploy request instead of letting a raw `ALTER` hit `main`. Production branches are protected
+by default. The full lifecycle (numbered steps, real `pscale` commands):
+
+```bash
+# 0. Install + authenticate (once)
+brew install planetscale/tap/pscale   # or scoop / apt — see pscale docs
+pscale auth login
+
+# 1. Create the database (region close to your app)
+pscale database create my_app --region us-east
+
+# 2. Create a dev branch off production to hold the change
+pscale branch create my_app add-orders-table
+
+# 3. Apply your DDL on the BRANCH, never on main.
+#    Open a MySQL shell scoped to the branch and run your CREATE/ALTER:
+pscale shell my_app add-orders-table
+#    mysql> CREATE TABLE orders (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
+#    mysql> ALTER TABLE users ADD COLUMN last_seen_at TIMESTAMP NULL;
+
+# 4. Open a deploy request from the branch back to production.
+#    --disable-auto-apply gates the cutover behind a manual apply (recommended for risky drops).
+pscale deploy-request create my_app add-orders-table --disable-auto-apply
+
+# 5. Inspect the exact schema diff the deploy will run. ALWAYS read this.
+pscale deploy-request diff my_app 42
+
+# 6. Review / approve (the schema-PR review step)
+pscale deploy-request review my_app 42 --approve
+
+# 7. Deploy. PlanetScale runs Online DDL: shadow table -> VReplication -> cutover.
+pscale deploy-request deploy my_app 42
+
+# 8. If you disabled auto-apply, the change waits gated until you apply the cutover:
+pscale deploy-request apply my_app 42
+
+# 9. Verify on production. If wrong, REVERT within the ~30-minute window:
+pscale deploy-request revert my_app 42
+```
+
+**Auto-apply is ON by default.** With it on, step 7 deploys *and* cuts over in one motion. For
+anything destructive — dropping a column/table, narrowing a type — pass `--disable-auto-apply` at
+step 4 so the cutover sits gated (step 8) until a human applies it. That gap is your last cheap exit
+before the revert window starts ticking.
+
+For queued/gated deploys that won't move, lint errors that block a deploy, declarative vs imperative
+schema, and the exact revert carve-outs, see [deploy-requests](references/deploy-requests.md).
+
+## Design without foreign keys
+
+Vitess's first-class features are Online DDL and horizontal sharding. Native foreign keys fight both:
+a cross-shard FK is meaningless once a table is sharded, and FK constraint checks degrade
+high-concurrency writes. PlanetScale **historically disallowed FKs entirely**; they are now an opt-in
+but **unsharded-only** feature. The scale-safe default is **app-level referential integrity** with
+emulated relations, not database-enforced FKs.
+
+```sql
+-- Bad on PlanetScale at scale: a DB-enforced FK with ON DELETE CASCADE.
+-- Blocks sharding, conflicts with Online DDL, and the cascade is a hidden write amplifier.
+CREATE TABLE orders (
+  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id   BIGINT NOT NULL,
+  CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+-- Good: no DB FK. Index the relation column, enforce integrity in the app/ORM,
+-- and do cascades explicitly in a transaction or background job.
+CREATE TABLE orders (
+  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id   BIGINT NOT NULL,
+  KEY idx_orders_user_id (user_id)   -- the relation still needs its index
+);
+```
+
+With Prisma, declare `relationMode = "prisma"` so the client emulates relations and adds the implicit
+indexes instead of emitting DB-level FKs:
+
+```prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+```
+
+With Drizzle, model the relation in app code (`relations()`), index the join column, and skip the
+`references()`-backed FK constraint at the DB layer. The opt-in unsharded FK is acceptable only when
+you are certain the table will never shard and you accept the Online DDL friction — see
+[no-foreign-keys](references/no-foreign-keys.md) for emulated cascades, ORM specifics, and the opt-in caveats.
+
+## Connecting
+
+Two connection paths. Pick by **runtime**, not by preference.
+
+```ts
+// Direct MySQL string — for Node/long-lived servers that can open a TCP socket.
+// DATABASE_URL=mysql://user:pass@host/db?ssl-mode=require   (TLS required)
+
+// Serverless HTTP driver — for edge/serverless where raw TCP MySQL is blocked.
+import { connect } from "@planetscale/database";
+
+const conn = connect({ url: process.env.DATABASE_URL });
+const result = await conn.execute("SELECT id FROM users WHERE email = ?", [email]);
+```
+
+`@planetscale/database` is Fetch-API compatible: it speaks HTTP, so it works where you cannot open a
+MySQL socket — Cloudflare Workers, Vercel Edge, Lambda. The spelling is exactly `@planetscale/database`;
+there is no other official package name. Drizzle ships a matching adapter,
+`drizzle-orm/planetscale-serverless`, that wraps this driver — see `../drizzle-orm/SKILL.md` for the
+query-builder side.
+
+| Runtime | Connection path | Why |
+| --- | --- | --- |
+| Node server, long-lived process | Direct `mysql://…?ssl-mode=require` | TCP socket available; pool it. |
+| Vercel Edge / Cloudflare Workers | `@planetscale/database` (HTTP) | No raw TCP; the Fetch-based driver works. |
+| AWS Lambda / short-lived serverless | `@planetscale/database` (HTTP) | Avoids per-invocation connection churn. |
+| Drizzle on edge | `drizzle-orm/planetscale-serverless` | Wraps the HTTP driver; same constraints. |
+
+## CI/CD
+
+Wire the deploy-request flow into CI so schema changes are reviewed like code. A GitHub Actions job
+installs `pscale`, authenticates with a service token (`PLANETSCALE_SERVICE_TOKEN` /
+`PLANETSCALE_SERVICE_TOKEN_ID` as secrets), then drives the same verbs you run locally:
+
+```yaml
+# .github/workflows/schema.yml — open + diff a deploy request on PR
+- run: |
+    pscale deploy-request create "$DB" "${{ github.head_ref }}" --disable-auto-apply
+    pscale deploy-request diff   "$DB" "$DR_NUMBER"   # surface the schema diff in the PR
+```
+
+For a **branch-per-PR preview database**, create a PlanetScale branch named after the PR head, run the
+app's migrations against it, and tear the branch down when the PR closes. The orchestration (matrix,
+secrets, cleanup-on-close) is generic CI — defer the Actions plumbing to the `github-actions` sibling
+and keep the PlanetScale verbs here.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `ALTER TABLE` on the `main` production branch | Skips the gate; no diff, no review, no revert window | Branch → DDL → deploy request → diff → deploy |
+| Relying on DB-enforced foreign keys at scale | Blocks sharding, fights Online DDL, degrades high-concurrency writes | App/ORM-level integrity; `relationMode="prisma"`; index the relation column |
+| Leaving auto-apply ON for a destructive change | Deploy + cutover happen in one motion; no gated last-look before the drop | `--disable-auto-apply`, inspect, then `deploy-request apply` |
+| Opening a direct `mysql://` connection from Vercel Edge / Workers | Raw TCP MySQL is blocked on edge runtimes → connection timeouts | Use `@planetscale/database` HTTP driver |
+| Treating revert as available forever | The window is **~30 min** and excludes dropped tables/cols and FK changes | Plan rollbacks as new forward deploys |
+| Deploying without reading `deploy-request diff` | You ship DDL you never saw; surprise table rewrites | Always run the diff before `deploy` |
+| Inventing a driver name (`@planetscale/serverless`, `planetscale-js`) | There is no such package; install fails | The package is exactly `@planetscale/database` |
+
+## Decision: FK strategy by sharding posture
+
+| Will this table shard? | FK strategy | Notes |
+| --- | --- | --- |
+| Yes, or unsure | No DB FK — emulate in app/ORM | Default. Index the relation column; cascade in code. |
+| Never (small, bounded, unsharded) | Unsharded FK opt-in *is* acceptable | Accept Online DDL friction; document why it won't shard. |
+
+When the question is really about reading a plan, picking an index, or query latency, that is engine
+work — route to the `mysql` sibling (or `../postgresdb/SKILL.md` for the transferable engine
+reasoning). This skill stops at the Vitess platform boundary.

package/skills/planetscale/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — planetscale
+
+`cases.yaml` holds prompt-routing checks and capability rubrics for the repo's eval harness. The
+`should_trigger` / `should_not_trigger` entries assert routing: an LLM grader decides whether each
+prompt would invoke the planetscale skill, and the `should_not_trigger` cases name the real sibling it
+should go to instead (mysql, postgresdb, neon, db-migrations, prisma-orm). The `capability` entry is a
+scenario graded against its `must_include` rubric — the model's answer must hit each bullet (dev
+branch, branch-scoped DDL, `pscale deploy-request create`/`diff`, Online DDL shadow-copy/cutover,
+auto-apply vs manual apply, the ~30-minute revert window and its carve-outs, and a no-FK table design).
+No live PlanetScale account, `pscale` CLI, or database is needed — everything is graded from the model's
+text. Run it through the repo's standard eval runner against this directory.

package/skills/planetscale/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: planetscale
+
+should_trigger:
+  - prompt: "How do I make a schema change on PlanetScale without taking the table offline?"
+    why: "Core Online DDL / deploy-request workflow — branch, deploy request, shadow-copy cutover — is the heart of this skill."
+  - prompt: "My deploy request on PlanetScale has been stuck in the queue for ages and won't cut over. What's going on?"
+    why: "Non-obvious stuck-deploy symptom; the skill distinguishes 'still copying via VReplication' from 'gated waiting on apply' and routes to the deploy-requests reference."
+  - prompt: "PlanetScale won't let me add a foreign key. What's the right way to model this relationship?"
+    why: "No-FK design is a named scope; the answer is emulated relations / relationMode, not a generic schema lecture."
+  - prompt: "I'm on Vercel Edge and my MySQL connection to PlanetScale keeps timing out. How do I connect?"
+    why: "Non-obvious: raw TCP MySQL is blocked on edge runtimes; the fix is the @planetscale/database HTTP driver, which is PlanetScale-specific."
+  - prompt: "Necesito cambiar el esquema sin downtime en PlanetScale, ¿cómo lo hago?"
+    why: "Spanish phrasing of the core branch + deploy-request zero-downtime workflow."
+  - prompt: "I deployed a PlanetScale deploy request about 40 minutes ago and need to undo it — can I still revert?"
+    why: "Non-obvious: the ~30-minute revert window has likely closed, and reverts exclude dropped tables/cols and FK changes — a load-bearing nuance of this skill."
+  - prompt: "Set relationMode = prisma for my PlanetScale database and explain why."
+    why: "PlanetScale-specific ORM knob for emulating relations without DB foreign keys; the skill owns this even though Prisma is an ORM."
+
+should_not_trigger:
+  - prompt: "This MySQL query does a full table scan even with an index. How do I make it use the index?"
+    route_to: mysql
+    why: "Engine-level query tuning / index usage — identical answer on RDS MySQL — is the mysql sibling, not the PlanetScale platform workflow."
+  - prompt: "Design my PostgreSQL schema with proper constraints and pick the right column types."
+    route_to: postgresdb
+    why: "Postgres engine design and SQL semantics route to postgresdb, even when PlanetScale also sells managed Postgres."
+  - prompt: "I want Postgres branches for spinning up preview environments per pull request."
+    route_to: neon
+    why: "Postgres copy-on-write branching is Neon's model; PlanetScale branches are Vitess MySQL gated by deploy requests, a different engine and flow."
+  - prompt: "Can you explain how expand-contract migrations work in general, regardless of database?"
+    route_to: db-migrations
+    why: "Engine-agnostic migration theory belongs to db-migrations; this skill is the concrete PlanetScale deploy-request realization."
+  - prompt: "My Prisma Client updateMany returns the wrong count — what is the ORM actually doing?"
+    route_to: prisma-orm
+    why: "ORM client API ergonomics are the prisma-orm sibling; this skill owns only the PlanetScale connector knobs like relationMode."
+
+capability:
+  - scenario: "Walk me through shipping an ADD COLUMN on users plus a new orders table to a production PlanetScale MySQL database with zero downtime and a rollback plan."
+    must_include:
+      - "Creates a dev branch (pscale branch create), not editing main/production directly"
+      - "Applies the DDL on the branch (pscale shell), never against the production branch"
+      - "Opens a deploy request with pscale deploy-request create"
+      - "Runs pscale deploy-request diff and reads it before deploying"
+      - "Explains Online DDL: shadow table + VReplication copy + non-blocking cutover"
+      - "Addresses auto-apply ON by default vs --disable-auto-apply + deploy-request apply for the gated cutover"
+      - "Notes the ~30-minute revert window and that it excludes dropped tables/columns and FK-constraint changes"
+      - "Designs the new orders table without a DB-level foreign key (indexed relation column + app/ORM integrity), or justifies the unsharded FK opt-in"

package/skills/planetscale/references/deploy-requests.md

@@ -0,0 +1,75 @@
+# Deploy requests — lifecycle, gating, lint, reverts
+
+Offloaded depth from SKILL.md §"The deploy-request workflow". The body has the happy path; this file
+covers the states a deploy request moves through, why it stalls, and the revert carve-outs.
+
+## Lifecycle states
+
+A deploy request moves through roughly:
+
+1. **Open** — created from a dev branch against production; PlanetScale has computed a schema diff.
+2. **Approved** — a reviewer ran `pscale deploy-request review … --approve` (or approved in the UI).
+3. **Queued / deploying** — the deploy is submitted; Vitess starts Online DDL (shadow table build +
+   VReplication copy). Large tables spend most of their time here.
+4. **Pending cutover / gated** — if auto-apply was disabled (`--disable-auto-apply`), the copy is done
+   and the change waits for a manual `pscale deploy-request apply` before cutting over.
+5. **Deployed** — cutover complete. The **~30-minute revert window** opens here.
+6. **Reverted** or **permanent** — either reverted within the window, or finalized after it closes.
+
+## Online DDL mechanics
+
+A deploy does not run a blocking `ALTER`. Vitess:
+
+- builds a **shadow table** with the target schema,
+- uses **VReplication** to copy existing rows and continuously apply in-flight writes from old→new,
+- waits for the shadow to catch up (lag → ~0),
+- performs an atomic **cutover**, swapping the shadow in as the live table.
+
+That is why a deploy against a big table can sit in "deploying" for a long time: it is copying rows,
+not stuck. Watch the deploy's progress before assuming it hung.
+
+## Why a deploy is queued / won't cut over
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| "Queued" for a long time on a large table | VReplication is still copying rows | Wait; check copy progress. It is working, not stuck. |
+| Deployed-but-not-cut-over | Auto-apply disabled; it is gated | Run `pscale deploy-request apply <db> <number>`. |
+| Another deploy already in flight | Deploys serialize per branch | Let the in-flight one finish or revert it first. |
+| Blocked at open with lint errors | The diff violates a schema lint rule | Fix the DDL on the branch, re-diff, re-open. |
+
+## Lint errors
+
+PlanetScale lints the schema diff before it will deploy. Common blockers: a table without a primary
+key (Vitess wants one for VReplication), or unsupported/foot-gun DDL. Resolve by editing the DDL on the
+**branch** (open a `pscale shell`, fix the schema), regenerate the diff, and re-open the deploy request.
+Never try to force a lint failure through.
+
+## Revert carve-outs
+
+The ~30-minute window lets you undo a deploy **while preserving writes that happened after the deploy**
+— for most additive changes. It does **not** cleanly cover:
+
+- **Dropped tables or columns** — the data is gone; a revert cannot resurrect it.
+- **Foreign-key constraint changes** — excluded from clean revert.
+
+After the window closes the deploy is permanent. Treat the window as a safety net for *additive*
+changes, and plan destructive rollbacks (re-adding a dropped column, restoring data) as **new forward
+deploys**, not as reverts.
+
+## Declarative vs imperative schema
+
+Two ways to express the change on a branch:
+
+- **Imperative** — you run the `ALTER`/`CREATE` statements yourself in `pscale shell`; the deploy
+  request diffs branch-vs-production and deploys that diff.
+- **Declarative** — you keep the desired schema in version control and let PlanetScale compute the DDL
+  needed to converge the branch to that target.
+
+Either way the deploy request is the gate and the diff is the contract. Read the diff before deploying.
+
+## Branch protection / safe migrations
+
+Production branches are protected by default. **Safe migrations** on a branch is the setting that
+*requires* the deploy-request flow — it stops raw schema edits from landing directly on the protected
+branch. Keep it on for any branch that fronts production. Dev branches are disposable; protect the one
+that matters.