@gallopsystems/agent-skills 1.25.1 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.25.1",
+  "version": "1.27.0",
   "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/frontend-design/skills/frontend-design/SKILL.md

@@ -199,6 +199,16 @@ The first three are the foundational lenses — every other principle and rule s
 - **Why:** This is core to the tool-like feel. Persistent action buttons next to every value make lists feel cluttered and form-like; inline edit + hover actions keep the surface calm and let content dominate.
 - **How to apply:** For editable fields on detail pages and rows, prefer click-to-edit. For bulk row actions, use a hover-revealed action group or a per-row `…` (kebab) menu. Reserve always-visible buttons for the one or two primary actions of the surface.
 
+#### Entering edit mode must not shift the layout
+
+- **Rule:** Toggling a row or field between read and edit must not move anything around it. The read-out keeps its exact footprint, aligned columns (numeric value columns especially) stay put, and neighboring rows don't reflow. The classic offender is swapping a row's right-hand cells (the value/metric readout) for inputs — inputs have different widths, so the value column jumps and every other row's alignment breaks the instant one row opens.
+- **Why:** A layout that lurches when you click "edit" reads as broken, and in a dense ledger/table it destroys the scannability that made the read view useful — the eye loses the column it was tracking. Stability is what makes inline editing feel native rather than like a bolted-on form.
+- **How to apply:**
+  - Reveal the edit affordance (a pencil/kebab) with **absolute positioning** so it consumes no layout space — float it in the row's whitespace with `opacity-0 group-hover:opacity-100` (also reveal on `focus-visible`). Adding a real per-row action *column* pushes content and, unless you add the identical gutter to every row including headers/totals, misaligns the value column — absolute positioning sidesteps that entirely.
+  - For anything wider than the value it replaces (multiple inputs, unit×qty, a rate + suffix), **expand an editor strip below the row** rather than replacing the cells in place. The row above stays frozen showing the current value for context; the editor gets arbitrary width with zero horizontal shift. Animate the expand with a height/opacity transition (e.g. `v-auto-animate` / auto-height), never by animating siblings.
+  - Drop the row's bottom divider while it's being edited so the row and its editor strip read as one unit, not two stacked rows.
+  - One editor open at a time; autofocus the first input; **Enter** saves, **Esc** cancels. On save, patch → return to read-only → let the recomputed value settle back into the unchanged row.
+
 #### Every interaction gets immediate visible feedback
 
 - **Rule:** The moment a user acts, the UI must respond — within the same frame if possible. Pressed states on buttons (slight darken or scale, not just color), hover states on every clickable surface, optimistic UI updates for ordinary mutations (toggling a checkbox, renaming a field), an inline check or subtle highlight when a save completes. If a network call takes more than ~200ms, show a quiet inline spinner or skeleton in the affected region — not a global loading bar.

package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md

