@rallycry/conveyor-skills 1.0.16 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "Shared Claude Code skills for Conveyor consumer repos, linked into .claude/skills via the conveyor-skills CLI",
   "keywords": [
     "claude",

package/skills/conveyor-build/SKILL.md

@@ -201,6 +201,11 @@ and never silence a failure with a filter, a `.skip`, or a "known flake" note:
 either your diff broke it, or the test is broken or environment-dependent and
 you fix the test.
 
+**A schema change regenerates its pages.** Run the project's own generate step
+after changing the schema (in Conveyor, `bun run db:generate` rewrites
+`docs/schema`) and commit the regenerated pages with the change. Never edit a
+schema page by hand: CI fails a pull request whose pages are stale.
+
 **Long gates in a pod: background them the sanctioned way.** Launch a long
 gate with the harness's `run_in_background` Bash option and end the turn — the
 runner tracks the launch, holds pod liveness while a gate process is alive,
@@ -291,6 +296,22 @@ in chat and mark it Complete.
 
 ## Open the PR
 
+### The PR body
+
+Write the parts a person reads; Conveyor appends the rest.
+
+- `## Summary`: 2-4 sentences on what changed and why.
+- `## User flow`: for a user-facing change, the steps a person takes and what
+  they see.
+- `## Screenshots`: the captures from Verify (the existing rule above).
+- `## Happy path & edge cases`: 3-6 bullets: the paths you verified, and the
+  edge cases you deliberately did NOT handle, so a reviewer can veto
+  over-engineering or ask for one.
+
+Never write `## Schema & wire changes` or `## Showcase` yourself: Conveyor
+appends each one when it applies (a project with schema pages whose PR changed
+them; a card with showcase attachments) when it opens the PR. Say why the schema changed in the Summary instead.
+
 ### Readiness policy
 
 A newer base alone is not a reason to refresh an already-green branch. Keep that

package/skills/conveyor-plan/SKILL.md

@@ -151,6 +151,13 @@ Actionability bar — every step must survive a context-free reader:
 - No "as discussed", no links to this chat, no TODOs the executor must
   research from scratch.
 
+**A plan that changes stored data or the wire contract adds a `## Schema
+impact` block** ([references/plan-format.md](references/plan-format.md)): the
+models it touches in a `schema` fence, the proposed delta as a `mermaid`
+`erDiagram`, and one line on which existing field or relation already stores
+the fact. That line is where a denormalization gets caught, such as a coach's
+authority copied into a permission field when a role relation already records it.
+
 **Close with the Builder briefing, and write it for the NEXT session.** Every
 other section addresses a reader; this one addresses the agent that will inherit
 this card having read the card and nothing else — no research, no dead ends, no

package/skills/conveyor-plan/references/plan-format.md

@@ -2,13 +2,26 @@
 
 ## Plan Format
 
-```markdown
+````markdown
 ## Objective
 One sentence: what this task accomplishes and why.
 
 ## Approach
 High-level strategy with relevant files/patterns/APIs.
 
+## Schema impact
+Only when the plan changes stored data or the wire contract; omit it otherwise.
+```schema
+Task
+```
+```mermaid
+erDiagram
+  Task {
+    String reviewNote "added, optional"
+  }
+```
+Already stored? The existing field or relation that holds this fact today, or "none".
+
 ## Implementation Steps
 1. Concrete step.
 2. Concrete step.
@@ -26,7 +39,24 @@ High-level strategy with relevant files/patterns/APIs.
 - **Already decided:** choices the builder should not reopen, one line of why each.
 - **Traps:** what looks right and is not.
 - **Verify in this order:** cheapest disqualifying check first.
-```
+````
+
+## Schema impact — propose the delta, never a page
+
+Only a plan that changes stored data or the wire contract carries this block.
+
+- A `schema` fence names the models the plan touches. Each renders as its
+  current diagram from the project's generated schema pages, so a reviewer
+  sees what exists before the change.
+- A `mermaid` `erDiagram` shows the proposed delta: only the models and fields
+  that change, each change named in its quoted comment (`"added"`,
+  `"removed"`, `"renamed from x"`).
+- One line answers **which existing field or relation already stores this
+  fact?** "None" is a fine answer. A second copy of a fact (a permission column
+  beside the role that grants it) needs a stated reason, or it is a
+  denormalization to design out now.
+- Never write or edit a schema page in a plan. The builder changes the schema
+  and regenerates the pages, which then record what actually shipped.
 
 ## Citations — ground every code step in the code
 

package/skills/conveyor-review/SKILL.md

@@ -55,10 +55,16 @@ the loop.
 1. `mcp__conveyor__get_task` for the plan — you cannot judge "does this do what
    it says" without the "what it says".
 2. **Ask the PR what you are reviewing, BEFORE any diff:**
-   `gh pr view <pr> --json state,baseRefName,headRefOid,files`. The PR's base is
+   `gh pr view <pr> --json state,baseRefName,headRefOid,files,body`. The PR's base is
    often not the project default branch, and asking costs one call instead of
    six spent guessing.
-3. Get the diff with the **merge-base** form, never two-dot, and **fetch the
+3. **Read the PR body's `## Schema & wire changes` section first** when it has
+   one (Conveyor generates it from the changed files). Check each model and
+   contract it lists against the plan's `## Schema impact` block: a model the
+   plan never named, or a proposed delta that did not land, is a finding. The
+   section lists the files as they were at the last `create_pull_request`
+   call; when it disagrees with the diff, the diff wins.
+4. Get the diff with the **merge-base** form, never two-dot, and **fetch the
    base first** — a pod clones single-branch, so `origin/<base>` does not exist
    until you ask for it and the diff fails or silently compares against nothing:
 
@@ -69,18 +75,18 @@ the loop.
    Two-dot (`git diff <base>..HEAD`) compares against the base TIP, so it
    reports already-merged commits as part of this change and sends you reviewing
    code nobody here wrote.
-4. **When the diff and the PR disagree, the PR wins.** Diff the head SHA
+5. **When the diff and the PR disagree, the PR wins.** Diff the head SHA
    directly instead (`git diff <headSha>^ <headSha>`). Your checkout can be
    stale and so can the remote branch tip — a merged PR's commit may be
    reachable only by SHA. If the PR reports `MERGED` or `CLOSED`, say so and
    review the recorded head SHA rather than assuming your tree matches it.
-5. **Read the code under review out of the PR's commit, not the working tree:**
+6. **Read the code under review out of the PR's commit, not the working tree:**
    `git show <sha>:<path>` and `git grep <pattern> <sha>`. Grepping the working
    tree when the PR is based elsewhere returns confident, wrong answers — it has
    produced false review findings.
-6. Read the surrounding code before judging consistency. A pattern is only a
+7. Read the surrounding code before judging consistency. A pattern is only a
    pattern if the neighbours share it.
-7. `mcp__conveyor__get_tag` on the card's tags — a tag's overview and linked
+8. `mcp__conveyor__get_tag` on the card's tags — a tag's overview and linked
    rules are what "follows existing patterns" actually means in this project.
 
 ## Criteria
@@ -96,6 +102,11 @@ the loop.
 - **Test coverage** — are new paths tested? Edge cases covered? A test that
   asserts nothing is worse than no test, because it reads as coverage.
 - **Typing** — proper types, no unnecessary `any`, correct async/await.
+- **Data model** — a fact stored twice (denormalization), a nullable column
+  with no stated reason, a relation that duplicates an existing path, a
+  contract member without `describe`, and a hand-edited or stale schema page
+  (its generated header line is missing, or the project's generate step leaves
+  a diff).
 - **Naming and readability** — clear names, and no comment that says something
   the code does not do.
 

package/skills/conveyor-workflows/SKILL.md

@@ -112,6 +112,14 @@ labels. Each tag carries a `description` (≤255 — the summary), an `overview`
   overview/description only when your change altered what the term means, add
   the tag to the card only when the work is genuinely about that area, and
   skip freely otherwise. Never bulk-assign tags from path matches alone.
+- **The schema note**: on a project with schema pages, the in-pod
+  `create_pull_request` also returns a "Schema & wire changes detected" line
+  (`schemaNote`) naming the changed models, contracts and schema sources, and
+  the PR body carries the generated section (on both surfaces). When it says
+  the schema sources changed but no page did, regenerate the pages, commit
+  them, and call `create_pull_request` again: it reuses the open PR and
+  rewrites the section. A project without schema pages
+  can set them up with the public guide `guides/schema-pages`.
 
 ## Execute