devrites 2.5.1 → 2.6.0

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.6.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.5.2...v2.6.0) (2026-07-05)
+
+### Added
+
+* **installer:** add Codex support ([cd19c70](https://github.com/ViktorsBaikers/DevRites/commit/cd19c70e6c6df5a38a3524c4cb3f8e9885ffedc3))
+
+## [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

package/README.md

@@ -36,7 +36,7 @@ recorded-exception escape hatch instead of silent work-arounds.
   archive/<slug>/             # shipped task, moved here intact (all .md preserved)
 ```
 
-**Stop your AI from shipping half-baked code.** DevRites turns Claude Code into a
+**Stop your AI from shipping half-baked code.** DevRites turns Claude Code or Codex into a
 disciplined senior engineer — one that asks the right questions before writing a line,
 ships features you can actually trust, and refuses to claim "done" without proof.
 
@@ -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.1`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.5.1) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v2.6.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.6.0) — 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)
@@ -145,8 +145,9 @@ Full rationale: [`docs/architecture.md`](docs/architecture.md).
 ## Install
 
 DevRites installs **into a project** (project-local only — it never writes to
-`~/.claude`). Install with `npx` (recommended) or the `curl | bash` one-liner —
-both run the same installer and ship skills, agents, **rules**, and aliases.
+`~/.claude` or `~/.codex`). Install with `npx` (recommended) or the `curl | bash`
+one-liner — both run the same installer and ship Claude Code skills, Codex skills,
+agents, **rules**, and aliases.
 
 ### Installing
 
@@ -168,7 +169,7 @@ npx devrites@latest uninstall
 `npx devrites` is a thin wrapper over the same installer below — the pack is bundled in the
 package, so the install runs **offline** and is **pinned** to the version you request
 (`@latest`, `@1.18.0`, …). It accepts every flag the bash installer does and is still
-project-local (it never writes to `~/.claude`). Requires `bash` — built in on macOS/Linux;
+project-local (it never writes to `~/.claude` or `~/.codex`). Requires `bash` — built in on macOS/Linux;
 on Windows run it inside Git Bash or WSL, or use the `curl | bash` one-liner below.
 
 **One-liner over the network** — no `git clone` or Node required:
@@ -189,7 +190,7 @@ curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/instal
 
 The script is self-bootstrapping: when piped through `bash` it auto-downloads the latest
 release tarball (or the `main` source archive as fallback) into `/tmp` and re-execs from
-there. Requires `curl` and `tar`. No global writes, ever — `~/.claude` is refused.
+there. Requires `curl` and `tar`. No global writes, ever — global agent homes are refused.
 
 **From a local checkout** (same script, no network needed):
 
@@ -208,6 +209,7 @@ Common flags:
 | `--force` | Overwrite existing non-DevRites files |
 | `--no-rules` | Skip the engineering rules |
 | `--no-agents` | Skip the review subagents |
+| `--no-codex` | Skip Codex support files (`.agents/skills`, `.codex/agents`, `AGENTS.md`) |
 | `--rules-only` | Install only the engineering rules |
 | `--short-aliases=all` | Add `/define`, `/build`, `/prove`, `/seal` short aliases (off by default) |
 