@@ -52,6 +52,7 @@ Runnable, copy-pasteable query examples live alongside as `.ts` files:
 1. **Always use Kysely's query builder — never reach for raw `sql`**: Almost anything expressible in SQL is expressible type-safely through Kysely's methods and the ExpressionBuilder (`eb`); raw `sql`` throws away the type safety this stack depends on. Treat it as a true last resort — only when Kysely genuinely cannot express the query (and type the template literal when you must). Being unsure how to do something is the cue to check the reference guides above, **not** to drop to raw SQL.
 2. **Use the ExpressionBuilder (eb)**: The `eb` parameter in callbacks is the foundation of type-safe query building
 3. **Let TypeScript guide you**: If it compiles, it's likely correct SQL
+4. **Document schema in the database, and read it before you touch a table**: Keep table/column/index/constraint notes as Postgres COMMENTs (not just migration source), surface them in the generated `db.d.ts`, and update them in the same migration that changes how something works. Consult that JSDoc to gather context before querying or altering a table — see [migrations-and-codegen.md](references/migrations-and-codegen.md#schema-comments--document-in-the-db-not-just-in-migration-source).
 
 ## Contributing Back
 

package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md

@@ -147,6 +147,46 @@ with `ifExists`, so re-applying it after the others is a safe no-op). Verify the
 ledger is a contiguous prefix after the DELETE, and prefer letting the deploy's own
 migrate job re-apply rather than running migrations from a laptop against prod.
 
+## Schema Comments — Document in the DB, Not Just in Migration Source
+
+Design notes written as `//` comments in a migration file are invisible the moment
+the migration runs: they don't reach a live database and they don't reach the
+generated types. **Put the documentation in the database itself** as Postgres
+COMMENTs so it survives, stays queryable (`\d+`, `obj_description`, any GUI), and —
+via codegen below — lands in the generated `db.d.ts` as JSDoc.
+
+Comment every object that carries intent, not just tables and columns:
+
+```typescript
+await sql`COMMENT ON TABLE ${sql.ref("invoice")} IS ${sql.lit(
+  "A billed invoice. status is DERIVED from payments, never stored.",
+)}`.execute(db);
+await sql`COMMENT ON COLUMN ${sql.ref("invoice.void_reason")} IS ${sql.lit(
+  "Set only when status='void'; null otherwise.",
+)}`.execute(db);
+await sql`COMMENT ON INDEX ${sql.ref("uq_invoice_current_number")} IS ${sql.lit(
+  "One live number per org — partial unique WHERE void_at IS NULL.",
+)}`.execute(db);
+await sql`COMMENT ON CONSTRAINT ${sql.ref("invoice_status_check")} ON ${sql.ref("invoice")} IS ${sql.lit(
+  "status must be one of draft/sent/paid/void.",
+)}`.execute(db);
+```
+
+Use `sql.ref()` for identifiers and `sql.lit()` for the text (it escapes the
+literal; `COMMENT` does not accept bound parameters). To reverse, set the comment
+to `NULL`. Centralizing all comments in one data-driven migration (maps of
+table/column/index/constraint → text, applied in `up`, nulled in `down`) keeps them
+in one place and makes the `down` trivial.
+
+**Keep comments in sync with behavior.** When a migration changes *how something
+works* — a column's meaning, what a partial index enforces, a new CHECK — update
+its comment in that same migration. A stale comment is worse than none.
+
+**Gather context from these comments.** Before querying or changing a table, read
+its JSDoc in the generated `db.d.ts` (see below) — the table/column/index/constraint
+notes are the schema's own explanation of intent, invariants, and "derived, not
+stored" rules. Prefer them over re-deriving intent from the raw column list.
+
 ## Type Generation
 
 Use `kysely-codegen` to generate types from your database:
@@ -160,3 +200,22 @@ Generated types use:
 - `ColumnType<Select, Insert, Update>` for different operation types
 - `Timestamp` for timestamptz columns
 
+### Surfacing schema comments in the generated types
+
+`kysely-codegen` emits **column** comments as JSDoc automatically, but drops
+**table**, **index**, and **constraint** comments (kysely #1368 / kysely-codegen
+#316, unmerged as of 0.20.0 — indexes and constraints also have no symbol of their
+own in the output). Recover them with a post-codegen step: a small script reads
+`obj_description` for tables/indexes/constraints and injects each table's comment
+plus `Indexes:` / `Constraints:` sections as JSDoc above its `export interface`.
+Chain it into the codegen command:
+
+```jsonc
+"db:codegen": "kysely-codegen --url $DATABASE_URL --out-file src/db/db.d.ts --dialect postgres --date-parser string && node scripts/inject-table-comments.mjs $DATABASE_URL src/db/db.d.ts"
+```
+
+The result is a `db.d.ts` where each table interface is prefaced by its full design
+note — the documentation surface an agent should consult first. (Ship the
+`inject-table-comments.mjs` script and this wired-up `db:codegen` in your project
+template so every scaffolded repo gets it out of the box.)
+

package/plugins/linear/skills/linear/SKILL.md

