devrites 2.6.1 → 3.0.1

package/pack/generated/claude/skills/devrites-ux-shape/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: devrites-ux-shape
+description: Plan UX/UI before code: design direction, design brief, visual direction, key states, interaction model for screens/forms/dashboards/settings pages. Use when shaping UI. Not for building/polish.
+user-invocable: false
+---
+
+# devrites-ux-shape — plan the UX/UI before code
+
+Decide what the UI *is* and how it should look and behave **before** code, and write it to
+the feature's `design-brief.md` — the contract the build (`devrites-frontend-craft`),
+polish, and seal all check against. This is "shape before code" raised to a **feature-level
+artifact**: produced once at spec time, refined per slice. It is **woven into the
+lifecycle** (`/rite-spec` calls it when UI is detected; `/rite-build` refines it), not a
+separate phase the user runs.
+
+## When it runs
+- `/rite-spec` invokes it after references-intake when the feature touches UI
+  (`../rite-build/reference/frontend-trigger.md`). Output: `design-brief.md` + a
+  confirmation pause.
+- `/rite-build` / `devrites-frontend-craft` read the brief as the **build target** and
+  refine it for the slice's surface — they don't re-derive it.
+- Skip entirely for backend / data / CLI / infra-only features.
+
+## 1. Foundation — discover, don't impose
+Reuse what's there first. Read the design system + register and any references the spec
+gathered:
+- Design system + register (tokens, components, type, spacing, neighbors; brand-vs-product)
+  → `../devrites-frontend-craft/reference/design-references.md`.
+- `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` if present — anchors that reduce questions.
+  `DESIGN.md` is the project's **rolled-up design memory** (tokens, calibration baseline,
+  proven component behaviors) earlier features sealed via `../rite-ship/reference/design-memory.md`;
+  treat it as the inherited system — read it before re-discovering, depart only on signal.
+- `references.md` + `references/` — the screenshots / Figma / video / links the human
+  supplied. Honor each recorded role: **target** = fidelity contract, **constraint** =
+  required rule, **inspiration** = extract only the cited principle.
+
+## 2. Discovery — one round, assert-then-confirm
+Understand the feature deeply enough to make excellent design calls — **no code, no
+markup**. Use the `devrites-interview` cadence: 2-3 questions per round, best-guess
+attached, stop when answers converge. One round is the default; add a second only for
+material gaps. When `PRODUCT.md` + the spec already pin an answer, **assert it and ask to
+confirm** ("reads as Restrained — confirm?"), don't offer a four-option menu. Cover:
+- **Purpose & user** — who, in what state of mind (rushed / exploring / anxious / focused).
+- **Content & data** — realistic ranges (0 / typical / many), dynamic content, real
+  media/assets the surface needs.
+- **Preserve + anti-goals** — identity, IA, behavior, content voice, SEO/analytics hooks,
+  existing accessibility wins, or assets that must survive; what this must NOT become;
+  the biggest risk of getting it wrong.
+
+## 3. Design direction — the direction set (commit, don't hedge)
+One deliberate visual decision on five fronts, each anchored in an existing reference so
+the call is checkable, not taste:
+- **Scene sentence** — who / where / ambient light / mood, per
+  `../devrites-frontend-craft/reference/design-references.md`. Forces dark-vs-light and
+  tone from the scene, not the category.
+- **Color strategy** — Restrained / Committed / Multi-role / Saturated, per the
+  color-commitment table in `../devrites-frontend-craft/reference/quality-standards.md`.
+  Pick from the scene; register doesn't decide it.
+- **Calibration** — density (Airy / Balanced / Dense) and motion (Minimal / Standard /
+  Expressive), per the calibration table in the same quality-standards file. Set both from
+  the scene so the build targets a calibration, not a guess (a 2am SRE → Dense + Minimal; a
+  launch hero → Airy + Expressive).
+- **Named anchor references** — 2-3 *specific* products / brands / objects to steer toward
+  (not adjectives like "modern" or "clean"), plus the saved `references/` files.
+- **Visual thesis** — the focal point and hierarchy in one sentence, plus one memorable
+  move (or `none — system continuity`) and the obvious-but-wrong direction rejected. This
+  creates intentional distinction without forcing novelty into product UI.
+
+Respect the existing identity (default, ~90%); depart only on an explicit signal.
+
+## 4. Scope — task-scoped, never persisted
+Name the output target so sketch-vs-ship isn't guessed: **fidelity** (sketch / mid-fi /
+high-fi / production — DevRites default is production), **breadth** (one screen / a flow /
+a surface), **interactivity**, **time intent**. These ride in the brief only; they do not
+change the project's design system, and never get written to `PRODUCT.md` / `DESIGN.md`.
+
+## 5. Key states + interaction model
+List every state the feature needs and what the user must see/feel in each (default,
+loading initial+subsequent, empty→next-action, error→recovery, success, disabled/
+no-permission, long-content/overflow), the information hierarchy (what's seen 1st / 2nd /
+3rd; primary action unmistakable), responsive reflow, a11y must-haves, and the interaction
+model (inline vs navigated vs — rarely — modal; optimistic vs pending; feedback). Name the
+representative states, viewports, input modes, and target R-ids that will prove the result;
+"looks polished" is not a proof target. Canonical state list:
+`../devrites-frontend-craft/reference/shape.md`.
+
+## 6. Visual-direction probe — capability-gated
+When the work is net-new or directionally ambiguous and fidelity ≥ mid-fi, pressure-test
+the lane with something concrete instead of words — pull Figma context, generate image
+probes, screenshot reference sites, or route a code-fidelity question to `/rite-prototype`.
+**Capability-gated**: announce the skip in one line if no tool is available. Flow:
+[reference/visual-direction-probe.md](reference/visual-direction-probe.md).
+
+## 7. AI-slop pre-check
+Run the two-altitude category-reflex check (`../rite-polish/reference/anti-ai-slop.md`) on
+the chosen direction *before* writing the brief — if the palette/theme is guessable from
+the category, rework the scene sentence and color strategy. Cheaper to catch the slop in
+the brief than in the build.
+
+## 8. Write the brief + gate
+Write `design-brief.md` ([reference/brief-template.md](reference/brief-template.md)) —
+**compact** (3-5 bullets) when discovery was crisp, **full** when the surface is ambiguous
+or multi-screen. Don't pad a clear brief to look thorough; don't skip the pause to look
+fast. Then honor the run mode (`../devrites-lib/reference/standards/afk-hitl.md`):
+- **HITL** — present the brief and **STOP for explicit confirmation**. The pause is the
+  point: shape ends at the user's "go", not at your own certainty. Disagreement → revisit
+  the relevant discovery question.
+- **AFK** — assert the best-guess direction, record it in `decisions.md` + an advisory
+  `questions.md` entry, and proceed. A direction touching the irreversible-risk list still
+  pauses.
+
+Completion: the smallest useful brief exists; primary action, states, interaction, proof
+targets, and reference role/usage are explicit; the run-mode gate is resolved. Only then may
+UI code start.
+
+## Output
+```
+UX/UI shaped: <slug>
+Direction: <color strategy> · density <airy|balanced|dense>/motion <minimal|standard|expressive> · "<scene sentence>" · anchors: <ref A, ref B>
+States: <n listed>   Probe: <figma | images | prototype | skipped — no tool>
+Brief: design-brief.md (<compact | full>)
+Gate: <confirmed | awaiting confirmation | AFK-asserted>
+Next: /rite-define (UI slices map to the brief's states) — or /rite-build refines it per slice
+```
+
+## NEVER (ux-shape)
+- Never write code, markup, or a component here — produce the thinking, not the UI.
+- Never finalize the brief without naming the **primary action** and the **full state set**
+  (not just the happy path).
+- Never decide visual direction by taste when the project has a system — discover first.
+- Never treat an **inspiration** reference as a fidelity target — honor its recorded role.
+- Never skip the HITL confirmation pause "because the brief is obviously right" — ask once,
+  wait.
+- Never re-derive the brief from scratch in `/rite-build` — refine the existing one.

