devrites 2.4.0 → 2.5.0

package/pack/.claude/skills/rite-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-spec
-description: Investigate a new feature and write `spec.md` (placement, gaps, design refs, measurable acceptance) under `.devrites/work/<slug>/`. Use when the user says "new feature", "spec this out", "start a project", "I have an idea". Not for planning approved specs (use `/rite-define`) or replanning (use `/rite-plan`).
+description: Investigate a new feature and write `spec.md` (placement, gaps, design refs, measurable acceptance) under `.devrites/work/<slug>/`. Use when the user says "spec out a new feature" or "I have an idea". Not for planning approved specs (use `/rite-define`) or replanning (use `/rite-plan`).
 argument-hint: "<feature or idea>"
 user-invocable: true
 ---
@@ -45,6 +45,25 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
    [ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
    [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
    ```
+0a. **Brownfield check — onboard before speccing onto un-adopted existing code.** If this is an
+   **existing codebase** (real source predating DevRites) that has **never been adopted** — no
+   `.devrites/conventions.md`, no prior `.devrites/work` or `.devrites/archive` — the build has no
+   conventions ledger to follow and the first slice would guess the project's idioms. Route
+   through `/rite-adopt` **first**, carrying `$ARGUMENTS` as its *next objective*: adopt
+   reverse-derives the baseline `spec.md`, **seeds the conventions ledger**, and proposes
+   principles, so this feature is specced on top of an onboarded project (adopt owns the
+   onboarding; `/rite-spec` only detects and routes — no duplicated logic). In **HITL** present a
+   ranked option (recommended: *adopt first, then spec this on top*; escape hatch: *spec-only, skip
+   onboarding*); in **AFK** (adoption allowed) run `/rite-adopt` first automatically. **Greenfield
+   (no pre-existing source) or an already-onboarded project → skip silently** — never block a spec
+   for the absence of adoption (the same no-op discipline as the principles gate). Cheap probe:
+   ```bash
+   if [ ! -f .devrites/conventions.md ] && [ ! -d .devrites/archive ] \
+      && [ -z "$(ls .devrites/work 2>/dev/null)" ] \
+      && [ -n "$(git ls-files 2>/dev/null | grep -vE '^\.(devrites|claude)/' | head -1)" ]; then
+     echo "brownfield, not yet adopted → recommend /rite-adopt first (carry this idea as its next objective)"
+   else echo "greenfield or already onboarded → continue spec"; fi
+   ```
 1. **Understand the request** (`$ARGUMENTS`). Restate the goal and the *real problem
    behind it* in a sentence or two.
 2. **Investigate deeply** — [investigation](reference/investigation.md). Produce, and
@@ -78,7 +97,7 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
    backend/data/CLI features skip this.
 4. **Close the gaps with the human.** Turn each material gap/issue into a question — one
    at a time, **best guess attached**, structured options + escape hatch. (Vague ask →
-   `devrites-interview`; rough idea → `rite-pressure-test`; ladders in
+   `devrites-interview`; rough idea → `/rite-pressure-test`; ladders in
    [interview-patterns](reference/interview-patterns.md) / [question-protocol](reference/question-protocol.md).)
    For a vague ask, **map the decision tree** and resolve each branch depth-first; **cover
    every dimension** (objective · scope · data model · UX · integration · non-functional ·

package/pack/.claude/skills/rite-spec/reference/state-workspace.md

@@ -13,6 +13,7 @@ workspace first; if none exists, it stops and tells the user to run `/rite-spec
     <feature-slug>/
       brief.md                    # short user-facing objective
       spec.md                     # what to build + why (from /rite-spec)
+      checklists/                 # spec-quality checklists — "unit tests for English", one <domain>.md per requirement domain (from /rite-spec; gated at spec readiness)
       references/                 # saved design/reference assets (screenshots, exports, video)
       references.md               # index of design references (saved files + links)
       strategy.md                 # strategic review: scope mode + pre-mortem + dimension scores (from /rite-temper; optional — always invoked, significance-gated, in /rite-autocomplete)
@@ -20,6 +21,8 @@ workspace first; if none exists, it stops and tells the user to run `/rite-spec
       tasks.md                    # ordered vertical slices (from /rite-define)
       eng-review.md               # engineering plan review: scope challenge + axis findings + failure modes + parallelization (from /rite-vet — run on every plan; depth scales light/full, never skipped; always in /rite-autocomplete)
       test-plan.md                # build-readable coverage target: coverage diagram + per-gap test requirements + acceptance→test map (from /rite-vet; read by /rite-build + /rite-prove)
+      coverage.md                 # traceability matrix: AC-id → slice(s) → test (from /rite-define; walked by /rite-prove + /rite-seal)
+      devex.md                    # developer-experience scorecard — predicted (/rite-vet) → measured (/rite-prove) → reconciled (/rite-seal); only when a developer-facing surface is in scope
       state.md                    # phase, active slice, risk, next step
       questions.md                # asked questions + answers
       decisions.md                # decisions + rationale (+ a `## Dead ends` section: approaches tried that failed + why, so retries don't repeat them)
@@ -27,6 +30,7 @@ workspace first; if none exists, it stops and tells the user to run `/rite-spec
       drift.md                    # spec/plan drift observations + resolutions
       touched-files.md            # files changed or intentionally inspected
       evidence.md                 # commands run + results
+      forge-report.md             # competitive-build record: K candidates → winner + grafts (from /rite-build on a `Forge: yes` slice; rare)
       browser-evidence.md         # screenshots, routes, console, viewport checks
       design-brief.md             # UX/UI contract — if UI involved (from /rite-spec via devrites-ux-shape; refined per slice in /rite-build)
       polish-report.md            # normalize+polish output
@@ -48,10 +52,14 @@ workspace first; if none exists, it stops and tells the user to run `/rite-spec
   `ACTIVE`. **`/rite-define` reads `spec.md`** and adds `plan.md` + `tasks.md` and updates
   `state.md`. Other skills read the active workspace; none create a new one.
 - Each phase **updates `state.md`** and the relevant evidence files.
-- Don't create `strategy.md` / `eng-review.md` / `test-plan.md` / `evidence.md` /
-  `browser-evidence.md` / `design-brief.md` / `polish-report.md` / `review.md` / `seal.md` /
-  `ship.md` / `handoff.md` until the producing phase runs — absence is meaningful (it means
-  "not done yet"). `strategy.md` is written by `/rite-temper` (which may also edit `spec.md` /
+- Don't create `checklists/` / `strategy.md` / `eng-review.md` / `test-plan.md` /
+  `coverage.md` / `devex.md` / `evidence.md` / `forge-report.md` / `browser-evidence.md` /
+  `design-brief.md` / `polish-report.md` / `review.md` / `seal.md` / `ship.md` / `handoff.md`
+  until the producing phase runs — absence is meaningful (it means "not done yet").
+  `coverage.md` is the `/rite-define` traceability matrix; `devex.md` is the conditional DX
+  scorecard (only when a developer-facing surface is in scope — greenfield no-op otherwise);
+  `forge-report.md` records a competitive `Forge: yes` build and is absent on the common
+  single-path slice. `strategy.md` is written by `/rite-temper` (which may also edit `spec.md` /
   `decisions.md` / `assumptions.md` via the Spec Drift Guard); its absence means the spec was
   planned without a strategic review. `eng-review.md` + `test-plan.md` are written by `/rite-vet`
   (which also hardens `plan.md` / `tasks.md`, and routes acceptance-changing deltas via the Spec

package/pack/.claude/skills/rite-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-status
-description: Read-only report on the active feature — phase, active slice, next action, evidence, open questions, drift, risks, handoff readiness. Use when the user says "where am I", "what's next", "status", "is this ready to ship", "show the active feature". Not for invoking phases or for the menu (use `/rite`).
+description: Read-only report on the active feature — phase, active slice, next action, evidence, open questions, drift, risks, and handoff readiness. Not for invoking phases or for the menu (use `/rite`).
 argument-hint: "[feature-slug]"
 user-invocable: true
 disable-model-invocation: true

package/pack/.claude/skills/rite-temper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-temper
-description: Strategic review of a readied `spec.md` before planning — pick a scope mode (expand / selective / hold-rigor / reduce-to-MVP), run a pre-mortem, harden the spec, and fold decisions back via the Spec Drift Guard plus a persistent `strategy.md`. Use when the user says "temper this", "strategy review", "think bigger", "scope check", "pre-mortem the spec", "are we over/under-building", or before defining a big or risky feature. Not for a rough idea (`/rite-pressure-test`), a mid-build decision (`devrites-doubt`), a code diff (`/rite-review`), or the final gate (`/rite-seal`).
+description: Temper a readied `spec.md` before planning. Use when the user says "temper this", "strategy review", "pre-mortem the spec", "are we over/under-building", or before defining a big or risky feature. Not for a rough idea (`/rite-pressure-test`), a mid-build decision (`devrites-doubt`), a code diff (`/rite-review`), or the final gate (`/rite-seal`).
 argument-hint: "[feature-slug] [--mode expand|selective|hold|reduce]"
 user-invocable: true
 ---

package/pack/.claude/skills/rite-vet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-vet
-description: Engineering review of a defined plan before any code — challenge implementation scope, then review architecture / code-quality / test-coverage / performance through senior-engineer lenses, confidence-banding each finding; harden `plan.md` / `tasks.md` and write `eng-review.md` + the build-readable `test-plan.md`. Use when the user says "vet the plan", "engineering review", "review the architecture", "lock in the plan", or before building a feature. Not for the spec's strategy (`/rite-temper`), a mid-build decision (`devrites-doubt`), a code diff (`/rite-review`), or the final gate (`/rite-seal`).
+description: Vet a defined plan before any code with a senior-engineer plan review. Use when the user says "vet the plan", "engineering review", "lock in the plan", or before building a feature. Not for the spec's strategy (`/rite-temper`), a mid-build decision (`devrites-doubt`), a code diff (`/rite-review`), or the final gate (`/rite-seal`).
 argument-hint: "[slug] [--cross-model] [--full]"
 user-invocable: true
 ---

package/pack/.claude/skills/rite-zoom-out/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: rite-zoom-out
-description: Zoom out one abstraction layer in unfamiliar code — return a structural map (modules, callers, callees, ADR/decisions touching the area) in the project's vocabulary. Use when the user says "zoom out", "map this", "bigger picture", "I don't know this area", "what calls this". Not for implementing changes (read-only) or one-symbol lookups (use grep).
+description: Zoom out one abstraction layer in unfamiliar code — return a structural map (modules, callers, callees, ADR/decisions touching the area) in the project's vocabulary. Use when the user says "zoom out", "map this", or "what calls this". Not for implementing changes (read-only) or one-symbol lookups (use grep).
+argument-hint: "[symbol | file | area to map]"
 user-invocable: true
 ---
 
@@ -16,7 +17,7 @@ on demand.
 
 ## What this skill returns
 
-A **map, not an essay**. One pass should answer:
+A **structural map** — terse. One pass should answer:
 
 - **The area** — what this code is for, in one sentence, using the project's own
   vocabulary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "DevRites — disciplined senior-engineer workflow skills pack for Claude Code",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",

package/pack/.claude/skills/rite-review/reference/parallel-dispatch.md

@@ -1,62 +0,0 @@
-# Parallel review dispatch
-
-How `/rite-review` and `/rite-seal` fan out the fresh-context review subagents under `.claude/agents/`. Loaded on demand by the calling skill — not a skill itself.
-
-DevRites ships ten fresh-context review subagents under `.claude/agents/` (plus the write-capable `devrites-slice-wright`, not a reviewer). Eight are post-build reviewers used at the seal / multi-axis review; the other two are gate-specific and *not* part of this fan-out — `devrites-strategy-reviewer` is **pre-plan** (for `/rite-temper`) and `devrites-plan-reviewer` is **pre-build** (for `/rite-vet`). The seal and the multi-axis review need most of the post-build reviewers running **at the same time**, on the same workspace + diff, so the verdicts don't contaminate each other.
-
-Pattern: delegate to specialized agents with isolated context, brief each one precisely, run them concurrently, reconcile on return.
-
-## When to use which subagent
-
-| Subagent | Always | Conditional |
-|---|---|---|
-| `devrites-spec-reviewer` | `/rite-review` Spec axis; `/rite-seal` | — |
-| `devrites-code-reviewer` | `/rite-review` Code-review axis; `/rite-seal` | — |
-| `devrites-test-analyst` | `/rite-seal` | — |
-| `devrites-frontend-reviewer` | — | UI files in the diff |
-| `devrites-security-auditor` | — | input / auth / data / external integrations / secrets in scope |
-| `devrites-performance-reviewer` | — | perf budget in `spec.md` or visible regression risk |
-| `devrites-doubt-reviewer` | — | a non-trivial decision is being stood up (called from `devrites-doubt`) |
-| `devrites-simplifier-reviewer` | — | `/rite-polish` Phase 1 audit (called from `devrites-audit simplify`) |
-
-## Dispatch shape
-
-For each chosen subagent, the caller uses the `Task` tool with this prompt shape:
-
-```
-Audit the active DevRites feature.
-
-Workspace: .devrites/work/<slug>/
-Read (yourself, fresh context):
-  - spec.md  (+ acceptance criteria)
-  - touched-files.md
-  - the git diff
-  - <any axis-specific files: decisions.md, evidence.md, references/...>
-
-Apply your documented discipline. Return labeled findings (Critical /
-Important / Suggestion / Nit / FYI) using your documented output format,
-ONE FINDING PER LINE, cite file:line.
-
-Feature scope only. No edits. Do not summarize or re-rank — the caller
-reconciles.
-```
-
-Rules:
-
-- **One Task call per subagent.** Send them in a single message with multiple `Task` invocations so the runtime dispatches concurrently.
-- **No cross-pollination.** Each subagent gets only its narrow brief and the workspace path. Do not pass another subagent's findings into a sibling's prompt — that recreates the masking problem.
-- **No author context.** Do not include the caller's analysis or the user's framing of the change; the point is a fresh, adversarial read.
-- **Feature scope only.** Each subagent must stay inside `touched-files.md` + the diff.
-
-## Reconciliation
-
-When the subagents return:
-
-1. **Quote verbatim.** Place each subagent's findings under its own `## <axis>` heading in `review.md` / `seal.md`. Do not merge, re-rank, or summarize. `devrites-code-reviewer` runs its **full** documented discipline (tests-first, correctness, readability, architecture, maintainability, standards); the inline lead **reconciles** the returned reports — it does not re-run those same axes itself.
-2. **Surface contradictions explicitly.** "Spec axis says complete, Code-review axis says untestable" is a finding, not noise. The caller decides at the gate.
-3. **Severity is the gate, not a score.** Sum the labels (`Critical / Important / Suggestion / Nit / FYI`) and apply the caller's gate (`/rite-seal` blocks on `Critical == 0`; `/rite-review` reports counts).
-4. **One scale.** All subagents use the same five-label scale. Reject any subagent output that invents its own.
-
-## Fallback
-
-If the `Task` tool is unavailable in the current environment, the caller runs the relevant subagent discipline **inline** in its own context and flags the result as a fallback (not an independent review). The seal weighs the fallback differently — see [`../../rite-seal/reference/risk-and-rollback.md`](../../rite-seal/reference/risk-and-rollback.md).