@@ -203,7 +203,7 @@ The CLI resolves friendly names against `workspace.json`, so you rarely need raw
 
 > **Important:** When assigning an issue to a cycle, always set `--state todo`. Issues default to Backlog, which doesn't work with cycles — they must be in Todo status.
 >
-> **Required placement rule:** Never create an issue without both `--project` and `--milestone`. If the right project does not exist, create it first. If the project exists but the right milestone does not, create the milestone first. Do not leave issues unscoped or unmilestoned.
+> **Required placement rule:** Never create an issue without both `--project` and `--milestone`. **The project must already exist** — place the issue in the initiative's existing `M` project for the milestone it falls under, and never conjure a project to hold it (see "Never invent a project"). Creating a project is only correct for a confirmed out-of-scope revision. If the project exists but the right milestone does not, create the milestone first. Do not leave issues unscoped or unmilestoned.
 >
 > **Never target a completed milestone.** New work never belongs in a milestone that is already done — it distorts the completed phase and hides the issue from the team's current view. Only place an issue in an **open** milestone. If no open milestone matches the issue, create a new one and use that; do not reopen or reuse a completed milestone.
 >
@@ -241,8 +241,11 @@ node linear.mjs create-issue --title 'Investigate perf issue' --state todo \
   --description-file ./issue-body.md \
   --project 'project-uuid' --milestone 'milestone-uuid'
 
-# If the project or milestone does not exist yet, create it before the issue
-PROJECT_ID="$(node linear.mjs create-project --name '[CLIENT] Feature Area' --description 'Short description' | node -e "process.stdin.once('data',d=>console.log(JSON.parse(d).data.projectCreate.project.id))")"
+# Find the existing M project for the milestone this work falls under — do not create one.
+# (Prefer the MCP `get_initiative` with includeProjects; this lists them via the CLI.)
+node linear.mjs list-projects            # copy the [KEY] M<n> project's UUID
+PROJECT_ID='project-uuid-here'
+# Only the milestone may be created as part of intake
 MILESTONE_ID="$(node linear.mjs create-milestone "$PROJECT_ID" 'Phase 1' | node -e "process.stdin.once('data',d=>{const n=JSON.parse(d).data.projectMilestoneCreate.projectMilestone;console.log(n.id)})")"
 node linear.mjs create-issue --title 'Investigate performance issue' --state todo \
   --project "$PROJECT_ID" --milestone "$MILESTONE_ID" --cycle current
@@ -319,7 +322,9 @@ node linear.mjs search-issues "login bug"
 ### Projects & Milestones
 ```bash
 # Create a new project (linked to an initiative)
-node linear.mjs create-project --name "[KEY] Project Name" --initiative "$INITIATIVE_ID" --description "Short description"
+# Projects mirror the signed proposal's milestones ([KEY] M<n>) or a confirmed revision ([KEY] R<n>).
+# Never create one to hold work you couldn't place — see "Never invent a project".
+node linear.mjs create-project --name "[KEY] M1 — Milestone Name" --initiative "$INITIATIVE_ID" --description "Short description"
 
 # List all projects (pretty table with initiative, state, progress)
 node linear.mjs list-projects
@@ -347,7 +352,7 @@ node linear.mjs create-issue \
 
 ### Initiatives
 ```bash
-# Create a new initiative (= new client)
+# Create a new initiative (= a newly signed proposal; a repeat client gets another one)
 node linear.mjs create-initiative --name "ClientName" --description "Short description"
 
 # List all initiatives (pretty table with ID, status, description)
@@ -601,11 +606,11 @@ node linear.mjs update-initiative "$INITIATIVE_ID" --content-file ./initiative-n
 
 Linear organizes work in a top-down hierarchy: **Initiative → Project → Milestone → Issue**. Here's how the Gallop team uses each level.
 
-### Initiative (= Client)
+### Initiative (= Signed Proposal)
 
