devrites 2.6.1 → 3.0.1

package/pack/generated/claude/skills/devrites-frontend-craft/reference/fullstack.md

@@ -0,0 +1,45 @@
+# Fullstack work (frontend + backend together)
+
+Most UI features also need backend. Don't build the two sides blind to each other, and
+don't build "all backend, then all frontend" — that hides integration risk until the end.
+
+## Contract first
+Define the **API / data contract** before either side codes against it — shape, field
+types + units, status codes, **error bodies**, pagination, idempotency. Use
+`devrites-api-interface`; doubt it with `devrites-doubt` before standing it. With the
+contract fixed:
+- the **backend** slice can land against it (consumer stubbed),
+- the **frontend** slice can build against a mock or the real contract.
+Neither side blocks the other, and the seam stays stable.
+
+## Slice vertically through the layers
+Each slice cuts **one capability** end-to-end — data/model → service → API → UI — and
+leaves a **working, demoable path**. "Create item" is a slice (persist + endpoint +
+minimal form); "all the models" is not. Order by dependency; the first slice is the
+thinnest end-to-end path so integration surprises surface early and cheap.
+
+## Apply the right discipline to each layer
+- **Backend part** → the engineering rules: validate untrusted input at the boundary,
+  authz on every sensitive action, parameterized queries, fail closed, no secrets in
+  logs (`security.md`); fail-fast errors with meaningful messages (`error-handling.md`);
+  measure-first performance (no N+1) (`performance.md`).
+- **Frontend part** → frontend craft: shape (all states), the design system, and the
+  2026 [quality-standards](quality-standards.md) (CWV, WCAG 2.2, responsive, motion).
+- Map the API's error/edge responses to **real UI states** — every error the contract can
+  return needs a handled, helpful UI state, not a blank screen.
+
+## Placement spans both sides
+The investigation's placement analysis covers **where the backend logic lives** *and*
+**where the UI component lives**, plus the contract that joins them — so each side is
+correctly placed, not bolted on.
+
+## Prove BOTH layers
+A fullstack slice is proven only when both sides have evidence:
+- backend/contract: tests for the endpoint + its error/edge cases (and a real
+  request/response observation);
+- frontend: browser proof (states exercised, console clean, responsive, a11y).
+If only one side is proven, the slice is **not** done.
+
+## Keep them in sync
+A change to the contract after both sides exist is a **Spec Drift Guard** event — it
+affects FE and BE together. Stop, record it, re-plan the contract, then update both sides.

package/pack/generated/claude/skills/devrites-frontend-craft/reference/quality-standards.md

