devrites 2.6.1 → 3.0.0

package/pack/generated/codex/skills/rite-prototype/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: rite-prototype
+description: User-invoked throwaway prototype for one logic or UI design question; delete or absorb after the answer.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[the question the prototype is answering]"
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $rite-prototype — throwaway code that answers ONE question
+
+A prototype is **throwaway code that answers exactly one question**. The question
+chooses the shape — get the shape wrong and the whole prototype wastes the user's time.
+
+## 0. Read core rules
+
+Read `.agents/skills/devrites-lib/reference/standards/core.md` first — the operating rules and the "capture the answer"
+persistence discipline apply even to throwaway code. The other rule files load on demand.
+
+## 1. Name the question
+
+If the user did not give the question explicitly, ask **one** short question to pin it
+down. Examples that count as "the question":
+
+- "Does this reducer correctly model add / undo / re-add of the same item?"
+- "Which of these three settings layouts feels right?"
+- "Will the proposed state machine deadlock when X overlaps Y?"
+
+A vague question ("explore this feature") is not enough — push back once to sharpen it.
+
+## 2. Pick the branch
+
+Read the user's prompt + the surrounding code. Two branches:
+
+| Question shape | Branch | Artifact |
+|---|---|---|
+| "Does this **logic / state / data model** behave right?" | **Logic** | Smallest runnable harness — terminal script / REPL / mini node or python file — that pushes the model through the hard cases. |
+| "What should this **look like / which UX wins**?" | **UI** | 2–4 **radically different** UI variations on a single route, switchable via a query param + a small floating selector bar. |
+
+If genuinely ambiguous and the user is AFK: pick by the surrounding code (backend module
+→ Logic; page / component → UI) and state the assumption in a comment at the top.
+
+**Variations must differ in shape.** UI prototypes where the variations are just colour
+or padding tweaks teach nothing — push each variation to a different *information
+architecture* / *interaction model* so the user can pick a direction, not a polish.
+
+## 3. Rules that apply to both branches
+
+1. **Throwaway from day one — and visibly so.** Place the prototype next to where it
+   will eventually be used (so context is obvious) but name it so a casual reader sees
+   it's a prototype: `prototype/`, `__prototype__`, `.scratch/`, etc. Obey the project's
+   existing routing / module convention; don't invent a new top-level structure.
+2. **One command to run.** Use whatever task runner the project already has — `pnpm
+   <name>`, `python <path>`, `bun <path>`. The user must start it without thinking.
+3. **No persistence by default.** State lives in memory. Persistence is usually the
+   thing the prototype is *checking*, not a dependency. If the question explicitly
+   involves a DB, hit a scratch DB or a local file with a name like
+   `PROTOTYPE — wipe me`.
+4. **Skip the polish.** No tests. No error handling beyond what makes it run. No
+   abstractions. The point is learn fast, delete fast.
+5. **Surface state.** After every action (Logic) or on every variant switch (UI), print
+   or render the full relevant state so the user can see what changed.
+6. **Delete or absorb when done.** When the question has an answer, either delete the
+   prototype or fold the validated decision into the real code — don't leave it
+   rotting in the repo.
+
+## 4. Capture the answer
+
+The *answer* is the only durable output. Before declaring the prototype done, write
+one of:
+
+- An entry in the active feature's `decisions.md` (`.devrites/work/<slug>/decisions.md`)
+  with the question and the answer.
+- A `NOTES.md` next to the prototype if no active feature exists.
+
+If the user is around, this is a quick conversation. If they're AFK, the prototype is
+complete only once the verdict is actually filled in — a blank `VERDICT: ___` is not an
+answer. Leave it marked **not yet complete** and queue the open question so a later pass
+fills the verdict before the prototype is deleted.
+
+## Where this slots in
+
+`$rite-prototype` is a **scoped detour**, not a phase of its own. Typical placements:
+
+- **Between `$rite-spec` and `$rite-define`** — a design question is undecidable on
+  paper; prototype it, capture the answer, return to `$rite-define`.
+- **Mid-build** — `$rite-build` hit a state-model ambiguity that the spec doesn't
+  resolve. Drop into a Logic prototype, capture the answer, return.
+
+After the prototype answers the question and the answer is recorded, return to the
+calling phase. The prototype itself does **not** ship.
+
+## Output
+
+Reply-contract exception: scoped prototype detour. Run `devrites-engine progress` only when
+an active workspace exists; otherwise skip it. Use the compact labels from the shared
+completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+
+```
+Done: prototype answered <question>.
+Changed: <prototype path | deleted after absorption>; decisions.md or NOTES.md
+Evidence: run command <cmd -> result>; verdict <one line>
+Open: <none | non-blocking delete/absorb follow-up>
+Next: <single command returning to the calling phase>
+Record: <.devrites/work/<slug>/decisions.md | NOTES.md path>
+↻ Hygiene: /clear after the answer is recorded; delete or absorb throwaway code before shipping
+```
+
+If the verdict is missing, use the shared `Awaiting human` form. The prototype is
+not `Done`, and `Resume:` points to the queued verdict question.

