devrites 2.5.0 → 2.5.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [2.5.2](https://github.com/ViktorsBaikers/DevRites/compare/v2.5.1...v2.5.2) (2026-06-28)
+
+### Changed
+
+* **skills:** swap browser-harness for Playwright MCP ([9c13e72](https://github.com/ViktorsBaikers/DevRites/commit/9c13e72c94e81f7df6dc7d07bf23acdfd4d18ddd))
+
+## [2.5.1](https://github.com/ViktorsBaikers/DevRites/compare/v2.5.0...v2.5.1) (2026-06-28)
+
+### Fixed
+
+* **rite:** ask HITL build gaps inline instead of deferring to resolve ([33266f1](https://github.com/ViktorsBaikers/DevRites/commit/33266f19d9ad30f53fc8ef267f486a5562be61c7))
+
 ## [2.5.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.4.0...v2.5.0) (2026-06-28)
 
 ### Added

package/README.md

@@ -101,14 +101,14 @@ Full diagram set (lifecycle, polish orchestrator, review fan-out, debug loop,
 rules carrier, workspace state, namespace map) →
 [`docs/flow.md`](docs/flow.md).
 
-**Status:** [`v2.5.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.5.0) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v2.5.2`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.5.2) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Contents
 
 - [Why distributed skills](#why-distributed-skills-not-one-engine)
 - [Modes — HITL & AFK](#modes--hitl--afk)
 - [Install](#install) — [npx / bash](#installing) · [upgrade](#upgrading-an-existing-install)
-- [Recommended setup](#recommended-setup-optional-but-devrites-is-much-sharper-with-it) — codegraph · graphify · browser-harness
+- [Recommended setup](#recommended-setup-optional-but-devrites-is-much-sharper-with-it) — codegraph · graphify · Playwright MCP
 - [Skills](#skills) — 36 total · full catalogue in [`docs/skills.md`](docs/skills.md)
 - [Typical workflow](#typical-workflow) · [Worked examples](docs/usage.md)
 - [Engineering rules](#engineering-rules) · [Browser proof ladder](#browser-proof-ladder) · [Frontend & fullstack](#frontend--fullstack)
@@ -274,7 +274,7 @@ one and **degrades gracefully** when it's absent.
 |---|---|---|
 | **codegraph** | A code-intelligence index. `/rite-spec`, `/rite-define`, and `/rite-plan` use it to understand structure, **placement**, callers, and **impact** cheaply — deeper investigation and sharper specs, at a fraction of the tokens of reading files. | Build the index in your project (e.g. `codegraph init`) so its `codegraph_*` tools / a `.codegraph/` are present. |
 | **graphify** | A codebase → knowledge-graph (`graphify-out/`) — same benefit for "where is X / what calls Y / what would Z break". | Generate it for your project (the `/graphify` skill). |
-| **[browser-harness](https://github.com/browser-use/browser-harness)** | Drives your real browser so `/rite-prove` and `/rite-polish` capture **real UI evidence** — screenshots, console, network, responsive — the top rung of the proof ladder. | Install it, connect it to your Chrome, and verify with its doctor. |
+| **[Playwright MCP](https://github.com/microsoft/playwright-mcp)** | Drives a real browser so `/rite-prove` and `/rite-polish` capture **real UI evidence** — screenshots, console, network, responsive — the top rung of the proof ladder (paired with **Chrome DevTools MCP** for Lighthouse / perf trace). | Configure the Playwright MCP server in Claude Code; DevRites detects it, never installs it. |
 
 Without them, DevRites reads files instead of a code graph and uses Claude Code's built-in
 `/run`+`/verify` (or documented manual steps) instead of a browser. With them: deeper
@@ -431,7 +431,7 @@ the build, records the drift in `drift.md`, asks you when product behavior
 changes, and routes through `/rite-plan repair` before resuming.
 
 Worked examples (spec-then-plan, mid-build drift, UI feature with
-browser-harness, backend-only, polish modes, zoom-out, mid-flight handoff):
+Playwright MCP, backend-only, polish modes, zoom-out, mid-flight handoff):
 **[docs/usage.md](docs/usage.md)**.
 
 ## Engineering rules
@@ -452,9 +452,10 @@ diagram: [`docs/flow.md` § Engineering-rules loading](docs/flow.md#6-engineerin
 
 ## Browser proof ladder
 
-For UI work DevRites prefers real runtime evidence, top-down: **browser-harness** (if
-installed) → **Chrome DevTools MCP** → Claude Code **`/run`+`/verify`** → **project-native
-E2E** (Playwright / Cypress / Capybara) → **manual fallback**. It detects tooling but
+For UI work DevRites prefers real runtime evidence, top-down: **Playwright MCP** (if
+configured, paired with **Chrome DevTools MCP** for Lighthouse / perf trace) → Claude Code
+**`/run`+`/verify`** → **project-native E2E** (Playwright / Cypress / Capybara) → **manual
+fallback**. It detects tooling but
 never installs it, stops at auth walls, and treats a screenshot **path** as unproven
 until it's opened and described.
 

package/SECURITY.md

@@ -175,7 +175,7 @@ settings file is never overwritten on update, so your own permission rules are s
 
 DevRites vendors no third-party code (see `NOTICE.md`). It depends on Claude
 Code itself and, optionally and at the user's choice, on codegraph /
-graphify / browser-harness — each of which is invoked through its own
+graphify / Playwright MCP — each of which is invoked through its own
 documented interface, not bundled.
 
 ### Known non-issues

package/docs/skills.md

@@ -126,7 +126,7 @@ The 11 model-invoked internal specialists (hidden from the menu): `devrites-inte
 | Skill | What It Does | Use When |
 |---|---|---|
 | [`rite-prove`](../pack/.claude/skills/rite-prove/SKILL.md) | Tests + build + runtime + browser evidence for the current scope. | All slices built; ready for full verification. |
-| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | Browser proof ladder: browser-harness → Chrome DevTools MCP → `/run`+`/verify` → project E2E → manual. Auto-emits the structured **Visual Verdict** (per-criterion PASS/FAIL vs `design-brief.md`) for UI slices — consumed by `devrites-frontend-reviewer` and gated at `/rite-seal`. | Scope touches UI. |
+| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | Browser proof ladder: Playwright MCP → Chrome DevTools MCP → `/run`+`/verify` → project E2E → manual. Auto-emits the structured **Visual Verdict** (per-criterion PASS/FAIL vs `design-brief.md`) for UI slices — consumed by `devrites-frontend-reviewer` and gated at `/rite-seal`. | Scope touches UI. |
 
 ### Polish — Normalize, then ship-quality detail pass
 

package/docs/usage.md

@@ -115,7 +115,7 @@ You: 2
 /rite-build          # resumes on the corrected plan
 ```
 
-## 4) UI feature with browser-harness
+## 4) UI feature with Playwright MCP
 
 ```text
 /rite-spec settings-theme-toggle
@@ -133,7 +133,7 @@ You: 2
     anti-AI-slop
 
 /rite-prove
-  → devrites-browser-proof: browser-harness detected → new_tab(route),
+  → devrites-browser-proof: Playwright MCP detected → browser_navigate(route),
     screenshot at 375 + 1280, exercise the toggle, check console clean,
     **compare to references/**, record to browser-evidence.md
 

package/pack/.claude/skills/devrites-browser-proof/SKILL.md

@@ -14,13 +14,17 @@ The same ladder captures a **developer-facing docs / getting-started page** for
 commands match what actually runs, and note the result in `browser-evidence.md` / `devex.md`.
 
 ## Ladder (top-down)
-1. **browser-harness** — detect `command -v browser-harness`. Connects to the user's
-   Chrome over CDP. Pattern: `new_tab(url)` → `wait_for_load()` → `capture_screenshot()`
-   → read the pixel → `click_at_xy(x,y)` → re-screenshot. Coordinate clicks pass through
-   iframes/shadow/cross-origin. `print(page_info())` for liveness. Don't launch a new
-   browser; don't auto-install.
-2. **Chrome DevTools MCP** (if configured) — screenshots, DOM, console, network,
-   performance, accessibility tree.
+1. **Playwright MCP** (preferred) — detect by tool availability (the `browser_*` tools are
+   present, e.g. `browser_navigate`); detect, don't install. Drives a Playwright-managed
+   browser. Pattern: `browser_navigate(url)` → `browser_snapshot()` (the accessibility tree
+   is the primary perception) → `browser_click` / `browser_type` on a **ref from the
+   snapshot** → `browser_take_screenshot()`. Read `browser_console_messages()` and
+   `browser_network_requests()` for console/network evidence; `browser_resize(w,h)` for each
+   responsive viewport. Act on snapshot refs, not pixel coordinates.
+2. **Chrome DevTools MCP** (when configured — use **alongside** Playwright MCP for more
+   detail) — screenshots, DOM, console, network, performance trace, accessibility tree, and
+   `lighthouse_audit`. Playwright MCP drives the flow; DevTools MCP adds Lighthouse + the perf
+   trace Playwright can't produce.
 3. **Claude Code `/run` + `/verify`** (if available) — launch + observe the app.
 4. **Project-native E2E** (only if present) — Playwright/Cypress/Capybara/Selenium via
    the project's existing commands. Don't add a new framework.
@@ -31,11 +35,13 @@ If `spec.md` carries a perf budget — or a frontend regression risk is visible
 CWV numbers here so the perf reviewer judges real data instead of guessing. Use the highest
 rung available; **detect, don't install**.
 
-1. **Chrome DevTools MCP** (if configured) — `lighthouse_audit` for LCP/INP/CLS + the
-   Lighthouse performance score. Source label: **Lab (Lighthouse)**. A `performance_*` trace
-   gives **Trace (DevTools)** attribution.
-2. **browser-harness** — drive the route, capture a performance trace over CDP. Source
-   label: **Trace (DevTools)**.
+1. **Chrome DevTools MCP** (preferred for CWV when configured) — `lighthouse_audit` for
+   LCP/INP/CLS + the Lighthouse performance score. Source label: **Lab (Lighthouse)**. A
+   `performance_*` trace gives **Trace (DevTools)** attribution.
+2. **Playwright MCP** — `browser_navigate` the route, then `browser_evaluate` the web-vitals
+   library to read LCP/INP/CLS off the live page. Source label: **Trace (DevTools)** (a
+   real-page number, not a Lighthouse score). Use **alongside** rung 1 when both are present —
+   the lab score and the trace corroborate each other.
 3. **CrUX / PageSpeed Insights** — only if the user supplied an API key. Field data, p75.
    Source label: **Field (CrUX)**.
 4. **None available** → mark CWV **pending (manual)** and name the exact command

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

@@ -105,12 +105,23 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
    right next slice. Write the slice's `Mode` to `state.md` as `Slice mode: <HITL|AFK>` on
    **every** selection (not only on the HITL pause path); `/rite-resolve` clears or updates
    it on resume.
-2a. **HITL gate (pre-action pause).** Read the slice's `Mode`. If `HITL` → render the
-    checkpoint per [`reference/checkpoint-protocol.md`](reference/checkpoint-protocol.md):
-    append a `questions.md` entry with the slice's `Checkpoint:` + `Gate:` + `SLA:`,
-    write the `Awaiting human` block to `state.md`, set `Status: awaiting_human`, run
-    the `notify:` hook if `.devrites/AFK` defines one, then **STOP**. Resume happens
-    when the user runs `/rite-resolve <qid> "<answer>"`.
+2a. **HITL gate (pre-action pause).** Read the slice's `Mode`. If `HITL`, surface the
+    checkpoint as a ranked **option set** and resolve it **before** any code lands, per
+    [`reference/checkpoint-protocol.md`](reference/checkpoint-protocol.md). Branch on whether
+    a human is here:
+    - **Human present (interactive — no `.devrites/AFK`) → ask inline via `AskUserQuestion`.**
+      This is the default for an interactive build. Render 2–4 options, the recommended one
+      **first and labelled `(Recommended)`**, each with its dimension-tagged rationale + the
+      trade-off it accepts, plus the `Something else — I'll describe it` escape hatch. The
+      human picks; record the pick to `questions.md` (`answered`) + `decisions.md` (through the
+      `resolve.sh` writer), clear the gate, and **continue to step 3 in place** — do **not**
+      STOP, do **not** route through `/rite-resolve`.
+    - **Human absent / AFK (`.devrites/AFK` present) → auto-pick or persist + STOP.** For a gate
+      in `allow_gates`, auto-pick the recommended option (option 1) and proceed; otherwise
+      append the `questions.md` entry, write the `Awaiting human` block to `state.md`, set
+      `Status: awaiting_human`, fire the `notify:` hook, then **STOP** — resume when the user
+      runs `/rite-resolve <qid> "<answer>"`. `blocking` / `escalating` / irreversible-risk gates
+      always take this stop path, never the AFK auto-pick.
 3. **Snapshot the tree, then dispatch the build core to `devrites-slice-wright`** — one `Task`
    call, fresh context. **First**, capture the pre-dispatch tree so the reconcile gate (step 6)
    can prove you never touched source — run this immediately before the `Task` call:

package/pack/.claude/skills/rite-polish/reference/harden-checklist.md

@@ -91,7 +91,7 @@ If the project has the tools, run them; capture evidence in `evidence.md`.
 - `prefers-reduced-motion`: emulate in DevTools → re-verify motion.
 - Throttle to "Slow 3G" → re-verify loading + error states.
 - Lighthouse / axe / pa11y → re-verify accessibility floor.
-- Browser-harness or Chrome DevTools MCP (per `devrites-browser-proof`) → capture
+- Playwright MCP or Chrome DevTools MCP (per `devrites-browser-proof`) → capture
   screenshots of the worst-case input states above.
 
 ## Reporting in `/rite-polish`

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

@@ -14,7 +14,7 @@ workspace first; if none, run `/rite-spec <feature>`.
 > single change; `/run` launches 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
-> (browser-harness → DevTools MCP → `/run`+`/verify` → project E2E →
+> (Playwright MCP → DevTools MCP → `/run`+`/verify` → project E2E →
 > manual), and writes `evidence.md` + `browser-evidence.md` keyed to the
 > active `.devrites/work/<slug>/`. Use `/verify` or `/run` on their own
 > when there is no DevRites feature workspace.

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

@@ -5,7 +5,7 @@ What `browser-evidence.md` must capture for a UI slice. Delegates to
 
 ```markdown
 ## Slice <N> — <name>  (<date>)
-- Tooling: browser-harness | devtools-mcp | /run+/verify | <e2e> | manual
+- Tooling: playwright-mcp | devtools-mcp | /run+/verify | <e2e> | manual
 - Route(s): <url(s) exercised>
 - Viewports: 375 / 768 / 1280  (note which were checked)
 - Screenshots: <path(s)>  — described: <what is actually visible>

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

@@ -3,12 +3,14 @@
 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. **browser-harness** (preferred when installed & connected)
-   - Detect: `command -v browser-harness`. Use its doctor/connection check only when
-     safe. Capabilities: navigation, screenshots, coordinate clicks, console logs, DOM
-     reads, network, raw CDP. Connects to the user's Chrome — don't launch a new browser.
-2. **Chrome DevTools MCP** (if configured) — screenshots, DOM, console, network,
-   performance, accessibility tree.
+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,

package/package.json

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