@@ -0,0 +1,234 @@
+# Frontend quality standards (2026)
+
+The measurable bar UI work is held to. Project conventions win where they're stricter;
+these are the floor, not the ceiling.
+
+## Performance — Core Web Vitals (field/p75 targets)
+- **LCP** (Largest Contentful Paint) ≤ **2.5 s**
+- **INP** (Interaction to Next Paint — the current responsiveness metric, replaced FID)
+  ≤ **200 ms**
+- **CLS** (Cumulative Layout Shift) ≤ **0.1**
+- Keep an interactive page's shipped JS lean (a budget around **≤400 KB gzipped** is a
+  good default); lazy-load below-the-fold and heavy/optional code; minimize hydration;
+  size and reserve space for images/media to avoid layout shift.
+
+## Accessibility — WCAG 2.2 AA
+- **Semantic HTML first** — real `<button>`/`<nav>`/`<label>`/headings; ARIA only to fill
+  gaps semantics can't.
+- **Keyboard**: every interactive element operable by keyboard; logical tab order; **focus
+  visible** with ≥ **3:1** contrast against its background (never remove the outline
+  without an equal replacement).
+- **Contrast**: text ≥ **4.5:1** (≥ 3:1 for large text and UI/graphics).
+- **Target size**: ≥ **24×24** CSS px (WCAG 2.2 AA, SC 2.5.8); prefer **44×44** for primary
+  touch targets.
+- **No drag-only** interactions — provide a single-pointer alternative (SC 2.5.7).
+- Labels/names on all controls; errors announced; respects `prefers-reduced-motion`.
+- **Test** with keyboard, a screen reader, and an automated checker (e.g. axe) — early.
+
+## Motion
+- Purposeful only; UI feedback ~≤200 ms, transitions ~≤500 ms. Never animate to mask slow
+  loading. Honor `prefers-reduced-motion` (reduce/remove non-essential motion).
+
+## Responsive
+- Fluid layouts; no fixed widths that break. Verify at **320 / 768 / 1024 / 1440** px; no
+  horizontal scroll; survives **200% text zoom**.
+- **`dvh`, not `vh`**, for full-height surfaces (`min-height: 100dvh`, never `h-screen` /
+  `100vh` — mobile address bars break them). A hero fits the *initial* viewport: headline
+  ≤2 lines, primary CTA above the fold.
+
+## Design system
+- Use the project's **tokens** (spacing/type/color roles) — never hard-code a value a
+  token covers. Compose from existing components; one icon set.
+
+### Consistency locks (one per surface)
+Lock these in `design-brief.md` and hold them page-wide — mid-scroll drift ("a different
+website by section 7") is a tell: **one accent** (no new accent appearing later on the
+page), **one radius scale**, **one theme** (light or dark, not both).
+
+## Numerical bar (enforceable specifics)
+
+These are the hard numbers that move "good UI" from opinion to checkable.
+Project tokens win when stricter; these are the floor.
+
+### Color
+- **OKLCH-only** for new tokens — perceptually uniform, predictable lightness
+  steps across hues. Stop reaching for HSL; the lightness lies.
+  - Example: `oklch(0.62 0.18 264)` for a saturated primary.
+- **Never `#000` / `#fff`** as raw values. Pure black/white are too harsh and
+  too clinical; use a near-black (`oklch(0.18 0 0)`) and near-white
+  (`oklch(0.98 0 0)`) or the project's surface tokens.
+- Contrast follows WCAG 2.2 — text ≥ 4.5:1, UI/graphics ≥ 3:1. Verify
+  against the *rendered* background, not the theoretical one.
+- **Tint neutrals toward the brand hue** — pure-grey neutrals look sterile.
+  Nudge every grey 0.005–0.01 chroma toward the brand colour — invisible at
+  a glance, but the surface stops feeling generic.
+- **Alpha is a smell** — heavy translucency usually means an incomplete palette.
+  Define explicit overlay/hover tokens; transparency is for focus rings and scrims.
+- **Every colored surface token ships its `on-` pair** (`primary`/`on-primary`,
+  `destructive`/`on-destructive`, …) so contrast is designed in, not patched after.
+
+#### Color commitment — pick the strategy before the palette
+Decide *how committed* the surface is to colour before opening the picker.
+Four positions on a single axis; pick one, then design within it:
+
+| Strategy | Rough coverage | Use for |
+|---|---|---|
+| **Restrained** | tinted neutrals + 1 accent ≤ ~10% of the surface | Most product UI; brand surfaces that want to look quiet. |
+| **Committed** | one saturated colour carries 30–60% of the surface | Brand pages with a strong identity; product feature surfaces that need a hero colour. |
+| **Multi-role** | 3–4 named colour roles, each used deliberately | Brand campaigns; product data-viz with distinct meanings. |
+| **Saturated** | the surface *is* the colour — full-bleed colour ground | Brand heroes, campaign pages, splash moments. |
+
+Two corollaries:
+- The "one accent ≤ ~10%" rule belongs to **Restrained only.** Committed /
+  Multi-role / Saturated exceed it deliberately. Don't collapse every
+  surface back to Restrained by reflex.
+- *Register* (brand vs product) doesn't pick the strategy by itself — brand
+  surfaces aren't always Saturated, product surfaces aren't always
+  Restrained. Pick from the scene, not the category.
+
+### Calibration — density & motion
+Colour commitment fixes *how much colour*; two more axes fix *how much space* and
+*how much movement*. Set one position on each — from the **scene sentence**, the same
+way colour is picked — and carry both in `design-brief.md` so the build targets a
+calibration instead of re-deciding it per slice.
+
+**Density** — information per viewport; drives which spacing steps dominate:
+
+| Position | Feels like | Spacing steps that dominate | Use for |
+|---|---|---|---|
+| **Airy** | gallery / calm / room to breathe | `32 / 48 / 64 / 80 / 96` | brand pages, onboarding, focus moments, low-data surfaces |
+| **Balanced** | most product UI | `16 / 20 / 24 / 32` | dashboards, forms, settings — the default |
+| **Dense** | cockpit / data-rich / power tool | `4 / 8 / 12 / 16` | tables, monitors, terminals, pro tools lived in all day |
+
+**Motion** — how much the surface moves; drives which motion classes (table below) are in play:
+
+| Position | Feels like | Motion classes in play | Use for |
+|---|---|---|---|
+| **Minimal** | crisp, almost still | Instant + State | dense tools, regulated/trust surfaces, reduced-motion-leaning |
+| **Standard** | responsive, purposeful | Instant + State + Layout | most product + brand UI — the default |
+| **Expressive** | choreographed, scroll-aware | + Entrance, deliberate sequencing | brand heroes, launch/campaign moments, story scroll |
+
+Corollaries (same shape as colour commitment):
+- Pick from the **scene sentence**, not the category — "an on-call SRE at 2am" → Dense +
+  Minimal; "a launch hero in afternoon light" → Airy + Expressive. Register doesn't decide
+  it by itself.
+- `prefers-reduced-motion` overrides Motion **downward at runtime** regardless of position —
+  an Expressive surface still ships a Minimal path.
+- The position is a target, not a straitjacket: a surface may break density locally for
+  emphasis — name the exception in the brief, don't let the whole page drift off it.
+
+### Spacing
+- **4pt base scale** (`4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 64 / 80 /
+  96`). Project tokens may use a multiplier; never hardcode in-between
+  values.
+- Inline spacing rhythms in multiples of 4 px. Optical alignments may need a
+  1 – 2 px nudge — record the *why* in a comment.
+
+### Typography scale
+- **Brand surfaces**: fluid `clamp()` headings (e.g.,
+  `clamp(2rem, 1rem + 3vw, 3.5rem)`). Display/body pairing OK.
+- **Product surfaces**: **fixed rem scale** (1.125 – 1.2 ratio). One family
+  usually carries headings, body, labels, data.
+- Body line-height ~1.5; headings ~1.1 – 1.25. Prose width ~ 65–75 ch.
+- Display ceiling: `clamp()` max ≤ ~6rem — larger is shouting. Display
+  letter-spacing floor **≥ −0.04em**; tighter and the letters touch.
+- `text-wrap: balance` on h1–h3; `text-wrap: pretty` on long prose.
+
+### Motion
+| Class | Duration | Use |
+|---|---|---|
+| Instant | 100 – 150 ms | Hover/press, tooltip enter, color shifts |
+| State | 200 – 300 ms | Toggle, focus ring, dropdown |
+| Layout | 300 – 500 ms | Modal/drawer enter, route transitions |
+| Entrance | 500 – 800 ms | Page entrance, hero animation |
+
+- **Exit at ~75 % of enter.** A 300 ms enter pairs with a 225 ms exit.
+- **Bounce / elastic easing banned** unless the project's design system
+  explicitly uses it.
+- Honor `prefers-reduced-motion` — reduce or remove non-essential motion
+  entirely.
+
+### Dark mode (three-axis compensation)
+A token-flip dark mode is sterile. When the project ships dark, compensate
+three axes from light:
+- **Line-height** `+0.05 – 0.10` (text breathes more on dark surfaces).
+- **Letter-spacing** `+0.01 – 0.02 em` (perceived spacing tightens on dark).
+- **Weight** `+1 step` for very small or low-contrast text.
+
+If the project has dark tokens already, follow them. If not and dark is in
+scope, propose the compensation rather than ship a flat invert.
+
+### Focus & states (8 required)
+Every interactive element ships **8 visual/interaction states**:
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`,
+`selected`, and an error/invalid surface when relevant.
+- `:focus-visible` ring: **2 – 3 px**, **≥ 3:1** contrast against the
+  background, **offset 2 px** so the focus is unambiguous on dense layouts.
+
+### Container queries vs viewport queries
+- **Component breakpoints** — use **container queries** (`@container`). The
+  same card adapts to its column whether the viewport is 320 or 1920.
+- **Page-level layout** — use viewport queries
+  (`@media (min-width: ...)`) for sidebar collapses, header reflows.
+- Mixing the two is normal; using only one is usually a code smell.
+
+### Semantic z-index scale
+Pick a scale per surface role; never use raw `z-index: 9999`. Suggested
+floor:
+
+| Role | z |
+|---|---|
+| Base content | `auto` / `0` |
+| Sticky header | `50` |
+| Dropdown / popover | `100` |
+| Drawer / sheet | `200` |
+| Modal | `300` |
+| Toast | `400` |
+| System dialog / debug overlay | `500` |
+
+### Materiality (elevation & surface)
+Depth is earned, not defaulted. Reach **down** this ladder in order; stop at the first
+rung that carries the structure.
+- **Hairline first.** A **1 px border / divider** (a hairline in a near-neutral token)
+  defines structure before any shadow does. Borders separate; shadows lift. Most "cards"
+  want a hairline, not elevation.
+- **Elevation is a token scale, not an ad-hoc value.** When a surface genuinely lifts
+  (menu, popover, dragged item), use a **small shadow set from the design system** with one
+  consistent light source — never a one-off `box-shadow`. The elevation step and the
+  semantic z-index role move together.
+- **Texture needs contrast.** Grain / noise / pattern earns its place only when it reads
+  against the surface. Invisible texture is bytes with no signal — drop it.
+- **Asset-led material.** Rich material (photographic grain, real product imagery,
+  generated art) comes from a **real raster / generated asset**, not an SVG/CSS
+  approximation of one. Don't fake a photo with gradients; ship the asset or use a flat
+  token.
+- **No decorative glass.** `backdrop-filter: blur(...)` is for a fixed/sticky surface over
+  moving content (a sticky header, a sheet over scroll), never a default panel look
+  (`rite-polish/reference/anti-ai-slop.md`).
+
+### NEVER (UI numerical bar)
+- Never ship a pure `#000` or `#fff` raw value.
+- Never hard-code a spacing value the 4 pt scale or project tokens cover.
+- Never use bounce/elastic easing without an explicit design-system reason.
+- Never animate an exit at 100 % of enter duration (feels uncontrolled).
+- Never use raw `z-index` numbers outside the semantic scale.
+- Never use viewport queries for component-internal reflows when the
+  component is reused at different widths.
+- Never ship dark mode as a flat token invert (compensate three axes).
+- Never reach for a shadow where a 1 px hairline carries the structure.
+- Never invent a one-off `box-shadow` outside the elevation token set.
+- Never ship texture / grain that doesn't read against its surface.
+
+## Verification gate (a UI slice isn't done until all pass)
+- [ ] Renders with **no console errors/warnings**
+- [ ] **Keyboard**: tab through reaches everything; focus visible; Esc/Enter behave
+- [ ] **Screen reader** conveys content + structure
+- [ ] **All states**: default / loading / empty / error / success / disabled
+- [ ] **Responsive** at 320 / 768 / 1024 / 1440; no overflow; zoom-safe
+- [ ] **No accessibility violations** (axe or equivalent)
+- [ ] Meets the **CWV budget** above (measure, don't assume)
+- [ ] Aligned to the **design system** (tokens, components, type, spacing)
+- [ ] Clickables show `cursor: pointer` + a hover state; icons are SVG from the one set
+      (no emoji); nothing trapped under fixed/sticky bars
+- [ ] **Consistency locks hold** (one accent / one radius scale / one theme) and the
+      mechanical pre-flight passes (`rite-polish/reference/anti-ai-slop.md`)

package/pack/generated/claude/skills/devrites-frontend-craft/reference/reuse-first.md

@@ -0,0 +1,59 @@
+# Reuse first — frontend application
+
+Frontend-specific application of the canonical reuse rule in
+[`.claude/skills/devrites-lib/reference/standards/coding-style.md`](../../devrites-lib/reference/standards/coding-style.md#reuse-before-you-write)
+(and the slightly longer treatment in `standards/patterns.md`). Same principle —
+**reuse → extend → build new**, with the AHA caveat. This file walks it through for
+components, styles, tokens, icons, hooks, utils, and helpers in a UI feature.
+
+Consistency comes from **one source of truth**. Before creating any new component, style,
+token, icon, hook, util, or helper for the feature, **search the project** for an
+existing one that fits. Reuse it. Don't duplicate.
+
+This applies to UI **and** non-UI code: utilities, helpers, types, validators, schemas,
+formatters, hooks, query helpers — anything that might already exist.
+
+## The decision (in order)
+1. **Search first.** Use a code-intelligence index if available — codebase-memory-mcp first,
+   cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob); see
+   `../../devrites-lib/reference/standards/tooling.md` — to find
+   similar definitions; fall back to grep/glob over `components/`, design tokens, hooks/,
+   utils/, lib/. Look for things doing the *same job*, not just the same name.
+2. **Exact fit → REUSE.** Compose / import the existing thing. No copy, no fork.
+3. **Close fit → EXTEND.** Add a variant/prop/option that the existing component or util
+   can carry without distortion. Adding a prop to a button is fine; adding ten props that
+   each branch the internals is not.
+4. **No fit → BUILD NEW**, in the project's idiom. If a similar need is likely to recur,
+   propose adding it to the shared system (component library / utils module). If it's
+   truly one-off, build it locally — don't pre-abstract.
+
+## When to *avoid* reuse (the AHA caveat)
+Reuse is good; **forcing** it isn't. **Avoid Hasty Abstractions**: if making the existing
+thing fit means warping its API or breaking its contract for one caller, **don't**.
+Duplication is cheaper than the wrong abstraction. Build a sibling component/util and let
+a real pattern emerge from two or three callers before consolidating.
+
+## Record the decision (per slice)
+On each slice, note what was reused / extended / created new — so the seal can see the
+consistency story and reviewers can spot silent duplication.
+
+```
+Existing reused: <Button, useToast, formatCents>
+Extended: <Card — added variant="elevated">
+Created new: <ExportProgress (no prior equivalent; propose for shared lib)>
+```
+
+## Anti-patterns to name
+- Silently re-implementing an existing component / hook / util because it was easier than
+  finding it. Search first.
+- Copy-pasting a component from `components/` into the feature folder. That's a fork.
+- Adding a second icon set / second toast library / second date util because the existing
+  one didn't quite fit — almost always extend the existing or ask first.
+- Forcing reuse via 8 boolean props that branch the internals — that's an abstraction
+  collapsing under its own weight. Split it.
+
+## Search hints
+- **UI**: `components/ui/`, design-system package imports neighboring features use,
+  `tokens.*` / Tailwind config / theme files, icon barrel files, layout primitives.
+- **Non-UI**: `lib/`, `utils/`, `helpers/`, `services/`, `validators/`, `schemas/`,
+  `hooks/`, language stdlib equivalents.

package/pack/generated/claude/skills/devrites-frontend-craft/reference/shape.md

@@ -0,0 +1,60 @@
+# Shape before code
+
+Decide what the UI *is* before how it looks. Aesthetics follow structure; structure
+follows the user's goal. Skipping this is how you get pretty UI that doesn't work.
+
+**The feature-level shape already exists.** `/rite-spec` ran `devrites-ux-shape` and wrote
+`design-brief.md` (design direction, key states, interaction model). In `/rite-build` this
+is a **per-slice refinement of that brief for the surface you're about to code** — confirm
+the answers below against the brief and fill any slice-specific gaps; don't re-derive the
+design. **Only shape from scratch here** when a UI slice has no `design-brief.md` (a spec
+written before shaping) — then run `devrites-ux-shape` first, or answer these and write the
+brief inline.
+
+## Answer these before writing markup
+1. **User goal** — what is the user here to accomplish? One sentence.
+2. **Primary action** — the single most important thing on this surface. It must be
+   visually obvious. Everything else is secondary.
+3. **Information hierarchy** — what must be seen first, second, third. Rank content;
+   the layout expresses the ranking.
+4. **States** — design all of them, not just the happy path:
+   - default / populated
+   - loading (initial + subsequent)
+   - empty (with a clear next action — welcoming, not a dead end)
+   - error (what happened + how to recover)
+   - success
+   - disabled / read-only / no-permission
+   - long content / overflow / many items
+5. **Responsive** — how it reflows from small (320) to large (1440). What collapses,
+   stacks, hides, or scrolls.
+6. **Accessibility** — focus order, labels, contrast, keyboard operability, semantics.
+7. **Interaction model** — what's inline vs. navigated vs. (rarely) a modal; optimistic
+   vs. pending; how feedback is given.
+
+## Ask when ambiguous
+If the visual direction or the UX flow isn't determined by the existing system + the
+spec, ask the user (show 2–3 concrete options) before building. Guessing a flow is
+expensive to undo once coded.
+
+## Output
+The answers live in the feature's `design-brief.md` (shaped at spec by `devrites-ux-shape`).
+In build, append any slice-specific refinement to its **Build-time refinements** section;
+if you shaped from scratch (no brief existed), write the brief now per
+`../../devrites-ux-shape/reference/brief-template.md`. This drives the build and the polish
+checklist.
+
+## NEVER (shape)
+
+- Never start coding markup without naming the **primary action** for the
+  surface.
+- Never design only the populated/happy state. Empty / loading / error /
+  disabled / long-content are not optional.
+- Never decide the visual direction by personal taste when the project has
+  an existing system. Discover first (`design-references.md`).
+- Never invent a new flow when a neighboring feature already has one — match
+  the neighbor, then deviate only with a recorded reason.
+- Never paper over an ambiguous spec with a "reasonable guess". Ask the user
+  with 2 – 3 concrete options.
+- Never name a state for the *technical* condition (`isLoadingTrue`) when
+  the *user-facing* name (`Loading your invoices…`) tells the user what's
+  happening.

package/pack/generated/claude/skills/devrites-interview/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: devrites-interview
+description: Interview the user one question at a time to extract intent. Use when the user says "interview me", "I am not sure what I want", or the ask is underspecified. Not for casual clarification.
+user-invocable: false
+---
+
+# devrites-interview — extract intent
+
+Close the gap between what the user said and what they want, at the cheapest moment —
+before a plan, spec, or code exists.
+
+## Protocol
+- **State a confidence number.** Open with your one-line hypothesis of what the user wants and an
+  explicit **0–100%** confidence in it. The number forces honesty — if you wrote 85% but can't
+  predict how the user reacts to your next three questions, the number is wrong. Below **~70%**,
+  append the single thing still unresolved so the user can close the gap directly.
+- **One question per turn.** Multiple questions get one answered and the rest ignored.
+- **Attach your best guess** to every question, with the reason:
+  > "I'm assuming export is CSV only (covers the stated use case). Right, or also XLSX?"
+  This turns an open question into a cheap correction and exposes your model so the user
+  can fix the premise.
+- **Highest-value question first** — order by how much the answer changes the build. A
+  question that moves the data model or acceptance criteria beats a cosmetic one.
+- **Impact-priority + bounded blocking.** Order unknowns **scope > security/privacy > UX >
+  technical**, and cap **blocking** questions at **≤3** per pass — ask the few that actually gate
+  the spec; **default-and-record** the rest in `assumptions.md` (best-guess + why). A reversible
+  detail never earns a blocking question.
+- **Structured options** when the space is enumerable — present them as the standard ranked
+  **option set** (`standards/afk-hitl.md` → "Option set"): recommended **first**, labelled
+  `(Recommended)`, each with a dimension-tagged rationale (`logic · infra · business ·
+  architecture`, + `security`/`UX`/`risk` when in scope), plus the escape hatch. Render via
+  `AskUserQuestion` when the harness has it:
+  ```
+  1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+  2. <alternative> — <rationale + the trade-off it accepts>
+  3. Something else — I'll describe it
+  ```
+
+## Stop condition
+Stop **opening new questions** when **any** holds — don't interrogate past the point of value.
+(Stopping the interview ≠ deciding for the user: a material call still goes back as a ranked
+option set — confidence lowers the question's *cost* to a one-pick confirm, not its *owner*.)
+- **Confidence — the predict-three test.** The 95% bar is checkable, not a feeling: *can you
+  predict the user's reaction to the next three questions you would ask?* If yes, you're done
+  extracting. If several rounds pass and you still can't predict, something foundational is
+  missing — step back and name it, don't grind out more questions.
+- **Convergence** — the last 2–3 answers only rubber-stamped your guesses and didn't
+  move the spec.
+- **Soft cap** — after ~8 material questions, proceed with your best-guess answers logged
+  in `assumptions.md` rather than asking more (hard-stop sooner if the ask is small).
+
+Depth on the few that matter, not breadth for its own sake. If answers stop converging —
+you keep circling one area without progress — **reframe once** (below) instead of asking
+another question.
+
+## Want vs. should-want
+People answer with what they think they *should* want — the buzzword, the best practice, the
+convention — not what they actually want. Watch for tells: abstract virtues ("scalable", "clean",
+"modern"), deferral to what's conventional, an answer that could be pasted into any project. When
+you hear one, ask the unlock question — *"if you didn't have to justify this to anyone, what would
+you actually want?"* — it often does more than the previous five questions. Extract the real want,
+then record it; don't design to the performed one.
+
+## What counts as a yes
+Approval is an **explicit** yes, and several common replies aren't one:
+- *"Whatever you think is best"* / *"you decide"* — **delegation, not approval.** Re-ask with two
+  concrete options so the user chooses on the substance, not the deferral.
+- *"Sounds good"* / *"sure, let's go"* — a polite exit; probe once that it's real agreement, not
+  fatigue, on anything material.
+- **Silence** — not consent. Half of misalignment is silent disagreement about what *won't* be
+  built. Make the "out of scope" line explicit and get a yes on it too.
+
+## Don't ask
+- Things the codebase answers (read it first).
+- Reversible implementation details (decide, log as an assumption).
+- Everything at once "to be thorough."
+
+## When the ask is vague — map the decision tree first
+For a one-line or fuzzy ask (`"design a contact page"`), don't fire isolated questions.
+First sketch the **decision tree** — the branches the answer splits into — and resolve
+each branch **depth-first** with the protocol above. Domain branches per area:
+`rite-spec/reference/interview-patterns.md`.
+
+## Reframe (once, when stuck)
+If the interview isn't converging, spend **one** turn challenging the premise rather than
+refining it — *"is a form even the right answer here, or a mailto / booking link?"* A good
+reframe collapses several open branches. Use it sparingly, then resume the protocol.
+
+## /clarify mode — coverage scan of an existing spec
+When invoked to clarify a written spec (not extract intent from scratch), scan it against the fixed
+taxonomy and mark each **Clear / Partial / Missing**: Functional scope · Data model · Interaction
+(API / UI states) · Non-functional (auth / latency / scale / compliance) · Edge cases (empty /
+boundary / invalid / concurrent / failure). Then ask **≤5 prioritized questions** (impact order
+above), targeting Missing before Partial, one per turn with a best-guess attached. **Integrate each
+answer into the right spec section** as it lands — not just a Q&A log — and append a dated
+**`## Clarifications`** block to `spec.md` (Q + resolution) for durable provenance. Re-run the scan
+after answers; stop when every area is Clear or explicitly deferred, then re-score the affected
+`checklists/<domain>.md`.
+
+## Output
+A short summary the caller can use: objective in one sentence, confirmed decisions,
+still-open (non-blocking) items, recommended next step. If a workspace is active, write
+Q&A to `questions.md`, confirmed calls to `decisions.md`, standing guesses to
+`assumptions.md`. If not, just return the summary — don't create a workspace.

package/pack/generated/claude/skills/devrites-lib/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: devrites-lib
+description: Internal shared DevRites helper library. Documents cross-cutting engine commands and references; not a user workflow. Do not invoke directly.
+user-invocable: false
+disable-model-invocation: true
+---
+
+# devrites-lib — internal shared helpers (not a command)
+
+This is **not** a skill you run. It is the manifest for DevRites'
+cross-cutting helper operations, each exposed as a subcommand of the global
+`devrites` binary. A skill invokes one as `devrites <op>` — the same call from
+any workspace, with no install layout or script path to resolve.
+
+## Operations
+
+Each is a subcommand of the global `devrites` binary, run as `devrites <op>`.
+
+**Read-only — orient / gate (never mutate the workspace):**
+
+- `devrites-engine preamble` — orientation digest for the active `.devrites/` feature:
+  prints `state.md`, the artifacts present, the run mode (HITL/AFK), and the
+  open-question tally by gate. Run first (step 0) by every workspace-operating
+  `rite-*` skill so the model orients deterministically instead of re-deriving
+  state from raw Markdown.
+- `devrites-engine progress` — progress footer; the mirror of `devrites-engine preamble` (which runs
+  first). Run **last** (output step) by every lifecycle `rite-*` skill to render — from
+  `state.md`, with zero model drift — the `── rite-<phase> ──` header rule, the **slice
+  meter** (`Slice 3/5  ██████░░░░  <last-built> ✓`, or `Slices 5/5  ██████████  ✅ ALL
+  BUILT` at completion), and the **flow ribbon** (`spec ✓ define ✓ build ◉ … ship ○`).
+  The meter answers "how many slices left"; the `✅ ALL BUILT` marker answers "is the
+  build done". The skill prints its own what-was-done / next-step / hygiene lines beneath
+  it. Read-only; silent (exit 0) when there is no active workspace. Not for the workspace-less
+  utilities (`/rite-prototype`, `/rite-zoom-out`, `/rite-pressure-test`, `/rite-handoff`,
+  the `/rite` menu) — they have no phase/slice state to render.
+- `reference/reply-contract.md` — the shared user-facing completion reply contract. It
+  standardizes the compact chat lines printed below `devrites-engine progress` for success,
+  awaiting-human, stopped/blocked, GO, NO-GO, and shipped states. The chat reply is a
+  status summary; durable detail stays in the workspace artifacts.
+- `reference/model-tiers.md` — the dispatch-by-task-shape contract (extraction / generation /
+  ceiling). A skill names a **tier** by the shape of the work and never hardcodes a model name;
+  reviewers are ceiling on purpose. Carries the degradation rule for harnesses that cannot pick
+  models per agent. Loaded on demand by any skill that dispatches subagents.
+- `devrites-engine build-readiness` — build-readiness gate. Exits non-zero on `/rite-build`'s
+  step-0 stop conditions so they hold by exit code, not by prose the model must
+  remember: `2` no `Plan approved` (→ `/rite-define`), `3` `awaiting_human`
+  (→ `/rite-resolve`), `4` `blocked` (→ `/rite-plan`), `5` no workspace, `0` ready.
+- `devrites-engine evidence-fresh` — evidence-freshness gate for `/rite-seal`. Exits `3`
+  when any file in `touched-files.md` is newer than `evidence.md` /
+  `browser-evidence.md` (stale proof = NO-GO until re-proven), `0` when fresh.
+- `devrites-engine check-acceptance` — executable acceptance gate. Compiles `spec.md`'s
+  acceptance IDs and exits `1` unless every one is checked (proven) in `seal.md`;
+  new workspaces use `AC-###`, while legacy archives may still carry old `[ACn]`
+  ids. Used by `/rite-seal` and by the outcome grader.
+- `devrites-engine spec-validate` — spec-grammar gate (the spec-side mirror of
+  `devrites-engine check-acceptance`). Lints `spec.md`'s structured `### Requirement:` / `#### Scenario:`
+  blocks (SHALL/MUST present, ≥1 scenario each, every scenario has WHEN + THEN, headers
+  unique). Exits `1` on a grammar violation, `0` when valid **or** when the spec uses the flat
+  `AC-###` flat-bullet form (no structured blocks — nothing to lint, never a failure). Used by
+  `/rite-spec`'s readiness gate; see [`standards/spec-grammar.md`](reference/standards/spec-grammar.md).
+
+**State mutators — write `state.md` / `questions.md` under one contract:**
+
+- `devrites-engine tick-afk` — decrement the AFK slice budget; exits `3` at 0 (forced HITL stop).
+- `devrites-engine resolve` — backs the `/rite-resolve` contract (answer / drop / batch).
+- `devrites-engine close-out` — archive the workspace + clear `ACTIVE` on `/rite-ship`.
+
+### Canonical footer snippet
+
+Every lifecycle `rite-*` skill prints this as the **first lines of its output**, then its
+own compact fact lines below per [`reply-contract.md`](reference/reply-contract.md):
+
+```bash
+devrites-engine progress
+```
+
+**Unified entrypoint (tool-agnostic):**
+
+- The `devrites` binary is that unified CLI, dispatching to all of the above (`orient` / `ready` /
+  `evidence-fresh` / `acceptance` / `spec-validate` / `tick-afk` / `resolve` / `close` /
+  `active` / `list` / `use`), so any agent or human can drive `.devrites/` without the skill
+  prose. See [`docs/cli.md`](../../../../docs/cli.md).

package/pack/generated/claude/skills/devrites-lib/reference/intent-map.md

@@ -0,0 +1,16 @@
+# Using DevRites: intent map
+
+This is an explicit reference, not a session-start autoload. Load it when the user asks which DevRites rite fits.
+
+| User intent | Route | Notes |
+|---|---|---|
+| New feature / vague product idea | `/rite-spec` (Codex: `$rite-spec`) | Investigate first; do not plan from vibes. |
+| Existing codebase / resume reality | `/rite-adopt` or `/rite-converge` | Adopt derives intent from code; converge appends remaining slices. |
+| Review plan before code | `/rite-vet` | Every defined plan; depth scales to stakes. |
+| Small safe fix | `/rite-quick` | Escalates on auth, migration, public API, destructive, ambiguous, or multi-slice work. |
+| Prove UI/runtime | `/rite-prove` plus `devrites-browser-proof` | Capture real evidence. |
+| Stuck / unfamiliar area | `/rite-zoom-out` | Map structure before changing code. |
+| Teach me | `/rite-explain` | Human learning loop. |
+| Ship? decide readiness | `/rite-seal` | Seal decides; it does not mutate git. |
+| Execute ship after GO | `/rite-ship` | Requires GO/type-GO. |
+| Whole lifecycle unattended | `/rite-autocomplete` | Clean baseline + checkpoint mode; stops on hard gates. |

package/pack/generated/claude/skills/devrites-lib/reference/model-tiers.md

@@ -0,0 +1,43 @@
+# Model tiers — dispatch by task shape, never by model name
+
+The single source for how DevRites skills choose a model for a dispatched subagent. A skill
+names a **tier** by the *shape of the work*; it never hardcodes provider SKUs (Claude,
+OpenAI/ChatGPT, or otherwise) into skill content. Model names change and differ per harness; a tier is stable. Loaded on demand by
+any skill that dispatches subagents (review fan-out, scouts, judges); not a skill itself.
+
+## The three tiers
+
+| Tier | For work that is… | Examples in DevRites | Model policy |
+|---|---|---|---|
+| **extraction** | search-and-quote: retrieval, grep, verbatim quoting, mechanical scanning — no judgement | archive-search scouts, footprint scanning, repo-profile gathering, an evidence-dossier scout | cheapest capable model **when the harness exposes a per-agent override**; otherwise inherit |
+| **generation** | evidence-driven or mechanical verification: apply a rule to text, draft to a contract, check a claim against a source | drafting to a `design-brief`, mechanical convention checks, first-pass claim verification | mid-tier when the harness allows; otherwise inherit |
+| **ceiling** | adversarial judgement and composition: the calls that decide GO/NO-GO or write the artifact a human reads | every reviewer in the seal/review fan-out, `devrites-forge-judge`, `devrites-plan-reviewer`, `/rite-explain` composition | the orchestrator's own model — inherited by declaring **no** model, never dispatched down |
+
+**Reviewers are ceiling on purpose.** Adversarial review is where a cheap model costs the most —
+a missed vulnerability or a rubber-stamp is far more expensive than the tokens saved. DevRites
+agent definitions therefore declare **no** `model:` field: they inherit the ceiling. Do not add
+one to a reviewer to save cost. The tier a scout runs on is where savings are safe.
+
+## The degradation rule
+
+Tiers are an optimization, never a correctness dependency. A skill written against tiers must run
+correctly on a harness that cannot select models per agent, or has no subagent primitive at all:
+
+1. **Per-agent model override unavailable** → dispatch the scout on the **inherited** model and
+   keep its **read budget and output cap**. The cost control falls back to structure, not model
+   choice — this is why every scout dispatch also carries an explicit read budget.
+2. **No subagent primitive at all** → run the scout work **inline** in the orchestrator, with the
+   same budgets. The tier still tells you how much to spend, even with nothing to dispatch to.
+
+A skill that only works when it can pick a cheap model is broken. The tier names the *intent*; the
+budget enforces it regardless of what the harness can do.
+
+## How a skill references a tier
+
+Name the tier and the budget where you dispatch; never the model:
+
+> Dispatch an **extraction-tier** scout (read budget: 20 files, output cap: the dossier path + a
+> 3-line gist) to quote every call site of `X` into `<scratch>/dossier.md`.
+
+Not: "dispatch a cheap Claude/OpenAI model to…". If a future reviewer needs to know why a scout is cheap,
+this file is the answer; the skill stays legible and portable.