package/pack/generated/codex/skills/rite-prototype/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pack/generated/codex/skills/rite-prove/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: rite-prove
+description: Prove a completed feature with tests and the full test suite, build/typecheck/lint, end-to-end/browser evidence, screenshots, commands, and outputs for seal. Not for single-slice proof.
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $rite-prove — prove the completed feature
+
+Turn "I think it works" into recorded evidence for the **whole feature**. Read the active
+workspace first; if none, run `$rite-spec <feature>`.
+
+> **Differs from built-in `/verify` and `/run`:** those prove a single change /
+> launch the app. `$rite-prove` is feature-scoped — it walks `spec.md` acceptance
+> criteria one-by-one, runs the full relevant test suite + build/typecheck/lint,
+> ascends the browser-proof ladder (step 4),
+> and writes `evidence.md` + `browser-evidence.md` keyed to the active
+> `.devrites/work/<slug>/`. No DevRites workspace → use `/verify` or `/run` alone.
+
+## Gate: all slices must be built first
+Read `tasks.md` + `state.md`. **If ANY slice is still pending/unbuilt, STOP** and tell the
+user to finish it with `$rite-build` — `$rite-prove` runs once, when the full task is
+complete, not after each slice. (Each slice already got its own targeted tests during
+`$rite-build`; this phase is the comprehensive proof of the assembled feature.)
+
+**Never report a pass you didn't observe.** If a command couldn't run, say so and give exact manual steps.
+
+**Re-runnable, scoped.** `$rite-prove` runs once when the full feature is assembled, but
+it can be **re-run scoped** afterwards: when `$rite-polish` or `$rite-review` edit code,
+the existing `evidence.md` no longer post-dates the change, so re-run `$rite-prove` over
+the affected criteria/routes to refresh proof before `$rite-seal`.
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+Pull these via `Read` when relevant:
+- `testing.md` — pyramid, determinism, no-flake discipline.
+- `test-proof-checklist.md` — compact proof-quality gate for tests and recorded evidence.
+- `browser-proof-checklist.md` — for UI scope, the required browser states and Visual Verdict evidence.
+- `spec-grammar.md` — when the spec uses structured `### Requirement:` / `#### Scenario:`
+  blocks, each scenario (WHEN/THEN) is one observable behavior to walk and prove.
+- `performance.md` — measure first when perf is in scope.
+- `observability.md` — when the change has a runtime surface (endpoint, job, integration,
+  user flow): telemetry must be present **and observed to emit**, not assumed.
+- `developer-experience.md` — when the change ships a developer-facing surface (API / CLI / SDK /
+  webhook / config / error messages / getting-started): **measure** the DX scorecard (run the flow,
+  time time-to-hello-world, capture the verbatim error text), don't assert it.
+- `definition-of-done.md` — standing Done bar: acceptance mapped, fresh proof, no open hard gates, scoped edits, rollback/docs where needed.
+
+
+## Operating rules
+- Evidence over confidence. Feature scope only — fix within the feature or record a
+  blocker; don't refactor unrelated code.
+- Spec Drift Guard applies: if tests/evidence reveal the spec is wrong, stop and handle
+  drift (`rite-build/reference/spec-drift-guard.md`).
+
+## Workflow
+0. Read `.agents/skills/devrites-lib/reference/standards/core.md` first (the always-on operating rules); pull the
+   on-demand rules above when relevant.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
+1. **Confirm the gate** (all slices built). Read `spec.md` (acceptance criteria +
+   "Commands discovered"), `tasks.md`, `state.md`, `test-plan.md` if present (the vetted
+   coverage target from `$rite-vet`), and the full `git diff`.
+2. **Discover commands** if not recorded —
+   [test-command-discovery](reference/test-command-discovery.md): README, package
+   scripts, Makefile, CI configs, Gemfile/Rakefile, pyproject, go.mod, Cargo.toml.
+   **Completion:** exact runnable test/build/typecheck/lint commands are recorded or explicitly unavailable.
+3. **Run the full relevant test suite** for the feature (not a single slice), then the
+   relevant **build / typecheck / lint**.
+4. **UI feature?** Read `design-brief.md` + `references.md`, then run the browser proof ladder over the feature's routes —
+   [proof-ladder](reference/proof-ladder.md) + [browser-proof](reference/browser-proof.md)
+   (`devrites-browser-proof`): routes, viewports, screenshots (opened + described),
+   console, network, interaction paths, and the brief's proof targets. Compare screenshots
+   with target references, record deltas, fix/re-render, and do not pass with an unresolved
+   material mismatch.
+5. **Map proof completely.** Follow
+   [`reference/acceptance-proof.md`](reference/acceptance-proof.md) for acceptance/scenario
+   coverage and the conditional critical-path, observability, developer-surface, and wiring
+   branches. Completion: every criterion, planned interaction, and declared key link has a
+   proof class plus passing evidence, or is recorded as a blocker.
+6. **On failure** → [failure-triage](reference/failure-triage.md) +
+   `devrites-debug-recovery`. Reproduce → isolate → fix within scope → re-run; if a fix
+   would exceed scope, record a blocker.
+7. Update `evidence.md`, `browser-evidence.md` (if UI), `traceability.md`, and
+   `state.md`. New proof goes to `evidence.md` (`proof.md` is a read-only alias —
+   see `devrites-lib/reference/workspace-artifact-schema.md`).
+
+> **Mid-flight discipline.** When tempted to claim an un-observed pass, skip a rung of the browser-proof ladder, or proceed with slices pending — see [`anti-patterns`](reference/anti-patterns.md). Load it the moment you reach for the excuse.
+
+## 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: feature proof complete for <slug>.
+Changed: evidence.md, browser-evidence.md <updated|n/a>, devex.md <updated|n/a>, state.md
+Evidence: acceptance <total>/<total> (judgment-only <n>); scenarios <total>/<total|n/a>; key links <n>/<n|none>; tests/build/lint/browser <pass summary>
+Open: none
+Next: $rite-polish
+Record: .devrites/work/<slug>/evidence.md
+↻ Hygiene: /clear before $rite-polish
+```
+If any check fails, a blocker remains, or a criterion is unproven, use the shared
+`Stopped / blocked` form and route `Fix:` to the failing check or `$rite-build`; do
+not recommend `$rite-polish`.

package/pack/generated/codex/skills/rite-prove/reference/acceptance-proof.md

@@ -0,0 +1,48 @@
+# Acceptance proof
+
+Map every `spec.md` acceptance criterion to evidence and label its proof class:
+`test`, `command`, `browser`, or `judgment` with a one-line reason. Re-run the
+structured grammar gate before mapping scenarios:
+
+```bash
+devrites-engine spec-validate ".devrites/work/<slug>" --against .devrites/specs
+```
+
+Each structured WHEN/THEN scenario needs a passing asserting test. If `test-plan.md`
+exists, every acceptance mapping, per-gap requirement, interactive element, and user
+flow needs a passing result. Missing coverage is an unproven blocker.
+
+## Critical-path assertion strength
+
+For regression-Critical, irreversible, and data-loss paths, fault-inject a small
+behavior break and confirm the covering test goes red, then revert. Use the existing
+mutation tool when present. Run:
+
+```bash
+devrites-engine test-integrity
+devrites-engine mutation-gate
+devrites-engine package-existence
+```
+
+A test that stays green on broken code is unproven. Pure transforms also get a
+round-trip or metamorphic property check when applicable.
+
+## Runtime observability branch
+
+For endpoints, jobs, consumers, integrations, user-facing flows, or new error paths,
+apply the on-call test from `observability.md`: trigger the failure path and observe the
+required log, metric, or trace emit. Record the observation. Skip pure internal, docs,
+config, and type-only changes.
+
+## Developer-facing branch
+
+For a public API, CLI, SDK, webhook, config contract, error path, or getting-started
+flow, execute the real entry point on clean state. Measure time-to-hello-world and
+capture verbatim failure output. Browser-capture docs/quickstarts when applicable.
+Write the measured scorecard to `devex.md` and headline evidence to `evidence.md`.
+
+## Wiring branch
+
+Walk every key link declared by `plan.md` and exercise or follow it in the assembled
+feature. Record each as `EVID-###`; if none are declared, record that fact. An unwired
+link is a blocker.

