Website ·
Quick reference ·
Command map ·
Worked examples ·
Changelog
DevRites is a repository-local workflow for AI coding agents. It turns a
feature request into a spec, a sliced plan, working code, recorded proof, a
release decision, and an explicit ship step. It runs inside Claude Code, Codex,
omp, pi, Devin CLI, and DSH.
DevRites keeps that work in `.devrites/` inside your repository, where chat
history can't lose it. After you clear the conversation, switch hosts, or hand
the feature to another engineer, the next session reads the same plan,
decisions, and evidence before it continues.
**Status:** [`v7.3.11`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v7.3.11): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
This is the latest published release; `main` may contain unreleased work.
## Why DevRites
| Without a workflow | With DevRites |
| --- | --- |
| The plan lives in a chat window and disappears on `/clear`. | Spec, plan, decisions, and questions are Markdown files in `.devrites/work//`. |
| The agent says "tests pass". | Proof must be positive and discriminating, and it is bound to a digest of the exact candidate files. |
| The agent that wrote the code also reviews it. | Seventeen fresh-context specialist agents plan, review, audit, and prove. Only one of them can write code. |
| Commits and pushes happen whenever the agent decides. | Seal decides `GO` or `NO-GO`. Ship acts only after you type a fresh, literal `GO`. |
| Every change gets the same ceremony. | `/rite-quick` handles a small reversible change. The full lifecycle is for features and risky work. |
## Quick start
**1. Install** from the root of your project. Node.js 18 or later is required to
install and run DevRites. Development in this repository (`npm ci`, which
`.npmrc` runs with `engine-strict=true`) needs Node.js 22.22.2 or later within
22.x, or 24.15 or later; Node 23.x and 24.0 through 24.14 fail with `EBADENGINE`.
```bash
npx devrites@latest
```
Or paste this to your coding agent:
```text
Install DevRites in this project: run `npx devrites@latest` from the repository
root, then run /rite-doctor ($rite-doctor in Codex) and report any FAIL line
with its fix.
```
The installer adds project-local support for Claude Code, Codex, omp, pi, Devin CLI, and DSH. It does not write skills, agents, or hooks to `~/.claude`,
`~/.codex`, `~/.pi`, or `~/.config/devin`.
**2. Pick the smallest route** that still protects the work.
| You want to… | Claude Code, omp, pi, Devin | Codex |
| --- | --- | --- |
| Make a small, reversible change | `/rite-quick fix the CSV header typo` | `$rite-quick fix the CSV header typo` |
| Build a new feature or risky behavior | `/rite-spec add-csv-export` | `$rite-spec add-csv-export` |
| Resume an active feature | `/rite-status` | `$rite-status` |
| Baseline an existing codebase | `/rite-adopt` | `$rite-adopt` |
| Run the whole lifecycle unattended | `/rite-autocomplete` | `$rite-autocomplete` |
**3. Follow the next recorded step.** `/rite-status` reads the active workspace
and reports the phase, open questions, evidence, and the next command.
> [!TIP]
> The shortest path is Spec, Build, Prove. Clarify and Vet still run, but
> they ask nothing when the contract is already complete.
## The lifecycle
In the default HITL mode, you run each command yourself, in this order. Each
one stops when its phase is done and records the next step in the workspace.
If you lose track, `/rite-status` prints the next command.
```text
/rite-spec add-csv-export # 1 answer its questions; writes spec.md
/rite-clarify # 2 asks nothing when the spec is complete
/rite-temper # optional: big or risky features only
/rite-define # 3 plan + vertical slices in tasks.md
/rite-vet # 4 plan review; nothing builds before READY
/rite-build # 5 builds slice 1, then stops
/rite-build # 5 builds slice 2; repeat until every slice is done
/rite-prove # 6 once, after the last slice
/rite-polish # 7 cleans code and touched UI
/rite-review # 8 checks the diff against spec and standards
/rite-seal # 9 GO or NO-GO; Git untouched
/rite-ship # 10 shows the exact Git plan, then waits for you to type GO
```
Every command has four equivalent forms: `/rite ` and `/rite-` in
Claude Code, omp, pi, and Devin CLI, and `$rite ` and `$rite-` in
Codex. On pi, commands run as prompt templates under `.pi/prompts`; on omp,
as command stubs under `.omp/commands`. On both, `/skill:rite-` is
equivalent.
### Shape (steps 1 to 4): agree on what "done" means
| # | Command | What it does | Leaves behind |
| :-: | --- | --- | --- |
| **1** | [`/rite-spec `](pack/.claude/skills/rite-spec/SKILL.md) | Inspects the request and the codebase, asks about product gaps, and writes a lossless contract with an explicit capability impact. | `spec.md` |
| **2** | [`/rite-clarify`](pack/.claude/skills/rite-clarify/SKILL.md) | Checks the whole feature for missing decisions. Mandatory, but asks nothing when everything is clear. | `decision-coverage.md` |
| opt. | [`/rite-temper`](pack/.claude/skills/rite-temper/SKILL.md) | Challenges scope, premise, and failure modes with a pre-mortem. Skip it for small work; Autocomplete always runs it. | `strategy.md` |
| **3** | [`/rite-define`](pack/.claude/skills/rite-define/SKILL.md) | Turns the approved spec into architecture, traceability, and vertical task slices. | `plan.md`, `tasks.md` |
| **4** | [`/rite-vet`](pack/.claude/skills/rite-vet/SKILL.md) | Reviews every plan before code, with review depth scaled to risk. Build cannot start until Vet passes. | `eng-review.md`, `test-plan.md` |
### Build (step 5): one slice per run
| # | Command | What it does | Leaves behind |
| :-: | --- | --- | --- |
| **5** | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | Implements and verifies the next slice, then stops. Run it again until every slice in `tasks.md` is built. With `.devrites/AFK`, it may chain low-risk slices under a cap. | `touched-files.md`, `evidence.md` |
| if needed | [`/rite-plan repair`](pack/.claude/skills/rite-plan/SKILL.md) | The plan turned out wrong: reslices, reorders, or unblocks it. Run `/rite-vet` again, then keep building. | `plan.md`, `tasks.md` |
| if needed | [`/rite-converge`](pack/.claude/skills/rite-converge/SKILL.md) | Resuming a half-built feature: compares live code with recorded intent, adds missing slices, and sends the plan back to Vet. | `convergence-assessment.md`, `tasks.md` |
### Prove (steps 6 to 8): once, after the last slice
| # | Command | What it does | Leaves behind |
| :-: | --- | --- | --- |
| **6** | [`/rite-prove`](pack/.claude/skills/rite-prove/SKILL.md) | Runs positive, discriminating tests plus build, runtime, and UI checks, then binds the evidence to the candidate digest. | `evidence.md`, `browser-evidence.md` |
| **7** | [`/rite-polish`](pack/.claude/skills/rite-polish/SKILL.md) | Cleans up the candidate, normalizes touched UI, completes durable rollups, and refreshes affected proof. | `polish-report.md` |
| **8** | [`/rite-review`](pack/.claude/skills/rite-review/SKILL.md) | Reviews the closed candidate against its spec and engineering standards. | `review.md` |
### Ship (steps 9 and 10): you decide
| # | Command | What it does | Leaves behind |
| :-: | --- | --- | --- |
| **9** | [`/rite-seal`](pack/.claude/skills/rite-seal/SKILL.md) | Rechecks candidate-bound evidence and writes the final `GO` or `NO-GO` without changing Git. | `seal.md` |
| **10** | [`/rite-ship`](pack/.claude/skills/rite-ship/SKILL.md) | Runs a read-only preflight and shows the exact Git plan. After you type a fresh literal `GO`, it commits, runs any approved push, tag, or PR action, and archives the workspace. | `ship.md`, `archive//` |
Other routes and utilities
| Command | Use it to… |
| --- | --- |
| [`/rite`](pack/.claude/skills/rite/SKILL.md) | Show the command menu, or route a verb. |
| [`/rite-quick`](pack/.claude/skills/rite-quick/SKILL.md) | Ship a small, reversible change with a compact contract, focused proof, and scope review. Escalates to `/rite-spec` when the work stops being small. |
| [`/rite-fast`](pack/.claude/skills/rite-fast/SKILL.md) | Take mid-size work through one spec-and-plan step with your answers, up to ten slices, one completeness check, review, polish, and proof. No gate after each slice; explicit invocation only. |
| [`/rite-autocomplete`](pack/.claude/skills/rite-autocomplete/SKILL.md) | Run the reversible lifecycle unattended and stop at Seal `GO`. With `--ship`, continue through Ship preflight and wait for your literal `GO`. |
| [`/rite-adopt`](pack/.claude/skills/rite-adopt/SKILL.md) | Reverse-engineer current behavior of an existing codebase into a baseline workspace. |
| [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) | Reconcile an older active workspace with current contracts. Routes only evidence-backed defects to their phase owners. |
| [`/rite-status`](pack/.claude/skills/rite-status/SKILL.md) | Report phase, active slice, next action, evidence, open questions, and risks. Read-only. |
| [`/rite-resolve ""`](pack/.claude/skills/rite-resolve/SKILL.md) | Answer, drop, or batch-resolve open questions. |
| [`/rite-handoff`](pack/.claude/skills/rite-handoff/SKILL.md) | Sync chat-only context into `.devrites/` and write a fresh-agent handoff. |
| [`/rite-frame`](pack/.claude/skills/rite-frame/SKILL.md) | Frame an underspecified ask before coding, then audit the diff. |
| [`/rite-pressure-test`](pack/.claude/skills/rite-pressure-test/SKILL.md) | Explore three to five radically different approaches to a rough idea before Spec. |
| [`/rite-prototype`](pack/.claude/skills/rite-prototype/SKILL.md) | Build a throwaway prototype to answer one logic or UI question. |
| [`/rite-pov`](pack/.claude/skills/rite-pov/SKILL.md) | Get a project-grounded verdict on a library, platform, CVE, or pattern. |
| [`/rite-zoom-out`](pack/.claude/skills/rite-zoom-out/SKILL.md) | Map unfamiliar code: modules, callers, callees, and relevant decisions. |
| [`/rite-explain`](pack/.claude/skills/rite-explain/SKILL.md) | Learn one concept, diff, or recent change, with an optional check-in. |
| [`/rite-dogfood`](pack/.claude/skills/rite-dogfood/SKILL.md) | Run explicit browser QA for the active feature or branch. |
| [`/rite-harness`](pack/.claude/skills/rite-harness/SKILL.md) | Generate or maintain a project-local verify skill that launches, drives, and proves the app. |
| [`/rite-pr-feedback`](pack/.claude/skills/rite-pr-feedback/SKILL.md) | Resolve GitHub PR review feedback. |
| [`/rite-watch-pr`](pack/.claude/skills/rite-watch-pr/SKILL.md) | Watch one PR and its CI state without mutating anything. |
| [`/rite-learn`](pack/.claude/skills/rite-learn/SKILL.md) | Turn recurring cross-feature evidence into durable project guidance. |
| [`/rite-customize`](pack/.claude/skills/rite-customize/SKILL.md) | Customize a project instruction, skill, agent, plugin, or legacy import. |
| [`/rite-doctor`](pack/.claude/skills/rite-doctor/SKILL.md) | Check the DevRites install, pack, or host configuration. |
| [`/overhaul`](pack/.claude/skills/overhaul/SKILL.md) | Run an approval-gated overhaul of a project, PR, or branch. Works without a DevRites workspace; explicit invocation only. |
The [command map](docs/command-map.md) covers every command, trigger, input,
and output. The [worked examples](docs/usage.md) cover normal features, plan
drift, UI work, backend work, and mid-flight handoffs.
## What DevRites records
Each feature gets a directory under `.devrites/work//`. Shipped
workspaces move intact to `.devrites/archive//`, so future work can
inspect the original decisions and proof.
```text
.devrites/
├── ACTIVE active feature slug
├── AFK optional unattended-mode configuration
├── principles.md project rules that gate the workflow
├── specs/ living structured capabilities
├── work//
│ ├── brief.md spec.md decision-coverage.md
│ ├── architecture.md plan.md tasks.md eng-review.md test-plan.md
│ ├── state.md decisions.md questions.md traceability.md
│ ├── evidence.md touched-files.md strict project-candidate manifest
│ └── review.md seal.md ship.md
└── archive//
```
`.devrites/CHECKPOINT` is a reserved path, not a commit gate. Some phases add
focused artifacts such as `strategy.md`, `design-brief.md`,
`browser-evidence.md`, `polish-report.md`, `drift.md`, or `handoff.md`. See the
[workspace contract](docs/engine/workspace-schema.md) for the full state model
and [candidate integrity](docs/candidate-integrity.md) for the Build-to-Ship
content binding.
## Safety rules
- **Settle before code.** Spec and Clarify settle the behavior contract. Define
and Vet settle the implementation path before Build starts. The active skill
and exact native reviewers judge `CLEAR`, `READY`, traceability, and test
quality; the engine checks phase-relative structure and, after Vet, the exact
Build-input binding.
- **Bound every Build dispatch.** Before each writer dispatch, the root names
the exact project-relative paths in the task. After return, it rejects any
extra path in `git diff --name-only`, reviews test integrity, and runs
repository proof.
- **Classify drift before routing.** The Spec Drift Guard records a mismatch in
`drift.md`. Build handles objective failures with bounded recovery, uses
`/rite-plan repair` only when the durable plan is wrong, and asks you only
for a real product or risk decision.
- **Prove claims.** Skipped, zero-test, assertion-free, tautological,
unexecuted, or exit-only results do not prove behavior. Static gates prove
only their static criterion. A screenshot path by itself is not proof.
- **Separate the decision from the action.** Seal makes the release decision.
Ship performs Git actions only after the seal passes and you type `GO`.
- **Stay inside the feature.** Review, security, simplification, and polish do
not expand into unrelated project cleanup.
Validated project principles and nearest-scope repository instructions govern
product and technical choices. They do not grant permission or waive DevRites
safety, source-writing, or evidence gates. A feature can record a deliberate,
scoped exception instead of silently ignoring a principle. The canonical order
is in [`core.md` § Precedence](pack/.claude/skills/devrites-lib/reference/standards/core.md#precedence).
## HITL and AFK
| | **HITL** (default) | **AFK** (opt-in) |
| --- | --- | --- |
| Turn on | Nothing to do. | Create `.devrites/AFK`. Delete it to return to HITL. |
| Decisions | Ranked options; your answer is recorded in the workspace. | Permitted gates pick the recommended option and continue. |
| Build | One vertical slice per run. | Chains low-risk slices within `max_slices` and pause rules. |
| Unanswered question | Stays in `questions.md`; answer later with `/rite-resolve`. | Pauses for product, scope, policy, irreversible risk, or human-only access. |
| Git | Ship always waits for a fresh literal `GO`. | Same. Local WIP checkpoint commits stay local unless Ship's disclosed plan includes an approved remote action. |
```yaml
# .devrites/AFK
max_slices: 10
max_agents: 32
max_minutes: 120
max_review_queue: 8
allow_gates: [advisory]
```
The workflow treats this file as configuration and never rewrites it.
`max_slices` seeds the remaining budget in the feature's `state.md`; the root
charges it once per green slice and stops at zero. Unattended slice work also
requires valid `max_agents`, `max_minutes`, and `max_review_queue`; a missing
or malformed value fails closed.
`/rite-autocomplete` also auto-resolves blocking questions that already name a
ranked recommended option. Escalating, irreversible-risk, access, and
no-recommendation questions still pause. When bounded recovery runs out,
agents record a technical blocker instead of asking you. The full contract is
in [`afk-hitl.md`](pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md).
`devrites-engine frontier [slug]` reports the recorded sequence across live and
archived workspaces without changing `ACTIVE`, creating workspaces, or launching
agents. It distinguishes preparation, repair, waiting, and completed work, and
prints an explicit mixed-workspace selection command when available. A source-local
`parallel select --from-plan` exposes that frontier but still selects only its own
workspace unless `--workspaces` is supplied. Native Autocomplete owns preparation
and semantic admission; the report is neither Build readiness nor Ship approval.
See the [frontier contract](docs/cli.md#sequence-frontier).
## Install, update, and remove
```bash
npx devrites@latest # install in the current project
npx devrites@latest --target /path/to/project
npx devrites@latest --dry-run # preview file operations
npx devrites@latest update # update engine and pack
npx devrites@latest update --check
devrites-engine update # same, from an installed project
npx devrites@latest uninstall
npx devrites@latest uninstall --keep-binary
```
On Windows, use `npx devrites@latest uninstall` or the Bash `uninstall.sh`
launcher to remove the shared engine binary. These launchers run a private
temporary copy so Windows can delete the original installed executable.
Direct `devrites-engine uninstall` cannot delete its own running image and
refuses before changing project files; use the launcher or `--keep-binary`.
Run `npx devrites@latest --help` for common flags and
`npx devrites@latest --help` for command-specific flags.
Install flags
| Flag | Effect |
| --- | --- |
| `--target DIR` | Use another project directory. |
| `--dry-run` | Show planned file operations without changing anything. |
| `--force` | Replace or remove foreign or customized managed files. The installer still rejects symlinks and path escapes. |
| `--no-codex` | Skip `.agents`, `.codex`, and the Codex `AGENTS.md` block. |
| `--no-omp` | Skip `.omp` skills, agents, and command stubs. |
| `--no-pi` | Skip `.pi` skills, agents, prompt commands, and the pi `AGENTS.md` block. |
| `--no-devin` | Skip `.devin` skills, agents, and the Devin `AGENTS.md` block. |
| `--no-dsh` | Skip `.dsh` skills, named presets, permission guard, and the DSH `AGENTS.md` block. |
| `--no-agents` | Skip hook-free native specialist profiles. |
| `--no-skills` | Skip skills and their bundled standards. |
| `--no-binary` | Do not keep the shared `devrites-engine` binary in a user or system bin directory. On `uninstall`, keep the existing binary. |
| `--short-aliases=all` | Add `/define`, `/build`, `/prove`, and `/seal` aliases. |
Install without Node.js (verified Bash bootstrap)
Download the release-owned installer and its checksum before executing it. It
needs `curl`, `gzip`, and `tar`.
```bash
bootstrap_dir="$(mktemp -d)"
project_dir="$PWD"
(
set -e
trap 'rm -rf "$bootstrap_dir"' EXIT HUP INT TERM
cd "$bootstrap_dir"
release=https://github.com/ViktorsBaikers/DevRites/releases/latest/download
curl -q -fL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 60 --max-filesize 1048576 "$release/install.sh" | head -c 1048577 > install.sh
install_status="${PIPESTATUS[0]}"
[ "$(wc -c < install.sh)" -le 1048576 ] || { echo 'error: install.sh exceeds 1 MiB' >&2; exit 1; }
[ "$install_status" -eq 0 ] || { echo 'error: install.sh download failed' >&2; exit 1; }
curl -q -fL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 30 --max-filesize 4096 "$release/install.sh.sha256" | head -c 4097 > install.sh.sha256
sidecar_status="${PIPESTATUS[0]}"
[ "$(wc -c < install.sh.sha256)" -le 4096 ] || { echo 'error: install.sh.sha256 exceeds 4 KiB' >&2; exit 1; }
[ "$sidecar_status" -eq 0 ] || { echo 'error: install.sh.sha256 download failed' >&2; exit 1; }
want="$(awk '
NF == 0 { next }
{ records++ }
NF == 2 && length($1) == 64 && $1 ~ /^[0-9A-Fa-f]+$/ && $2 == "install.sh" { valid++; hash=tolower($1) }
END { if (records == 1 && valid == 1) print hash; else exit 1 }
' install.sh.sha256)"
if command -v shasum >/dev/null 2>&1; then
got="$(shasum -a 256 install.sh | awk '{print $1}')"
elif command -v sha256sum >/dev/null 2>&1; then
got="$(sha256sum install.sh | awk '{print $1}')"
else
echo 'error: shasum or sha256sum is required' >&2
exit 1
fi
[ "$got" = "$want" ] || { echo 'error: install.sh checksum mismatch' >&2; exit 1; }
# Choose one Node-free operation:
bash ./install.sh --target "$project_dir" # install into the directory you ran this from
# bash ./install.sh --dry-run --target "$project_dir"
# bash ./install.sh update --target "$project_dir"
# bash ./install.sh uninstall --target "$project_dir"
)
```
To pin a named release, replace `latest/download` with
`download/v` and run the chosen operation with
`DEVRITES_REF=v`. Existing local or extracted `install.sh`,
`update.sh`, and `uninstall.sh` invocations remain compatible. The
exact-release acquisition guarantee begins with the verified release
`install.sh`; mutable default-branch scripts are not an installation boundary.
How install, update, and uninstall protect your files
The installer records every managed project file and its SHA-256 in
`.claude/devrites.manifest`. Before an update or uninstall changes anything, it
checks every managed path. It preserves customized files and tells you to retry
with `--force`; legacy manifests without hashes also require `--force`.
`--force --dry-run` lists the exact destructive actions. Every settings and
marker merge is checked before the first write, so a rejected merge (such as a
Codex config that already sets top-level `default_permissions`) leaves the project untouched.
Unmerges receive the same preflight: malformed settings or legacy hooks JSON
blocks uninstall and dropped-host pruning, including dry runs, before writes.
Existing files retain their permission bits. Claude permission ownership is
recorded before settings replacement, so interrupted merges retain the records
needed to remove installer-added grants on retry and uninstall.
User-pinned aliases keep their recorded ownership hashes; refreshing does not
silently adopt local edits. Shared-config marker collisions fail before writes.
Legacy hook cleanup matches known shipped commands, not user commands that merely
mention DevRites.
Marker-merged files keep user content outside the DevRites block, and
`.devrites/` runtime state stays in place. `update` reuses the install flags
recorded in the manifest; flags you pass explicitly win and are recorded. The installer refuses symlinks, junctions, and paths that
escape the target.
The optional shared `devrites-engine` binary is the only artifact installed
outside the project. Before replacement, the staged release binary must report
the requested version; after installation, the binary at its final path must
report it again in a new process. The selected binary is installed after merge
preflight but before project payload and version publication, so binary failure
leaves an ordinary update retry possible. The installer keeps a backup until the
second check passes and restores it on failure. If restoration also fails, it
retains the backup and reports its recovery path.
`devrites-engine update` resolves the latest stable release, acquires its
bundle and platform binary, and hands local paths to the downloaded engine, so
the candidate engine validates its own payload before replacing the installed
pack and binary. `update --check` compares versions without downloading
release assets. If an older engine reports `missing codex/hooks.json` or asks
for `--source-dir`, use the npm or verified shell route once to reach a
release with the self-contained updater.
GitHub release API authentication uses `GH_TOKEN`, then `GITHUB_TOKEN`, then an
optional, bounded, noninteractive `gh auth token --hostname github.com` lookup.
GitHub CLI is not required. Credentials go only to the exact GitHub API origin,
never release assets or off-origin redirects. Explicit invalid credentials fail
instead of silently falling back to another identity. For a headless machine,
run `gh auth login --hostname github.com --web` and complete its device-code flow
in a browser on another device. Do not paste credentials into commands, logs, or
support reports. `--force` controls managed-file replacement; it does not bypass
GitHub authentication or rate limits. If authentication does not clear a rate
limit, wait before retrying.
`/rite-upgrade` is the separate, preservation-first route for reconciling an
unfinished workspace; it never migrates cursor format or invents historical
proof. `devrites-engine migrate` owns deterministic v5 schema normalization.
See the [CLI contract](docs/cli.md) and
[ADR-0029](docs/adr/0029-v5-workspace-schema-and-native-migration.md).
Every release asset is checked against its exact-filename SHA-256 sidecar
before it is decompressed, extracted, or executed. The installers do not need
GitHub CLI and do not run `gh attestation verify`.
Release binaries and installers also ship with build-provenance attestations.
The `.sha256` sidecar is fetched from the same origin as the artifact, so it is
a corruption check, not a provenance one. To check provenance yourself, run
`gh attestation verify -R ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`
on the downloaded file before it runs. This step is optional. Pin the signer
workflow, because valid provenance shows where a build ran but does not show
that the intended publishing step produced it. See
[docs/release.md](docs/release.md).
## Hosts
For DSH, launch `npx @deepseek-ai/dsh web --patch .dsh/cordis.patch.yml`
and select the **DevRites** agent preset before starting a workflow. See the
[DSH integration guide](docs/dsh.md) for permissions, dispatch, and result collection.
| Host | Skills | Agents | Also installs | Invoke |
| --- | --- | --- | --- | --- |
| **Claude Code** | `.claude/skills/` | `.claude/agents/` | Native root permissions merged into `.claude/settings.json` | `/rite-spec` |
| **Codex** | `.agents/skills/` | `.codex/agents/` | Permissions in `.codex/config.toml`, marked block in `AGENTS.md` | `$rite-spec` or `/skills` |
| **omp** | `.omp/skills/` | `.omp/agents/` | Command stubs in `.omp/commands/`; `.omp/config.yml` hiding duplicate DevRites skills (only if absent) | `/rite-spec` or `/skill:rite-spec` |
| **pi** | `.pi/skills/` | `.pi/agents/` | Prompt commands in `.pi/prompts/`, marked block in `AGENTS.md`; with Codex, `.pi/settings.json` skipping the `.agents/skills` copies (only if absent) | `/rite-spec` or `/skill:rite-spec` |
| **Devin CLI** | `.devin/skills/` | `.devin/agents/` | Marked block in `AGENTS.md` | `/rite-spec` |
| **DSH** | `.dsh/skills/` | Named native agent presets; profiles in `.dsh/agents/` | `.dsh/cordis.patch.yml`, role permission guard, marked block in `AGENTS.md` | `/rite-spec` in the DevRites preset |
On every host, among the lifecycle `devrites-*` specialists only
`devrites-slice-wright` is writable and the rest are read-only and hook-free;
the shipped profiles are the full role-to-permission map, and `/rite-doctor`
step 3 checks them. Existing
settings and user content stay in place; when `.omp/config.yml` or
`.pi/settings.json` already exists, the installer leaves it unchanged and
prints the setting to add. Once you edit one the installer created, it is
yours: update, uninstall, and `--force` leave it in place. On Devin CLI, dispatch goes through
`run_subagent` with the exact `devrites-` profile, and a missing profile
stops for HITL instead of substituting `subagent_general`. Profiles load when a
session starts, so reopen the project after installing. pi-subagents refuses a
child whose `tools:` names a tool it cannot load, so pi agents list only Pi's
built-in tools; grant extension tools on one machine with
`subagents.agentOverrides..tools` in Pi settings.
DevRites is installed through npm or the Bash bootstrap. It is not distributed
through Claude Code or Codex plugin stores.
## Skills and agents
The pack ships 47 skills: 36 public and 11 internal. The public surface
contains the `rite` menu, 33 `rite-*` workflows and utilities, and the
standalone, explicit-only `/overhaul`. Ten `devrites-*` specialists load when a
matching task needs them; `devrites-lib` carries the shared contracts and
engineering standards.
Seventeen fresh-context agent profiles ship with the pack: sixteen read-only
roles plus `devrites-slice-wright`, the sole source and test writer. Codex,
omp, pi, and Devin generate the same one-writer, sixteen-reader split.
`/overhaul` adds eight `overhaul-*` agents that only it dispatches; they keep
every tool ([ADR-0031](docs/adr/0031-overhaul-agents-keep-every-tool.md)).
`/rite-fast` adds four `fast-*` agents that only it dispatches: three read-only
roles and `fast-builder`, its own writer ([ADR-0033](docs/adr/0033-rite-fast-own-agents.md)).
The [skills catalogue](docs/skills.md) lists every skill and agent. The
[flow diagrams](docs/flow.md) show routing, reviewer fan-out, and namespace
boundaries.
## Engineering standards and UI work
Stack-agnostic standards live under
`.claude/skills/devrites-lib/reference/standards/`. Lifecycle skills load the
small core first, then only the standards they need. Nearest project
instructions override generic advice, and ratified `.devrites/principles.md`
are gating invariants. The
[standards index](pack/.claude/skills/devrites-lib/reference/standards/README.md)
maps each rule file to the phases that use it.
For UI work, Spec records the visual direction and required states in
`design-brief.md`, Build follows the project's existing design system, and
Prove collects runtime and browser evidence. The guidance checks WCAG 2.2 AA
and, when performance is measurable, targets LCP ≤ 2.5 s, INP ≤ 200 ms, and
CLS ≤ 0.1. Full-stack work starts with the API and data contract, then builds
a vertical slice through the UI.
DevRites works without extra tools. When available,
[codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) answers
structural questions (callers, blast radius, diff impact),
[ego-lite](https://github.com/citrolabs/ego-lite), browser-harness, or
[Playwright MCP](https://github.com/microsoft/playwright-mcp) can collect
browser evidence (tried in that order), and Chrome DevTools MCP can add Lighthouse and performance
traces. DevRites detects these tools but does not install them.
## Security model
- Installed host artifacts stay in the project. Use `--no-binary` or
`DEVRITES_NO_BINARY=1` to avoid keeping a shared binary outside it.
- npm, Bash, and `devrites-engine update` all require release assets that
match their SHA-256 sidecars. Build-provenance attestations can be checked
manually with `gh attestation verify` (see
[Install, update, and remove](#install-update-and-remove)). Remote fetches use HTTPS at every redirect hop, are bounded in size,
and never fall back to an unchecked raw file, source archive, tag, or default
branch.
- Install, update, and uninstall do not inspect target-project Git. Retained
safety operations such as `secret-scan --staged` read only the exact index
and staged blobs they validate.
- Production Git calls strip `GIT_*` variables that could retarget them. Seal
binds proof, review, and verdict to the strict project candidate rather than
to modification times
([ADR-0026](docs/adr/0026-content-bound-proof-and-bounded-inputs.md)).
- The installer never sets a Claude `permissions.defaultMode`; it keeps yours, and an
update removes the `plan` mode older DevRites versions wrote. Skills use
networked research only through host tools you invoke or configure.
Read [`SECURITY.md`](SECURITY.md) for the threat model, managed deployment
guidance, and private reporting instructions.
## Contributing
```text
bin/ npm CLI shim
engine/ Go control plane and tests
pack/.claude/ canonical skills, agents, permissions, and standards
pack/generated/ generated host payloads; do not edit by hand
scripts/ validation, generation, install, and release tooling
tests/ repository-level shell tests
docs/ architecture, usage, command, and contributor guides
evals/ routing and behavioral evaluation fixtures
```
```bash
npm install
npm run validate
npm test
(cd engine && go test ./... -count=1)
```
Native Windows launcher integration tests also require Node and Git for Windows
(including Git Bash). They exercise the real installed engine through both launchers.
Canonical pack changes belong in `pack/.claude/`. Rebuild host payloads with
`bash scripts/build-host-artifacts.sh` instead of editing `pack/generated/`.
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and
review requirements, and the [code of conduct](CODE_OF_CONDUCT.md) before
opening a change. Maintainer ownership is in [`CODEOWNERS`](CODEOWNERS);
third-party notices are in [`NOTICE.md`](NOTICE.md).
All documentation
- [Quick reference](docs/quick-reference.md)
- [Worked examples](docs/usage.md)
- [Command map](docs/command-map.md)
- [Skills catalogue](docs/skills.md)
- [Architecture](docs/architecture.md)
- [Lifecycle diagrams](docs/flow.md)
- [Candidate integrity](docs/candidate-integrity.md)
- [Engine CLI](docs/cli.md)
- [Release process](docs/release.md)
- [Nine-source workflow benchmark snapshot (2026-08-01; historical, non-authoritative)](docs/upstream-workflow-benchmark-2026-08-01.md)
- [Markdown instruction upgrade snapshot (2026-08-02; historical, non-authoritative)](docs/markdown-instruction-upgrade-2026-08-02.md)
- [ADR-0026: content-bound proof and bounded inputs](docs/adr/0026-content-bound-proof-and-bounded-inputs.md)
- [Changelog](CHANGELOG.md)
- [Releases](https://github.com/ViktorsBaikers/DevRites/releases)
## License
DevRites is source-available software for personal use with Claude Code and
Codex. Distribution, modified distribution, fork mirrors, and commercial or
organizational use require approval. Read [`LICENSE`](LICENSE) for the full
terms.
Spec → proof → people → better software.