package/pack/generated/claude/skills/devrites-ux-shape/reference/brief-template.md

@@ -0,0 +1,108 @@
+# `design-brief.md` template — the UX/UI contract
+
+The feature-level design decision, produced **before** code by `devrites-ux-shape` (at
+`/rite-spec` when UI is detected) and the **target** the build, polish, and seal check
+against. `devrites-frontend-craft` refines it per slice and appends build-time decisions;
+it is never re-derived from scratch.
+
+Pick the shape by how clear the answers are. **Compact** is the default for a crisp prompt;
+**full** when the surface is ambiguous, multi-screen, or the user asked to shape it as a
+step. Don't pad a clear brief into a long one to look thorough.
+
+## Compact form (default)
+```markdown
+# Design brief: <feature>
+Slug: <kebab>   Shaped: <iso>   Register: brand | product   Fidelity: <sketch|mid-fi|high-fi|production>
+
+- **Building**: <one line — what + who it's for + the primary action>
+- **Thesis**: <focal point + hierarchy> · memorable move: <one move | none — system continuity> · preserve/avoid: <identity + anti-goal>
+- **Direction**: <color strategy> · density <airy|balanced|dense>/motion <minimal|standard|expressive> · "<scene sentence>" · targets: <R-ids> · constraints: <R-ids> · inspiration: <R-ids>
+- **Locks**: accent <token> · radius <scale> · theme <light|dark>
+- **States**: <the states this surface needs, comma-listed>
+- **Interaction**: <inline / navigated / modal · feedback · entry→completion in a phrase>
+- **Proof**: <states × viewports × input modes; target R-ids; zero material visual mismatches>
+- **Confirm or override?** <the one or two things you still want the user to confirm>
+```
+
+## Full form
+```markdown
+# Design brief: <feature>
+Slug: <kebab>   Shaped: <iso>   Register: brand | product
+
+## 1. Summary
+What this is, who it's for, what it must accomplish, what existing identity/behavior must
+survive — including IA, content voice, SEO/analytics hooks, and accessibility wins — and
+the anti-goal (2-3 sentences).
+
+## 2. Primary action
+The single most important thing the user does or understands here. Everything else is secondary.
+
+## 3. Design direction
+- Color strategy: Restrained | Committed | Multi-role | Saturated — why (from the scene, not the category).
+- Calibration: density Airy | Balanced | Dense · motion Minimal | Standard | Expressive — from the scene (`../../devrites-frontend-craft/reference/quality-standards.md` — Calibration).
+- Scene sentence: "<who uses it, where, under what light, in what mood>".
+- Visual thesis: <focal point + 1st/2nd/3rd hierarchy> · memorable move: <one | none — system continuity>.
+- References by role: targets <R-ids> · constraints <R-ids> · inspiration <R-ids>.
+- Locks: one accent <token> · one radius scale · one theme — held page-wide
+  (`../../devrites-frontend-craft/reference/quality-standards.md` — Consistency locks).
+- Rejected direction: <the obvious-but-wrong direction + why>.
+- Departure: default (preserve identity) | departing because <explicit signal>.
+
+## 4. Scope  *(task-scoped — not persisted to PRODUCT.md / DESIGN.md)*
+Fidelity · breadth · interactivity · time intent.
+
+## 5. Layout & hierarchy
+What gets emphasis; what's seen 1st / 2nd / 3rd; how information flows. Hierarchy, not CSS.
+
+## 6. Key states
+Every state + what the user needs to see and feel:
+| State | User sees / feels | Notes |
+|---|---|---|
+| default / populated | | |
+| loading | | initial + subsequent |
+| empty | | welcoming + the next action |
+| error | | what happened + how to recover |
+| success | | |
+| disabled / no-permission | | |
+| long-content / overflow / many items | | |
+
+## 7. Interaction model
+Inline vs navigated vs (rarely) modal; optimistic vs pending; focus & keyboard; feedback on
+every action; the flow from entry to completion.
+
+## 8. Content & copy
+Labels, empty/error messages, microcopy in the product's voice. Realistic dynamic ranges.
+For image-led surfaces: required media roles + likely source (project asset / generated /
+SVG-CSS / icon library / accepted omission) and the shippable provenance/usage recorded in
+`references.md`.
+
+## 9. Responsive & a11y
+Reflow 320→1440 (what stacks / collapses / scrolls); focus order, labels, contrast,
+keyboard, target size. Floor: `../../devrites-frontend-craft/reference/quality-standards.md`.
+
+## 10. Visual-direction probe
+Which probe ran (figma / images / prototype / skipped — no tool), which direction won, what
+changed in the brief because of it. Artifacts saved under `references/`.
+
+## 11. Proof targets
+Representative states × viewports × input modes, the target R-ids or brief rules each
+render is compared with, and the exact interaction/accessibility checks. A visual pass
+requires zero unresolved **material** mismatch; accepted departures are recorded below.
+
+## 12. Open questions
+Genuinely unresolved only. If you'd write "Recommend: X", decide X instead.
+
+## Build-time refinements  *(appended by devrites-frontend-craft per slice)*
+- SLICE-001: <decision made while building this surface + why>.
+```
+
+## How downstream phases use it
+- `/rite-define` — UI slices map to the **Key states**, **Interaction model**, and **Proof
+  targets**; each UI slice names the visual acceptance it proves.
+- `/rite-build` + `devrites-frontend-craft` — build **to** the brief; refine per slice;
+  append refinements above instead of re-deriving.
+- `/rite-prove` + `browser-evidence.md` — render the proof targets, compare against the
+  brief + target references, and close material deltas.
+- `/rite-polish` — Phase 4 reads the brief so polish honors the agreed direction.
+- `/rite-seal` + `devrites-frontend-reviewer` — check the UI matches the brief (states
+  covered, direction held, references matched).