-An **Initiative** represents a client engagement or internal program. Each client gets one initiative.
+An **Initiative** represents **one signed proposal** for a client, not the client itself. A client who signs a second proposal (a later phase, a separate engagement) gets a **second initiative** — never a second set of projects bolted onto the first. The initiative's scope is fixed by what was signed.
 
-**The current client roster is not stored in this repo — fetch it live from Linear.** Initiatives are the source of truth for which clients exist, their descriptions, and their repo links:
+**The current roster is not stored in this repo — fetch it live from Linear.** Initiatives are the source of truth for which engagements exist, their descriptions, and their repo links:
 
 - **List all clients:** `mcp__linear-server__list_initiatives`
 - **Read a client's full details (overview, repo structure, domain notes):** `mcp__linear-server__get_initiative` — these live in the initiative's `content` field
@@ -615,33 +620,69 @@ When you start any task that needs client context, query Linear instead of looki
 
 - One initiative can contain **multiple projects**
 
-### Project (= Product / Workstream)
+### Project (= One Proposed Milestone, or a Revision)
 
-A **Project** is a distinct product, app, or major workstream within a client initiative. It groups related issues that ship together.
+A **Project** is **one of the milestones the signed proposal committed to** — not a
+product, not a workstream, not a theme you invented. The initiative's project list
+*is* the proposal's milestone list: if the proposal promised three milestones, the
+initiative has three projects, numbered and named after them.
 
-**Examples:**
-- `[ACME] Billing System` — one self-contained product
-- `[ACME] Analytics Demo` — separate product under the same client
-- `[CLIENT] Migration Workstream` — the single workstream for that client
-- `[CLIENT] Scheduling Platform` — the main product for that client
+**Naming convention:** `[KEY] M<n> — <Milestone name>`, where `<n>` is the
+milestone's number in the signed proposal.
 
-**When to create a new project:**
-- The work has its own deployment, repo, or codebase
-- It could be described independently to a stakeholder
-- It has a distinct "done" state separate from other work
+- `[KEY] M1 — Data Model`
+- `[KEY] M2 — Pricing Engine`
+- `[KEY] M3 — Reporting`
 
-**Naming convention:** `[CLIENT_KEY] Project Name`
+**Work outside the signed scope is a revision, and gets its own project** —
+attached to the **same initiative**, named with an `R` prefix instead of `M`:
+
+- `[KEY] R1 — <Name>`, `[KEY] R2 — <Name>`, …
+
+`R` numbering is sequential across the whole proposal in the order revisions are
+taken on, independent of which milestone the revision relates to. Never fold
+out-of-scope work into an `M` project — that silently rewrites what was signed.
+
+#### Never invent a project
+
+**The default is that the right project already exists.** Creating one is a
+structural change to a signed engagement, so it is never a side effect of intake.
+
+Before placing any work, answer this question — and **ask the requester if they
+are in the conversation, do not infer it**:
+
+> Is this within the signed scope, or is it a revision?
+
+- **Within scope** → **find the existing `M` project yourself.** List the
+  initiative's projects (`get_initiative` with `includeProjects: true`), read what
+  each milestone covers, and place the work in the one it falls under. Only ask
+  which project if two genuinely both fit. Do **not** create a project because none
+  of the names happens to match the request's wording — milestone names are broad
+  by design.
+- **A revision** → determine the next `R<n>` (one past the highest existing `R`,
+  or `R1`), **confirm the name and the revision framing with the requester**, then
+  create it under the same initiative.
+
+Never create a project to hold work you were unsure how to place, to mirror a repo
+or deployment, to group work by theme or domain (that is what milestones and labels
+are for), or because the initiative looked empty. If you cannot place the work and
+the requester is unavailable, leave it unplaced and say so — an invented project is
+harder to undo than an unplaced issue.
 
 ### Milestone (= Phase / Epic)
 
 A **Milestone** is a phase or epic within a project — a meaningful chunk of progress that can be demoed or shipped incrementally.
 