package/pack/generated/codex/skills/rite-prove/reference/anti-patterns.md

@@ -0,0 +1,25 @@
+# rite-prove — anti-patterns
+
+Load this when standing a non-trivial proof decision, or when tempted to
+report a pass you didn't observe, skip a rung of the browser-proof ladder,
+or proceed without all slices built.
+
+Pack-wide rationalizations + red flags (incl. observed-but-not-recorded):
+see [standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Tests passed during build; that's enough." | Build = per-slice sanity check. Prove = whole-feature suite + build/typecheck/lint + browser. |
+| "Browser proof is overkill for this UI change." | If it's UI and a browser can run, the ladder applies. If you can't, document which rung and why. |
+| "Failure is in pre-existing code, not in this feature." | Still surfaces as a blocker. Feature scope = fix in scope or record + halt. |
+| "Some slices are still pending but the rest can be proved." | No — `$rite-prove` runs once, when every slice is built. Otherwise you're proving a partial system. |
+
+## Red Flags
+
+- Reporting "pass" for a command you didn't actually run.
+- Skipping browser-proof rungs 1–3 because rung 4 (project E2E) was easier.
+- An acceptance criterion left "unproven" without a corresponding blocker note.
+- Tests recorded green but the diff shows the test file wasn't touched (stale run).
+- About to write `evidence.md` without command + output.

package/pack/generated/codex/skills/rite-prove/reference/browser-proof.md

@@ -0,0 +1,49 @@
+# Browser proof — evidence schema
+
+What `browser-evidence.md` must capture for a UI slice. Delegates to
+`devrites-browser-proof`; this is the record contract.
+
+```markdown
+# Browser Evidence
+
+## Browser evidence
+| Evidence ID | Route | State/input | Viewport | Compared with | Tooling | Result | Related IDs | Limitation |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| EVID-003 | <route> | empty/keyboard | 375 | brief Proof targets + R1 | playwright-mcp | <observed result> | AC-002, SLICE-002 | <none / exact gap> |
+
+## Visual Verdict
+| State | Result | Notes |
+| --- | --- | --- |
+| default | PASS / FAIL | <what is visible> |
+| loading | PASS / FAIL | <what is visible> |
+| error | PASS / FAIL | <what is visible> |
+
+## Comparison deltas
+| State / viewport | Target | Material delta observed | Disposition | Result |
+| --- | --- | --- | --- | --- |
+| empty / 375 | design-brief.md + R1 | <hierarchy/layout/spacing/type/behavior difference> | fixed + re-rendered / accepted with reason | PASS / FAIL |
+
+## Run notes
+- Screenshots: <path(s)> — opened and described above.
+- Console: <errors/warnings, or "clean">.
+- Network: <failures, or "no failures">.
+- Interaction path: <clicks/inputs performed and result>.
+- Accessibility: <focus order / labels / contrast spot-check>.
+- Responsive: <what changed across viewports; any breakage>.
+```
+
+## Rules
+- Open every screenshot path and describe it — never assert from the filename.
+- Read `design-brief.md` + `references.md` first. Compare fidelity only with references
+  classified **target**; check constraints as rules and never pixel-match inspiration.
+- Render every proof target named by the brief/slice. At minimum check a small (375) and a
+  large (1280) viewport for layout slices.
+- Compare structure before decoration: hierarchy/layout → responsive/state behavior →
+  type/spacing/color → polish. Record each material delta, fix it, and re-render. A visual
+  PASS requires zero unresolved material deltas; an accepted departure needs its reason in
+  the design brief's build-time refinements.
+- A clean console + no layout shift are part of the evidence, not extras.
+- If no browser can run, write the manual verification steps a human would follow and
+  mark the slice's browser proof as **pending (manual)**.
+- Every browser evidence row uses `EVID-###` and names the related `AC-###` and
+  `SLICE-###`; `$rite-prove` mirrors the evidence ID in `traceability.md`.

package/pack/generated/codex/skills/rite-prove/reference/failure-triage.md

@@ -0,0 +1,25 @@
+# Failure triage
+
+When a test/build/runtime/browser check fails, triage before fixing. Delegates the deep
+loop to `devrites-debug-recovery`.
+
+## Triage ladder
+1. **Reproduce** — run the failing command again; capture the exact error (quote it).
+2. **Classify** the failure:
+   - test is right, code is wrong → fix the code (in scope).
+   - test is wrong/outdated → that may be **spec drift** (acceptance criteria wrong).
+   - environment/setup (missing dep, wrong node/ruby) → fix setup or record blocker.
+   - flaky (passes on re-run, timing/order) → note it; don't paper over with retries.
+   - external dependency down → record blocker; don't fake the result.
+3. **Isolate** — minimize to the smallest failing case; bisect the diff if needed.
+4. **Fix within scope** — the current slice/feature only. If the fix reaches outside
+   scope, stop and record a blocker in `state.md` (then `$rite-plan unblock`).
+5. **Re-run** the same command; confirm green; record both attempts in `evidence.md`.
+
+## Rules
+- Quote the real error text; don't paraphrase it away.
+- Don't loosen/delete a failing assertion to get green — investigate whether it's drift.
+- Don't add blanket retries/sleeps to hide flakiness.
+- Three failed fix attempts on the same root cause → escalate: `devrites-debug-recovery`
+  for a hypothesis-driven pass, or ask the user.
+- A failure you can't fix in scope is a recorded **blocker**, not a silent skip.

package/pack/generated/codex/skills/rite-prove/reference/proof-ladder.md

@@ -0,0 +1,28 @@
+# Proof ladder
+
+Prefer real runtime evidence. For UI/browser work, try tools top-down and record which
+rung you used. Detect, don't install — browser tooling setup is the user's call.
+
+1. **Playwright MCP** (preferred when configured)
+   - Detect: the Playwright MCP `browser_*` tools are available (e.g. `browser_navigate`).
+     Capabilities: navigation, accessibility-tree snapshots, screenshots, ref-based
+     clicks/typing, console messages, network requests, `browser_evaluate`. Drives a
+     Playwright-managed browser; detect, don't install.
+2. **Chrome DevTools MCP** (when configured — pairs with Playwright MCP for Lighthouse, the
+   perf trace, and deeper DOM) — screenshots, DOM, console, network, performance,
+   accessibility tree.
+3. **Claude Code `/run` and `/verify`** (if available) — launch and observe the app;
+   prefer a project-specific run/verify skill if one exists.
+4. **Project-native E2E** (only if already present) — Playwright, Cypress, Capybara,
+   Selenium. Use the project's existing commands; don't add a new framework.
+5. **Manual fallback** — no tooling available: record the limitation and write exact
+   manual steps (route, action, expected result).
+
+## Non-UI scope
+The "ladder" for backend/CLI/data scope is just: targeted tests → build/typecheck/lint
+→ runtime observation (a real request/response or CLI run). Same evidence rules apply.
+
+## Stop conditions
+- Auth wall reached → stop, ask the user; never type credentials from a screenshot.
+- Destructive action required to prove → confirm with the user first.
+- A screenshot tool returns a path → **open and describe it**; a path is not proof.

package/pack/generated/codex/skills/rite-prove/reference/test-command-discovery.md

@@ -0,0 +1,30 @@
+# Test / build command discovery
+
+Use the project's own commands. Never invent a test runner or build step. Discover from
+these sources, in roughly this order of authority:
+
+| Source | Look for |
+|---|---|
+| `spec.md` → "Commands discovered" | already-found commands (trust first) |
+| `package.json` `scripts` | `test`, `build`, `typecheck`, `lint`, `dev`, `e2e` |
+| `Makefile` / `Justfile` / `Taskfile` | `test`, `build`, `check`, `lint` targets |
+| `Gemfile` / `Rakefile` | `rake test`, `rspec`, `bin/rails test` |
+| `pyproject.toml` / `tox.ini` / `noxfile.py` | `pytest`, `tox`, `nox` |
+| `go.mod` | `go test ./...`, `go build ./...`, `go vet` |
+| `Cargo.toml` | `cargo test`, `cargo build`, `cargo clippy` |
+| CI configs (`.github/workflows`, `.gitlab-ci.yml`, `circleci`) | the exact commands CI runs — the source of truth for "green" |
+| README / CONTRIBUTING | documented dev/test workflow |
+| framework conventions | Rails/Django/Next/etc. defaults when nothing else is set |
+
+## Targeted first
+Run the **narrowest** command that exercises the slice (a single test file/path),
+then widen. A full suite is slower and noisier; use it for the final check, not the
+inner loop.
+
+## Record what you found
+Write the discovered commands back into `spec.md` → "Commands discovered" so later
+phases (and `$rite-seal`) don't rediscover them. Note the runner version if it matters.
+
+## If nothing exists
+No tests in the project: say so. Propose the minimal test setup as a **follow-up**
+(ask before adding a framework), and prove the slice via runtime observation meanwhile.

package/pack/generated/codex/skills/rite-quick/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: rite-quick
+description: Express lane for a small reversible change: typo/copy/config, rate-limit constant, error message, local variable rename, feature flag, README link, one-file/function fix.
+argument-hint: "<what to change>"
+user-invocable: true
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $rite-quick — express lane for small changes
+
+The full DevRites lifecycle is right for real features; it is **ceremony** for a typo, a
+copy tweak, a one-function fix, or a small config change. `$rite-quick` keeps the
+discipline that matters (idiom, TDD, evidence, escape-to-full-lifecycle) and drops the
+artifacts that don't, in a **single pass**. Senior-engineer "right step, right time" made
+executable, not advisory.
+
+## The significance gate (the whole safety story)
+
+**Run this first. If ANY of these holds, STOP and route to `$rite-spec` — do NOT use the
+express lane:**
+- Touches **auth / authz**, a **data migration**, a **public API contract**, or any
+  **destructive / data-loss** path (the irreversible-risk list — `standards/afk-hitl.md`).
+- Spans **more than one vertical slice**, or more than a couple of files of real logic.
+- **Ambiguous scope** — you'd have to guess what "done" means, or the ask hides a design
+  decision (data model, new dependency, second design system).
+- Security-sensitive input handling, or a measurable performance-critical path.
+- Would **break a declared project principle** (`.devrites/principles.md`) with no recorded,
+  human-approved exception — the express lane never relaxes a project gate; a needed exception is
+  a deliberate human decision, so route it to `$rite-spec`.
+
+If none hold, the change is small + reversible + unambiguous → proceed. **When in doubt,
+escalate** — the cost of the full lifecycle on a small change is minutes; the cost of the
+express lane on a risky one is the failure mode the lifecycle exists to prevent.
+
+## Rules consulted
+Load this lane's conditional standards when needed:
+- `coding-style.md` — naming, guard clauses, reuse-first.
+- `testing.md` — TDD, **completeness** (every touched behavior/element asserted) +
+  **assertion strength** (no tautological tests; see it fail first), scaled to the change.
+- `error-handling.md` / `security.md` — only if the change touches input/errors.
+- `principles.md` — when `.devrites/principles.md` exists; a change that breaks an invariant is a gate, not a quick fix.
+- `definition-of-done.md` — standing Done bar: acceptance mapped, fresh proof, no open hard gates, scoped edits, rollback/docs where needed.
+
+
+## Workflow
+0. **Orient.** Read `core.md`. If a `.devrites/` workspace is active, run the preamble to
+   see it; `$rite-quick` does **not** require one and does **not** create the full tree.
+1. **Significance gate** (above). Fail → STOP, tell the user to run `$rite-spec <feature>`.
+2. **One-line contract.** Restate in 1–3 lines: the change, its **acceptance** (how you'll
+   know it works), and the **scope boundary** (what you will NOT touch). This is the entire
+   "spec + plan" for a quick change — keep it in the chat; optionally drop a `brief.md` +
+   `evidence.md` under `.devrites/work/<slug>/` if the user wants a record. This is the
+   `$rite-frame` FRAME move: if the acceptance won't reduce to a check that could be *false*,
+   the ask is ambiguous → escalate per the significance gate. Its AUDIT pass is the diff
+   self-review in step 5.
+3. **Build with TDD.** Failing test first when behavior changes (see it fail for the right
+   reason) → smallest complete change in the **project's idiom** (reuse before you write,
+   anti-AI-slop) → cover every touched behavior / interactive element with a **real**
+   assertion. UI → check the states + a browser glance.
+4. **Prove (scoped).** Run the **targeted** tests + typecheck / lint for what changed (not
+   the whole suite) → green. Record the command + output. A tautological test that can't
+   fail is not proof.
+5. **Review-lite + ship.** Self-review the diff (correctness, scope, idiom, and — if
+   `.devrites/principles.md` exists — no declared invariant broken; this is `$rite-frame`'s AUDIT
+   pass — one pass, no subagent fan-out). Show the diff, then on the user's confirm commit it
+   (Conventional Commits, atomic) — or hand to `$rite-ship` if a workspace is active. **Never push
+   without the user asking.**
+
+## Escalation (mid-flight) — the Spec Drift Guard still applies
+If the "small" change turns out to be not small — a second slice appears, a real design
+decision surfaces, scope grows past the boundary, or you hit an irreversible-risk item —
+**STOP, say so, and route to `$rite-spec` / `$rite-define`**. Don't quietly grow a quick
+fix into an unreviewed feature; that's the exact drift the lifecycle guards against.
+
+## Output
+Run `devrites-engine progress` when a workspace is active; otherwise skip it. Then use the
+shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: quick change complete — <one line>.
+Changed: <files touched>
+Evidence: tests <cmd -> pass>; assertion check <real asserts saw red | n/a>; boundary held yes
+Open: <none | non-blocking follow-up | tracked workspace needs ship>
+Next: <single recommended command>
+Record: <commit/PR path | .devrites/work/<slug>/evidence.md | not applicable>
+↻ Hygiene: /clear after commit
+```
+
+If the quick boundary does not hold or an escalation remains, use `Stopped / blocked`
+and route to the full lifecycle; do not render `Done`.
+
+**DO NOT** use this lane to dodge the gate — the express lane is for changes that are
+*actually* small, not for shipping risky work faster.