@@ -261,7 +263,8 @@ curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/uninst
 ./uninstall.sh --dry-run             # preview, change nothing
 ```
 
-Removes only files listed in `.claude/devrites.manifest` and prunes empty dirs.
+Removes only files listed in `.claude/devrites.manifest` and prunes empty dirs,
+including Codex mirrors when they were installed.
 `.devrites/work/` (your feature data) is always preserved.
 
 ## Recommended setup (optional, but DevRites is much sharper with it)
@@ -274,7 +277,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
@@ -282,9 +285,15 @@ investigation, cheaper context, and real browser proof. None are required.
 
 ## Skills
 
-The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills, 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library (scripts the workflow skills run, not a command). **Prefix convention:** `rite-*` is the user-facing slash-command surface; `devrites-*` is internal (model-invoked, hidden from the menu). Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step, and the other 22 rule files load on demand.
+The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills, 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library (scripts the workflow skills run, not a command). **Prefix convention:** `rite-*` is the user-facing command surface; `devrites-*` is internal (model-invoked, hidden from the menu). Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step, and the other 22 rule files load on demand.
 
-**Two invocation forms.** Every user-invocable skill responds to **both** `/rite <verb>` (menu form — type `/rite` to discover) and `/rite-<verb>` (direct shortcut — muscle memory). The forms are equivalent: `/rite build slice-2` ≡ `/rite-build slice-2`. Use whichever reads more naturally.
+**Claude Code invocation.** Every user-invocable skill responds to **both** `/rite <verb>` (menu form — type `/rite` to discover) and `/rite-<verb>` (direct shortcut — muscle memory). The forms are equivalent: `/rite build slice-2` ≡ `/rite-build slice-2`. Use whichever reads more naturally.
+
+**Codex invocation.** The installer mirrors the same skills to `.agents/skills/`, mirrors DevRites rules to `.agents/devrites/rules/`, injects a Codex compatibility block after each skill's front matter, generates project custom agents in `.codex/agents/`, installs Codex hooks in `.codex/hooks.json` + `.codex/hooks/`, installs the DevRites MCP server at `.codex/mcp/devrites-mcp.mjs`, and creates or merges the needed Codex guidance into `AGENTS.md`. If `AGENTS.md` already exists, DevRites adds a marked block instead of replacing your guidance. In Codex, invoke DevRites via `$rite`, `$rite-spec`, or `/skills`; if you prefer a Claude-only footprint, install with `--no-codex`. Codex must trust the project `.codex/` layer and review the hooks via `/hooks` before non-managed hooks run.
+
+**Rules in Codex.** DevRites engineering rules are mirrored as Markdown under `.agents/devrites/rules/` because they are workflow/craft instructions, not Codex command-approval `.rules` files. The generated `AGENTS.md` block and every mirrored `.agents/skills/*/SKILL.md` tell Codex to read `.agents/devrites/rules/core.md` before workflow work and load the other `.agents/devrites/rules/*.md` files on demand.
+
+**DevRites MCP in Codex.** The installer adds a marked `[mcp_servers.devrites]` block to `.codex/config.toml` and copies the MCP server into `.codex/mcp/`. That gives Codex deterministic tools for DevRites state and gates (`devrites_status`, `devrites_ready`, `devrites_evidence_fresh`, `devrites_acceptance`, and related workspace helpers) without relying on prose or ad-hoc shell commands.
 
 **Custom pinned aliases** (optional). Add your own one-word shortcuts to any `rite-*` skill at runtime with `scripts/pin.sh` — useful for muscle-memory commands like `/b` → `/rite-build` or `/ship` → `/rite-ship`. The wrapper is a thin delegate (same shape the installer uses for `--short-aliases=all`); pinned aliases are manifest-tracked so `./uninstall.sh` cleans them up.
 
@@ -295,7 +304,7 @@ The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + uti
 ./scripts/pin.sh remove b              # drop the alias
 ```
 
-Pinned aliases live at `.claude/skills/<alias>/SKILL.md`. The script refuses `rite-*` names, unknown targets, and writes to `~/.claude`.
+Pinned aliases live at `.claude/skills/<alias>/SKILL.md` and mirror to `.agents/skills/<alias>/SKILL.md` when Codex support is installed. The script refuses `rite-*` names, unknown targets, and global agent homes.
 
 ### Full skill + agent inventory
 
@@ -431,7 +440,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 +461,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.
 
@@ -478,7 +488,7 @@ real UI state, and **prove both layers** (contract tests + browser proof).
 
 ## Safety & scope
 
-- **Project-local only.** Never writes to `~/.claude`. Manifest-managed install/uninstall.
+- **Project-local only.** Never writes to `~/.claude` or `~/.codex`. Manifest-managed install/uninstall.
 - **Feature scope only.** Review/simplify/polish/security stay within the active feature
   and touched files — no project-wide refactors, no drive-by cleanup.
 - **One slice at a time.** `/rite-build` stops after a single verified slice.
@@ -502,6 +512,8 @@ devrites/
   pack/.claude/        # skills/  36 skills — 24 public + 12 internal          ─┐
                        # agents/  13 read-only + 1 writer (slice-wright)         ├─ the pack
                        # rules/   23 rule files + README index                   ┘
+  installed projects   # .claude/ runtime assets; .agents/skills + .codex/agents
+                       # + .codex/hooks/config/mcp + AGENTS.md for Codex
   evals/               # trigger evals (20/skill) + golden/ outcome-eval fixtures
   docs/                # architecture · skills · command-map · usage · flow · release · cli-mcp
     internal/          # research, development notes (gitignored)
@@ -525,7 +537,7 @@ Cross-links: [architecture](docs/architecture.md) ·
 DevRites is auditable Markdown + a small set of shell scripts. The complete security
 policy, including private vulnerability reporting and recommended managed-deployment
 settings, lives in [`SECURITY.md`](SECURITY.md). Highlights: **project-local only**
-(installer refuses any target under `~/.claude`); **no network access** in installer or
+(installer refuses global Claude/Codex agent homes); **no network access** in installer or
 skills (no remote code execution); **`!` shell injection removed** from `/rite` and
 `/rite-status` (state loaded via a `Bash`-invoked script that reads only DevRites' own
 state under `.devrites/`); **auto-trigger** is a deliberate design choice mitigated by
@@ -550,4 +562,4 @@ repository in package registries or plugin marketplaces* are permitted without a
 distributing it, distributing modified versions, mirroring as a fork, or commercial /
 organizational use — requires **approval on request** (ask via
 [the repo](https://github.com/ViktorsBaikers/DevRites)). Source-available. See
-[`LICENSE`](LICENSE). DevRites is independent software for use with Claude Code.
+[`LICENSE`](LICENSE). DevRites is independent software for use with Claude Code and Codex.

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/bin/devrites.mjs

@@ -44,13 +44,14 @@ Common flags (passed straight through to the installer):
   --dry-run             Show the plan, change nothing
   --force               Overwrite existing non-DevRites files
   --rules-only          Install only the engineering rules
+  --no-codex            Skip Codex support files (.agents, .codex, AGENTS.md)
   --short-aliases=all   Also install /define /build /prove /seal
   --no-agents           Skip the review subagents
 
   --version             Print the devrites version
   --help                Show this help (use "<subcommand> --help" for installer-level detail)
 
-DevRites is project-local — it never writes to ~/.claude.
+DevRites is project-local — it never writes to ~/.claude or ~/.codex.
 Requires bash (Git Bash or WSL on Windows). No-Node fallback:
   curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash
 `);

package/docs/cli-mcp.md

@@ -27,14 +27,19 @@ any agent's loop or a pre-merge CI step. `devrites help` lists them all.
 
 ## The MCP server
 
-`mcp/devrites-mcp.mjs` (in the DevRites source) is a dependency-free MCP **stdio** server
-that exposes the read/gate operations as MCP tools (`devrites_orient`, `devrites_ready`,
+`mcp/devrites-mcp.mjs` is a dependency-free MCP **stdio** server that exposes the
+read/gate operations as MCP tools (`devrites_orient`, `devrites_ready`,
 `devrites_evidence_fresh`, `devrites_acceptance`, `devrites_status`, `devrites_active`,
 `devrites_list`, `devrites_use`). It shells out to the CLI, so it stays a thin surface over
 the same scripts — no SDK, no dependencies.
 
-Register it in a project's `.mcp.json`, running from the project root (it auto-finds the
-installed CLI; override the path with the `DEVRITES_CLI` env var):
+For Codex installs, DevRites copies the server to `.codex/mcp/devrites-mcp.mjs` and
+adds a marked `[mcp_servers.devrites]` block to `.codex/config.toml`. After the project
+`.codex/` layer is trusted, Codex can use those MCP tools directly.
+
+For other MCP clients, register the source server in a project's `.mcp.json`, running
+from the project root (it auto-finds the installed CLI; override the path with the
+`DEVRITES_CLI` env var):
 
 ```json
 {

package/docs/skills.md

@@ -1,6 +1,6 @@
 # All 36 skills
 
-The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills and 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library skill (`user-invocable: false`, not a command) that ships the cross-cutting scripts the workflow skills run: the read-only orientation preamble and the `readiness` / `evidence-fresh` / `acceptance` gate scripts, plus the `tick-afk` / `resolve` / `close-out` state mutators. Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0) and pulls the other 22 rule files on demand (no carrier skill, no session-start autoload). A unified `devrites` CLI and an MCP server expose the `devrites-lib` ops to any tool (see [`cli-mcp.md`](cli-mcp.md)).
+The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills and 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library skill (`user-invocable: false`, not a command) that ships the cross-cutting scripts the workflow skills run: the read-only orientation preamble and the `readiness` / `evidence-fresh` / `acceptance` gate scripts, plus the `tick-afk` / `resolve` / `close-out` state mutators. Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0) and pulls the other 22 rule files on demand (no carrier skill, no session-start autoload). The installer mirrors skills to `.agents/skills` for Codex, mirrors rules to `.agents/devrites/rules`, injects Codex-specific dispatch/rules guidance into those mirrors, generates `.codex/agents` from the DevRites review agents, installs Codex hooks in `.codex/hooks.json` + `.codex/hooks/`, merges DevRites guidance into `AGENTS.md`, and registers the project-local DevRites MCP server through `.codex/config.toml`. A unified `devrites` CLI and an MCP server expose the `devrites-lib` ops to any tool (see [`cli-mcp.md`](cli-mcp.md)).
 
 **Naming convention.** `rite-*` is the user-facing slash-command surface (lifecycle phases plus utilities — `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`). `devrites-*` is internal (model-invoked, hidden from the menu) and collision-avoiding against bundled Claude Code skill names. Visibility is governed by each skill's `user-invocable:` flag; the prefix mirrors it.
 
@@ -31,7 +31,7 @@ single `## Gotchas` heading is a possible future normalization; the content alre
 
 ## Commands quick reference
 
-Every user-invocable skill responds to **both** `/rite <verb>` (menu form — type `/rite` for the discoverable entry point) and `/rite-<verb>` (direct shortcut). Both hit the same skill; use whichever reads more naturally.
+In Claude Code, every user-invocable skill responds to **both** `/rite <verb>` (menu form — type `/rite` for the discoverable entry point) and `/rite-<verb>` (direct shortcut). Both hit the same skill; use whichever reads more naturally. In Codex, use `$rite`, `$rite-<verb>`, or `/skills` to select the mirrored skill from `.agents/skills`; when a skill dispatches a DevRites subagent, the Codex mirror instructs Codex to use the matching `.codex/agents/devrites-*.toml` custom agent. The generated `AGENTS.md` block tells Codex to read `.agents/devrites/rules/core.md` before DevRites workflow work.
 
 | Menu form | Direct shortcut | Phase | Does |
 |---|---|---|---|
@@ -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