-**Examples within `[ACME] Billing System`:**
+A milestone is the level where grouping decisions actually belong — **unlike
+projects, milestones may be created freely as part of intake.** If a request needs
+a new home inside its `M` project, that home is a milestone, never a new project.
+
+**Examples within `[KEY] M2 — Billing`:**
 - `Core Billing` — create, edit, send invoices (done)
 - `Quotes` — quote workflow, create/edit/convert to invoice
 - `Payments` — payment methods, receipts, balance due display
 
-**Examples within `[NW] Appointment Scheduling`:**
+**Examples within `[KEY] M1 — Scheduling`:**
 - `Providers Module` — list, create, edit, deactivate providers
 - `Booking Requests` — request creation, accept/reject workflow
 - `Scheduling & Calendar` — availability, scheduling UI
@@ -661,24 +702,30 @@ Individual work items live at the bottom of the hierarchy. Every issue belongs t
 ### Hierarchy in Practice
 
 ```
-Initiative: Northwind
-  └── Project: [NW] Appointment Scheduling
-        ├── Milestone: Providers Module
-        │     ├── ACME-101: Create providers list page
-        │     ├── ACME-102: Add provider create/edit form
-        │     └── ACME-103: Provider deactivation support
-        ├── Milestone: Booking Requests
-        │     ├── ACME-110: Request creation form
-        │     └── ACME-111: Accept/reject API endpoints
-        └── Milestone: Notifications
-              └── ACME-120: Set up email service
+Initiative: <Client> — Phase 1        ← one signed proposal
+  ├── Project: [KEY] M1 — Scheduling      ← proposal milestone 1
+  │     ├── Milestone: Providers Module
+  │     │     ├── KEY-101: Create providers list page
+  │     │     ├── KEY-102: Add provider create/edit form
+  │     │     └── KEY-103: Provider deactivation support
+  │     ├── Milestone: Booking Requests
+  │     │     ├── KEY-110: Request creation form
+  │     │     └── KEY-111: Accept/reject API endpoints
+  │     └── Milestone: Notifications
+  │           └── KEY-120: Set up email service
+  ├── Project: [KEY] M2 — Billing         ← proposal milestone 2
+  └── Project: [KEY] R1 — SSO Integration ← out-of-scope revision
 ```
 
+The project row is fixed by the proposal (`M1`, `M2`) plus whatever revisions have
+been agreed (`R1`). New requests land as **issues in a milestone** inside an
+existing project — the project row only grows when a revision is confirmed.
+
 ### Guidelines for the Team
 
 1. **Every issue must be placed into a cycle with Todo status.** **Do NOT default to the current/active cycle.** Follow this procedure: (a) Run `cycle-capacity` to see each cycle's capacity % (velocity-based, from last 3 completed cycles). (b) Starting from the earliest (current) cycle, find the first cycle that is **strictly under 100%** capacity. (c) If the current cycle is at or above 100%, **skip it** and use the next cycle with room. Assign the issue there via `--cycle`. **Always set `--state todo`** — issues in Backlog don't work with cycles. **Exception:** High priority or above (priority ≤ 2: Urgent, High) always go into the current active cycle regardless of capacity.
 2. **Every issue must belong to a project and a milestone.** Never create orphan issues and never leave an issue outside a milestone.
-3. **If the correct project does not exist, create it before creating the issue.** Do not park work in a generic team backlog while waiting to organize it later.
+3. **Place the issue in an existing project — never invent one.** The initiative's `M` projects are the signed proposal's milestones; find the one the work falls under. A new project is correct *only* for work the requester confirmed is out of scope, and then only as the next `[KEY] R<n> — <Name>` revision project (see "Never invent a project"). Don't park work in a generic team backlog either — if you truly cannot place it, say so rather than manufacturing a home for it.
 4. **If the correct milestone does not exist, create it before creating the issue.** Milestone creation is part of issue intake, not optional cleanup. **Never add an issue to a completed milestone** — only open milestones may receive new issues. If no open milestone matches the issue, create a new one; do not reuse a completed one.
 5. **Use milestones for sequencing.** Milestones can have target dates, making them useful for communicating delivery phases to clients.
 6. **Track progress in Linear.** After creating/updating projects or milestones, update the initiative's content in Linear to reflect the current structure (see "Post-Organization: Update Initiative in Linear" below).