package/pack/generated/claude/skills/devrites-ux-shape/reference/visual-direction-probe.md

@@ -0,0 +1,48 @@
+# Visual-direction probe — test the lane before the brief locks
+
+Before finalizing `design-brief.md`, pressure-test the visual direction with something
+concrete instead of words — *when it will actually clarify the brief*. This is the
+DevRites-native answer to "build it according to the design (Figma, images)": show a
+direction, get a reaction, then write the brief.
+
+## When to run (all true)
+- The work is **net-new** or directionally **ambiguous**. An existing surface or an
+  approved reference classified **target** already fixes the direction → skip.
+- Fidelity is **mid-fi or higher**. Sketch-only planning → skip.
+- A probe tool is actually available (below). **Capability-gated** — never ask the user to
+  install APIs or tooling. If none is available, **announce the skip in one line** and
+  proceed to the brief. The one-line announcement is required; it forces a conscious choice
+  instead of letting the step quietly evaporate.
+
+## Pick the probe by what's available (first match)
+1. **Figma reference supplied** → pull design context with the Figma integration (frames,
+   tokens, components, a screenshot of the target). Record what it dictates. A Figma frame
+   that conflicts with the project's design system is a **question for the user**, not a
+   silent choice.
+2. **Native image generation available** (Figma Make, an image-gen MCP, computer-use, or
+   similar) → generate **2-4 distinct direction probes** from the discovery answers (color
+   strategy, scene sentence, anchors). They must differ in **primary direction** —
+   hierarchy, density, typographic voice, topology — not just palette tweaks. Treat them as
+   *direction tests*, not final UI.
+3. **A code-fidelity question** ("which of these layouts actually works in our stack") →
+   route to **`/rite-prototype`** (2-4 real UI variations on one throwaway route). Prototype
+   is DevRites' existing tool for this; don't rebuild it here.
+4. **Reference sites / links only** → screenshot them (`devrites-browser-proof` tooling)
+   and read the relevant intent (tone, density, interaction).
+5. **Nothing available** → one-line skip, proceed.
+
+## How to use the result
+- Ask which direction feels closest, what's off, what carries forward. Don't treat
+  generated imagery as final UX, copy, or accessibility behavior.
+- If the probe reveals a mismatch, revise the **discovery inputs** (scene sentence, color
+  strategy, anchors) *before* writing the brief — that's the whole point of probing.
+- Save probe artifacts (generated images, Figma exports, screenshots) into
+  `.devrites/work/<slug>/references/`, index them in `references.md` with what each shows,
+  and note the winning direction in the brief's **Visual-direction probe** section.
+
+## Limits
+- Don't skip discovery because image generation is available.
+- Don't run a probe for a minor refinement of existing work — it's for shaping a new
+  surface or a big directional choice.
+- Don't block the brief on a slow or failing tool — try once, then skip with the one-line
+  note.