@@ -693,10 +740,12 @@ node linear.mjs list-projects
 # List milestones within a project
 node linear.mjs list-milestones "$PROJECT_ID"
 
-# If needed, create the missing project or milestone before creating the issue
-PROJECT_ID="$(node linear.mjs create-project --name "[CLIENT] Feature Area" --description "Short description" | node -e "process.stdin.once('data',d=>console.log(JSON.parse(d).data.projectCreate.project.id))")"
+# If the milestone is missing, create it inside the EXISTING M project (never a new project)
 MILESTONE_ID="$(node linear.mjs create-milestone "$PROJECT_ID" "Phase 1" | node -e "process.stdin.once('data',d=>console.log(JSON.parse(d).data.projectMilestoneCreate.projectMilestone.id))")"
 
+# Creating a project is only for a CONFIRMED out-of-scope revision — next R<n>, same initiative
+node linear.mjs create-project --name "[KEY] R1 — Revision Name" --initiative "$INITIATIVE_ID" --description "Short description"
+
 # Create an issue within a project and milestone (with cycle)
 node linear.mjs create-issue \
   --title 'Add provider create form' \

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md

@@ -146,3 +146,9 @@ The model's prior is mostly Zod 3 — these are the idioms that changed. Get the
 - **Format errors with the built-ins**, not `zod-validation-error`: `z.prettifyError()` (human string), `z.treeifyError()` (nested, replaces deprecated `.format()`), `z.flattenError()` (replaces deprecated `.flatten()`).
 - **`.default()` applies to the *output* type** and short-circuits parsing when input is `undefined`. For the old "run the default through the schema" behavior, use `.prefault()`.
 - **`z.coerce.*` input type is now `unknown`** (not the output type) — fine for h3 query/body parsing, but affects schemas you consume elsewhere.
+- **`.default()` fires even under `.optional()` (and through `.partial()`)** — `someDefaulted.optional()` still emits the default for a missing key, so a defaulted field can never signal "not provided". The classic trap is deriving a PATCH body from a create schema: `CreateSchema.partial()` silently fills every defaulted field, so `body.someField !== undefined` is always true and "was this field sent?" logic (partial updates, tree-replace triggers) misfires on every request. For PATCH schemas, compose from bare **undefaulted** field schemas and add `.optional()` per field:
+  ```typescript
+  const itemsSchema = z.array(ItemSchema); // no .default([]) here
+  const createSchema = z.object({ items: itemsSchema.default([]) });
+  const patchSchema = z.object({ items: itemsSchema.optional() }); // undefined ⇢ "not sent"
+  ```

package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md

@@ -13,10 +13,18 @@ but your custom `@theme` tokens fail with *"Cannot apply unknown utility class."
 
 ```css
 /* ❌ @reference "tailwindcss";  → @apply text-fg fails */
-@reference "../assets/css/main.css";   /* ✅ exposes YOUR tokens; path is relative to the file */
+@reference "~/assets/css/main.css";   /* ✅ exposes YOUR tokens */
 .prose :where(h2) { @apply text-fg; }
 ```
 
+Prefer the bundler alias (`~/` in Nuxt, or your Vite alias) over a relative
+path — `@tailwindcss/vite` resolves aliases in `@reference` fine, and the alias
+survives file moves. A relative path (`"../assets/css/main.css"`) is depth-
+sensitive: move the file a directory deeper (e.g. a route-namespace refactor)
+and the production build fails with
+`[@tailwindcss/vite:generate:build] Can't resolve '../assets/css/main.css'` —
+typecheck, tests, and dev can all stay green; only the real build catches it.
+
 Better still in scoped styles: skip `@apply` and consume the generated CSS
 variables directly — `color: var(--color-fg)` always works with no `@reference`.