package/pack/generated/claude/skills/rite/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: rite
+description: User-invoked DevRites menu and router; no args renders the menu, a verb dispatches to the matching `rite-<verb>` skill.
+argument-hint: "[verb [args...]]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# /rite — DevRites menu + router
+
+You are the DevRites entry point. Two modes:
+
+- **No args** → run `devrites-engine first-task`, render one recommended-start line above the menu, then stop. Do not execute a phase or read `state.md` — status is `/rite-status`.
+- **Verb arg** → pass-through dispatch to the matching `rite-<verb>` skill (`/rite spec foo` ≡ `/rite-spec foo`); the called skill owns the output.
+
+When the user asks which rite fits, load [`devrites-lib/reference/intent-map.md`](../devrites-lib/reference/intent-map.md).
+When they ask how phases connect, load [`reference/menu.md`](reference/menu.md).
+
+## Dispatch
+
+If `$ARGUMENTS` starts with a verb in this table, **load the matching skill and execute its workflow** with the remainder of `$ARGUMENTS` as that skill's argument. Try post-install path first, fall back to pre-install:
+
+```bash
+V=<verb>; ARGS="<remaining args>"
+F=.claude/skills/rite-$V/SKILL.md
+[ -f "$F" ] || F=pack/.claude/skills/rite-$V/SKILL.md
+# Then Read "$F" and follow its workflow with $ARGS as that skill's $ARGUMENTS.
+```
+
+What each verb does lives once, in the Menu below; this table is the dispatch map only.
+
+| Verb | Skill |
+|---|---|
+| `spec [feature]` | `/rite-spec` |
+| `adopt [area]` | `/rite-adopt` |
+| `temper [--mode]` | `/rite-temper` |
+| `define` | `/rite-define` |
+| `vet [--cross-model]` | `/rite-vet` |
+| `plan [mode]` | `/rite-plan` |
+| `build [slice]` | `/rite-build` |
+| `converge [slug]` | `/rite-converge` |
+| `prove` | `/rite-prove` |
+| `polish [mode]` | `/rite-polish` |
+| `review [scope]` | `/rite-review` |
+| `seal` | `/rite-seal` |
+| `ship` | `/rite-ship` |
+| `status [slug]` | `/rite-status` |
+| `doctor [--code | --reindex]` | `/rite-doctor` |
+| `learn [--mine \| "<lesson>"]` | `/rite-learn` |
+| `explain [concept \| diff \| idea \| recap]` | `/rite-explain` |
+| `pov [candidate]` | `/rite-pov` |
+| `dogfood [--port N]` | `/rite-dogfood` |
+| `pr-feedback [PR\|thread]` | `/rite-pr-feedback` |
+| `customize [override <agent> \| extension <name>]` | `/rite-customize` |
+| `use <slug>` | (inline) |
+| `guide` | (inline) |
+| `resolve <qid> "<answer>"` | `/rite-resolve` |
+| `prototype [question]` | `/rite-prototype` |
+| `handoff [focus]` | `/rite-handoff` |
+| `zoom-out` | `/rite-zoom-out` |
+| `pressure-test` | `/rite-pressure-test` |
+| `autocomplete [idea] [--ship]` | `/rite-autocomplete` |
+| `quick [change]` | `/rite-quick` |
+| `frame [task]` | `/rite-frame` |
+
+Both forms hit the same skill — the menu form for discovery, the `/rite-<verb>` shortcut for muscle memory.
+
+`use <slug>` is handled **inline** — there is no `rite-use` skill. Confirm
+`.devrites/work/<slug>/` exists, then re-point `.devrites/ACTIVE` to `<slug>` and report
+the now-active feature. It is cheap context-switching only — no re-spec, no phase run. If
+the workspace is missing, list the slugs under `.devrites/work/` and stop.
+
+`guide` is also inline — a first-feature walkthrough that teaches the lifecycle by running
+it. Agree on one **real, genuinely small** change, then dispatch the normal phases in order
+(spec → define → build → prove → seal → ship). Per phase, exactly two narration beats:
+before, what it will decide; after, what it wrote in `.devrites/work/<slug>/` and why. Walk
+every phase — the small change is what makes the full ceremony affordable to watch. Pause
+at each boundary for the user's go-ahead. Teach without lecturing.
+
+Specialist triggers (model-invoked inside the above):
+`devrites-frontend-craft` (UI) · `devrites-browser-proof` (UI verify) ·
+`devrites-source-driven` (uncertain library) · `devrites-doubt` (non-trivial
+decision) · `devrites-api-interface` (cross-boundary) ·
+`devrites-audit <security|perf|simplify>` (single-axis review/polish pass) ·
+`devrites-debug-recovery` (failures). Parallel reviewer fan-out at seal is a shared
+reference (see [`devrites-lib/reference/parallel-dispatch.md`](../devrites-lib/reference/parallel-dispatch.md)).
+
+## What to output
+
+Reply-contract exception: `/rite` is the menu/router, not a workspace completion step.
+Called phase skills own the shared completion reply contract
+([`reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+
+1. **Verb in `$ARGUMENTS`** → dispatch per the table above.
+2. **No args** → menu mode, as above.
+3. **Unrecognized first token** → tell the user the known verbs and stop. Don't guess.
+4. **No active feature** and the user asked "where am I" or named no verb → point at `/rite spec <feature>` (or `/rite-spec`). Don't summarize state yourself — `/rite status` (or `/rite-status`) owns that.
+
+## Menu
+
+```
+DevRites — disciplined senior-engineer workflow
+Recommended start: <greenfield: /rite spec <feature> | brownfield-unadopted: /rite adopt | active-feature: /rite status | dirty-worktree: /rite frame or /rite quick | branch-ahead: /rite ship/status | clean-default: /rite spec <feature>>
+                              menu form           direct shortcut
+SPEC          /rite spec               ≡    /rite-spec        investigate deeply → write spec.md
+ADOPT         /rite adopt              ≡    /rite-adopt       onboard existing code → reverse-derive spec.md + seed conventions
+TEMPER        /rite temper             ≡    /rite-temper      optional — strategic review: scope mode + pre-mortem, harden the spec
+PLAN          /rite define             ≡    /rite-define      turn the spec into plan + task slices + state
+VET           /rite vet                ≡    /rite-vet         optional — engineering plan review: scope · architecture · tests · perf, harden the plan
+REPLAN        /rite plan               ≡    /rite-plan        decompose / reslice / repair an active plan
+BUILD         /rite build              ≡    /rite-build       implement exactly one verified vertical slice, then stop
+PROVE         /rite prove              ≡    /rite-prove       tests + build + runtime + browser evidence
+POLISH        /rite polish             ≡    /rite-polish      code polish always; UI normalize + polish if UI
+REVIEW        /rite review             ≡    /rite-review      feature-scoped multi-axis review
+SEAL          /rite seal               ≡    /rite-seal        final GO / NO-GO decision (no git)
+SHIP          /rite ship               ≡    /rite-ship        type-GO + commit/push/tag, then archive + clear ACTIVE
+STATUS        /rite status             ≡    /rite-status      active feature, next action, evidence, risks
+DOCTOR        /rite doctor ...         ≡    /rite-doctor      health check; --reindex refreshes structural indexes
+LEARN         /rite learn ...          ≡    /rite-learn       review captured lessons → promote to project rules / principles
+EXPLAIN       /rite explain ...        ≡    /rite-explain     grounded concept/diff/idea/recap explainer
+POV           /rite pov ...            ≡    /rite-pov         decide adopt / trial / hold / reject for an external option
+DOGFOOD       /rite dogfood ...        ≡    /rite-dogfood     browser QA by changed user journey
+PR FEEDBACK   /rite pr-feedback ...    ≡    /rite-pr-feedback fix and resolve PR review threads
+CUSTOMIZE     /rite customize ...      ≡    /rite-customize   author overrides/extensions without forking the pack
+SWITCH        /rite use <slug>                                re-point .devrites/ACTIVE to another feature (inline)
+GUIDE         /rite guide                                     first feature, guided — full lifecycle on one small real change (inline)
+RESUME        /rite resolve ...        ≡    /rite-resolve     answer a HITL checkpoint
+AUTO          /rite autocomplete ...   ≡    /rite-autocomplete  run the whole lifecycle unattended (--ship to push)
+QUICK         /rite quick <change>     ≡    /rite-quick       express lane — one small reversible change (escalates if it grows)
+UTILITY       /rite frame | prototype | handoff | zoom-out | pressure-test  (or direct shortcuts)
+```
+
+> **Small one-off change?** A typo, copy tweak, config bump, or one-function fix → **`/rite-quick`**
+> (express lane: one contract → build → prove → ship, no full workspace). It escalates to
+> `/rite-spec` the instant the change grows past small / reversible / unambiguous. The full
+> lifecycle above is for real features — don't pay its ceremony for a one-off.
+
+## Core operating rules (every DevRites skill enforces)
+
+The operating rules live in `.claude/skills/devrites-lib/reference/standards/core.md`; DevRites skills Read it as
+their first step, and the other rule files load on demand. See
+[`.claude/skills/devrites-lib/reference/standards/README.md`](../devrites-lib/reference/standards/README.md) for the full index.

package/pack/generated/claude/skills/rite/reference/menu.md

@@ -0,0 +1,42 @@
+# Menu reference
+
+Phase-ordered command reference for `/rite`. Load only if the user wants detail on
+what each command does or how phases connect.
+
+## Phases and commands
+
+| Phase | Command | Use when |
+|---|---|---|
+| Spec | `/rite-spec <feature>` | **Start here.** Investigate deeply → write spec.md. Asks you with options; gathers any design references you attach (optional). |
+| Adopt | `/rite-adopt` | Onboard an existing codebase instead of starting fresh — reverse-derive spec.md + seed the conventions ledger. |
+| Temper | `/rite-temper` | _Optional, before define._ Strategic review of the spec — scope mode (expand/selective/hold-rigor/reduce) + pre-mortem; hardens the spec. Best on big/risky features; mandatory in `/rite-autocomplete`. |
+| Plan | `/rite-define` | Turn the approved spec into plan + vertical task slices + state. |
+| Vet | `/rite-vet` | _Optional, before build._ Engineering review of the plan — scope · architecture · tests · perf; hardens the plan. Best on big/risky features; mandatory in `/rite-autocomplete`. |
+| Re-plan | `/rite-plan` | The active plan is too big, wrong, stale, ambiguous, or blocked. |
+| Build | `/rite-build` | Implement the next single vertical slice. Stops after one slice. |
+| Converge | `/rite-converge` | _Recovery._ Code drifted from / falls short of intent (resumed cold, adopted, stalled build) — assess live code vs spec/plan/tasks and append the remaining work as new slices for `/rite-build`. |
+| Prove | `/rite-prove` | Prove the current scope: tests, build, runtime, browser evidence. |
+| Polish | `/rite-polish` | Code polish always; UI normalize + ship-quality polish if UI is in scope. Modes: `bolder/quieter/distill/harden/normalize-only`. |
+| Review | `/rite-review` | Feature-scoped review before sealing. |
+| Seal | `/rite-seal` | Final GO / NO-GO decision (no git). |
+| Ship | `/rite-ship` | Type-GO → commit/push/tag, then archive the task + clear ACTIVE. |
+| Status | `/rite-status` | See where the active feature stands. |
+| Doctor | `/rite-doctor` | Health check — install integrity, stale ACTIVE, orphaned gates, hook wiring, merge/rebase state. |
+| Learn | `/rite-learn` | Review the captured learning ledger → promote recurring lessons to project rules / principles. |
+
+## Typical orderings
+
+- **Every feature**: `/rite-spec` (spec) → *(big feature? `/rite-temper` — strategic review)* →
+  `/rite-define` (plan) → *(big feature? `/rite-vet` — engineering review)* →
+  `/rite-build` ×N (all slices) → `/rite-prove` (once all built) →
+  `/rite-polish` (always: code + UI if UI) → `/rite-review` → `/rite-seal` → `/rite-ship`.
+- **Existing codebase**: `/rite-adopt` (onboard → spec.md + conventions) → continue at `/rite-define`.
+- **Drift mid-build**: stop → drift question → `/rite-plan` (repair) → resume build.
+- **Resumed / adopted / stalled**: `/rite-converge` (assess live code vs intent → append the
+  remaining slices) → `/rite-build` ×N → continue at `/rite-prove`.
+
+## Rules this menu obeys
+
+- `/rite` never edits code or runs a phase workflow.
+- It reads `.devrites/ACTIVE` and `state.md` for status only.
+- It suggests; the user (or Claude, when appropriate) invokes the real skill.

package/pack/generated/claude/skills/rite-adopt/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: rite-adopt
+description: Adopt an existing or legacy codebase into DevRites by reverse-engineering current behavior, seeding conventions, and establishing the workflow. Use for inherited or live applications.
+argument-hint: "[path or area to adopt] [+ what you want to build next]"
+user-invocable: true
+---
+
+# /rite-adopt — brownfield on-ramp
+
+The **reverse** of `/rite-spec`. `/rite-spec` goes idea → spec; `/rite-adopt` goes
+**existing code → spec + seeded conventions**, so an already-built project can enter the
+DevRites lifecycle without hand-writing a spec from nothing. It produces the same
+`spec.md` the rest of the lifecycle expects, plus a head start in the conventions ledger
+so the very first new slice already knows the project's idioms.
+
+Use it once, at the start, to onboard a repo (or a sub-area of one). After it, the normal
+lifecycle (`/rite-temper` → `/rite-define` → `/rite-build` …) takes over.
+
+> **Just want a map, not an onboarding?** `/rite-zoom-out` returns a structural map of
+> unfamiliar code without creating a workspace or ledger. `/rite-adopt` is the heavier move:
+> it *commits the project to the lifecycle*. Pick zoom-out to look, adopt to begin.
+
+## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+Pull `documentation.md` when recording the adoption decisions (why-not-what) in
+`decisions.md`; pull `principles.md` when the code
+upholds invariants worth proposing as project principles (step 4a).
+
+## Operating rules (DevRites core)
+- No silent assumptions · prefer the project's existing conventions (you are *documenting*
+  them, not imposing new ones) · ask the human when the adoption scope or the next-build
+  objective is unclear.
+
+## Workflow
+0. **Read `.claude/skills/devrites-lib/reference/standards/core.md`**, then run
+   `devrites-engine preamble` for deterministic workspace orientation.
+1. **Scope the adoption** (`$ARGUMENTS`). Which repo or sub-area is being onboarded, and —
+   if stated — what the user wants to build *next* on top of it. If the next-build objective
+   is missing, ask once (it shapes the spec's acceptance); if the area is ambiguous, confirm
+   before investigating the whole tree.
+2. **Reverse-investigate the existing code** — the durable shape of the project. Use a
+   code-intelligence index if available — codebase-memory-mcp first (its `get_architecture`
+   gives a fast overview), cross-checked with codegraph + graphify, else standard methods
+   (LSP / Read/Grep/Glob); see `.claude/skills/devrites-lib/reference/standards/tooling.md` — for
+   structure, callers, and impact. Capture, per [adoption](reference/adoption.md): **current
+   behavior**, **architecture + placement** (layers, seams, where each kind of thing lives),
+   the **commands** (test / build / typecheck / lint), and the **idioms** (naming, layering,
+   error model, test style) + recurring **gotchas**. Read `PRODUCT.md` / `DESIGN.md` /
+   `CLAUDE.md` / `AGENTS.md` if present.
+3. **Write `spec.md`** via [rite-spec's spec template](../rite-spec/reference/spec-template.md)
+   and create the workspace + set `.devrites/ACTIVE`
+   ([state-workspace](../rite-spec/reference/state-workspace.md)). The spec records the
+   **current behavior as the baseline** and the **next objective** (what adoption is for) with
+   measurable acceptance. Also write `decisions.md`, `assumptions.md`, `questions.md`, and
+   `state.md` (phase: spec).
+3a. **Seed the capability ledger** from the baseline. If the reverse-derived `spec.md` carries
+   structured `### Requirement:` blocks, fold them into the living
+   `.devrites/specs/<capability>/spec.md` ledger so the project's *current* proven behavior is on
+   record before the first new feature — the ledger the next `/rite-spec` writes deltas against
+   ([ledger.md](../rite-ship/reference/ledger.md)). A flat baseline folds as all-ADDED into the
+   feature slug's capability; tag capabilities in the spec first if you want finer granularity.
+   ```bash
+   devrites-engine ledger diff .devrites/work/<slug>   # preview
+   devrites-engine ledger sync .devrites/work/<slug>   # seed
+   ```
+   Skip when the baseline records no structured requirements (nothing to seed).
+4. **Seed the conventions ledger** from what the investigation *observed* —
+   [adoption § seeding](reference/adoption.md). This is the deliberate bootstrap exception to
+   evidence-gated promotion: the seeds start at the base band and are provenance-tagged as
+   onboarding observations, not sealed-slice proofs, so real slices later corroborate or
+   (fresh-wins) contradict them.
+   **Completion:** every seed names observed evidence, provenance, and the base band.
+4a. **Propose candidate principles** (human-ratified; optional). Where the investigation found an
+   invariant the code *consistently and deliberately* upholds — money always in integer cents, PII
+   always redacted from logs, every v1 endpoint preserved — surface it as a **candidate
+   principle**, not a seeded convention. Principles are prescriptive and gating, so they are
+   **ratified by the human, never auto-seeded** the way conventions are: present the candidates via
+   `AskUserQuestion` with the evidence (where the code upholds it), and write the ones the human
+   ratifies to `.devrites/principles.md` with a dated Governance entry
+   ([`principles.md`](../devrites-lib/reference/standards/principles.md)). Propose, don't impose — an unratified candidate
+   stays a convention, not a gate. Skip cleanly when nothing rises to an invariant (common — a
+   fresh adopt may declare zero principles, and that's valid).
+5. **Hand off.** The project is now in the lifecycle with a spec and a head-start ledger.
+   Point the user at `/rite-temper` (big/risky) or `/rite-define` (straightforward) — do not
+   plan or build here.
+   **Completion:** one next rite is reported and no plan or application code was written.
+
+> **Mid-flight discipline.** Don't invent conventions the code doesn't actually follow, don't
+> seed an idiom you only assumed, and don't expand scope into a rewrite — adoption documents
+> what exists; the *next* feature changes it. See [`anti-patterns`](reference/anti-patterns.md).
+
+## Output
+
+**Progress first** — run `devrites-engine progress`, then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: adopted existing behavior into <slug>; baseline spec and placement recorded.
+Changed: spec.md, decisions.md, conventions ledger, principles proposals <updated|none>
+Evidence: not applicable; reverse-derived behavior is recorded for review
+Open: <none | adoption questions | Alternative: /rite-define for straightforward follow-up>
+Next: /rite-temper
+Record: .devrites/work/<slug>/spec.md
+↻ Hygiene: /clear before the next phase
+```

package/pack/generated/claude/skills/rite-adopt/reference/adoption.md

@@ -0,0 +1,55 @@
+# Adoption — reverse-investigate + seed (the on-ramp contract)
+
+Loaded on demand by `/rite-adopt`. Two jobs: document what the code already does (so the
+lifecycle has a spec), and seed the conventions ledger (so the first slice knows the idioms).
+
+## Reverse-investigation — what to capture
+
+Document the **durable shape** of the project, not a line-by-line tour:
+
+- **Current behavior** — what the adopted area does today, from the user's perspective.
+- **Architecture + placement** — the layers and seams; where each kind of thing lives
+  (where endpoints / components / models / migrations / tests go). Prefer a code-intelligence
+  index if available (see `../../devrites-lib/reference/standards/tooling.md`) for
+  structure, callers, and impact.
+- **Commands** — the real test / build / typecheck / lint commands (run or read them; don't
+  guess). Verify uncertain framework facts at the source.
+- **Idioms** — naming + casing, layering, the error model, the result/exception style, the
+  http/data-access pattern, the test framework + file layout.
+- **Gotchas** — non-obvious constraints the code encodes (ordering requirements, "don't call
+  X before Y", a framework quirk).
+
+This feeds `spec.md` (current behavior as the baseline + the next objective) and the ledger
+seeds below.
+
+## Seeding the conventions ledger
+
+The deliberate **bootstrap exception** to evidence-gated promotion. Normally a convention is
+promoted only when a *sealed slice proved it* (`/rite-seal`); adoption seeds from **observed
+existing code** so the first slice isn't blind. Keep the seeds honest:
+
+- Seed only what the code **actually and consistently** follows — not an aspiration, not a
+  one-off, not something you assumed.
+- Each seed starts at the base band (one corroboration) and is provenance-tagged as an
+  onboarding observation, **not** a sealed-slice proof. Real slices later corroborate it
+  (raising the band) or, per fresh-observation-wins, contradict it.
+
+```bash
+SLUG="$(cat .devrites/ACTIVE 2>/dev/null | tr -d '[:space:]')"
+if command -v devrites-engine >/dev/null 2>&1; then
+  devrites-engine conventions promote --slug "${SLUG}-adopt" \
+    --key test-runner --kind test \
+    --statement "tests run with <runner>, <file layout>" \
+    --evidence "observed during /rite-adopt onboarding (not yet slice-proven)"
+  # …one promote per durable convention the investigation actually observed
+  # (test-runner, build-cmd, error-model, http-client, endpoint-placement, …).
+else
+  echo "(conventions ledger unavailable — devrites-engine missing; skipping seed)"
+fi
+```
+
+The `-adopt` suffix on the slug marks the provenance as onboarding. Because the ledger is
+read at orient as a *prior* and the live code always overrides it
+([`.claude/skills/devrites-lib/reference/standards/security.md`](../../devrites-lib/reference/standards/security.md) § Prompt-injection resistance),
+an over-eager seed is self-correcting — but seed conservatively anyway; a wrong seed costs a
+needless contradiction later.