devrites

DevRites

DevRites is a repository-local workflow for building software with Claude Code or Codex. It turns a feature request into a spec, a sliced plan, working code, recorded proof, a release decision, and an explicit ship step.

The work lives under .devrites/, not in chat history. A later session or a different agent can read the same plan, decisions, state, and evidence before it continues.

The core path is:

SPEC -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP

Seal decides whether the feature is ready without changing git. Ship owns the final commit, push, and tag, and it requires a typed GO confirmation. Unattended runs may create local WIP checkpoint commits along the way, but only Ship collapses and pushes them.

Status: v3.0.6: see CHANGELOG.md for release notes.

Quick start

1. Install DevRites

Run this from the root of your project. Node.js 18 or later is required.

npx devrites@latest

The installer adds project-local support for Claude Code and Codex. It does not write skills, agents, or hooks to ~/.claude or ~/.codex.

2. Start a feature

In Claude Code:

/rite-spec add-csv-export

In Codex:

$rite-spec add-csv-export

DevRites investigates the repository, asks about gaps, and writes the feature spec under .devrites/work/add-csv-export/. For an existing codebase that needs an onboarding pass first, use /rite-adopt in Claude Code or $rite-adopt in Codex.

3. Follow the next recorded step

Use /rite-status in Claude Code or $rite-status in Codex. Status reads the active workspace and reports the current phase, open questions, evidence, and next command.

How the lifecycle works

Claude Code supports both /rite <verb> and /rite-<verb>. Codex uses the same forms with $: $rite <verb> and $rite-<verb>. The menu and direct forms run the same skill.

Stage	Direct command	What happens
Spec	/rite-spec <feature>	Investigates the request and codebase, closes product gaps, and writes spec.md.
Define	/rite-define	Turns the spec into architecture, a plan, traceability, and vertical task slices.
Vet	/rite-vet	Reviews every plan before implementation. The depth scales with the risk.
Build	/rite-build	Implements and verifies exactly one slice, then stops. Repeat for each slice.
Prove	/rite-prove	Runs the completed feature's tests, build, runtime checks, and browser proof when UI is involved.
Polish	/rite-polish	Cleans up the touched code and normalizes the UI when needed.
Review	/rite-review	Runs feature-scoped review across the relevant engineering axes.
Seal	/rite-seal	Produces a final GO or NO-GO decision without changing git.
Ship	/rite-ship	On GO, asks for typed confirmation, performs the approved git actions, and archives the workspace.

Some work needs a different route:

• /rite-quick handles a small, reversible change without creating a full feature workspace.
• /rite-temper challenges the scope and failure modes of a larger spec before Define.
• /rite-converge compares a resumed, adopted, or stalled feature with the live code and adds the missing work as new slices.
• /rite-autocomplete runs the lifecycle unattended. With --ship, it auto-confirms the final typed GO; without that flag, it stops and waits for you.
• /rite shows the command menu.

The command map covers every command, trigger, input, and output. The worked examples show normal features, plan drift, UI work, backend work, and mid-flight handoffs.

What DevRites records

Each feature gets a directory under .devrites/work/<slug>/. Shipped workspaces move intact to .devrites/archive/<slug>/ so future work can inspect the original decisions and proof.

.devrites/
  ACTIVE                 # active feature slug
  AFK                    # optional unattended-mode configuration
  principles.md          # project rules that gate the workflow
  conventions.md         # observed project patterns
  learnings.md           # recurring lessons and known false positives
  work/<slug>/
    brief.md
    spec.md
    architecture.md
    plan.md
    tasks.md
    state.md
    decisions.md
    questions.md
    traceability.md
    evidence.md
    review.md
    seal.md
    ship.md
  archive/<slug>/

Some phases add focused artifacts such as strategy.md, test-plan.md, design-brief.md, browser-evidence.md, polish-report.md, drift.md, or handoff.md. See the workspace contract for the full state model.

Safety rules

• Plan before code. Spec, Define, and Vet settle the intended behavior and implementation path before Build starts.
• Build one slice. /rite-build implements one vertical slice and records its proof before returning control.
• Stop on drift. If implementation no longer matches the plan, the Spec Drift Guard records the mismatch in drift.md and routes through /rite-plan repair.
• Prove claims. Tests, commands, output, and opened screenshots support completion claims. A screenshot path by itself is not proof.
• Separate the decision from the action. Seal makes the release decision. Ship performs the final 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.

Project principles in .devrites/principles.md take precedence over learned conventions and the bundled engineering standards. A feature can record a deliberate exception instead of silently ignoring a project rule.

HITL and AFK modes

HITL is the default

When DevRites needs a decision, it presents ranked options, records the chosen answer in the workspace, and continues. If the current turn must stop, the question remains in questions.md; answer it later with /rite-resolve <qid> "<answer>". Codex uses the equivalent $rite-resolve form.

AFK runs the safe part unattended

Create .devrites/AFK to let permitted gates select their recommended option and continue:

max_slices: 10
allow_gates: [advisory]

The workflow treats this file as configuration and never rewrites it. max_slices seeds the remaining budget in the active feature's state.md; the engine decrements that state after each built slice. Delete .devrites/AFK to return to HITL.

AFK still pauses for blocking or escalating gates, destructive migrations, auth or authorization changes, public API breaks, external service contract changes, filesystem destruction outside the workspace, and red tests, types, or lint. The full pause and gate contract is in afk-hitl.md.

Install, update, and remove

npm

# Install in the current project
npx devrites@latest

# Install elsewhere or preview the changes
npx devrites@latest --target /path/to/project
npx devrites@latest --dry-run

# Update or remove an existing installation
npx devrites@latest update
npx devrites@latest uninstall

Useful install flags:

Flag	Effect
--target DIR	Use another project directory.
--dry-run	Show planned file operations without changing anything.
--force	Replace conflicting files that DevRites does not own.
--no-codex	Skip .agents, .codex, and AGENTS.md integration.
--no-agents	Skip the review agents.
--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.
--short-aliases=all	Add /define, /build, /prove, and /seal aliases.

Run npx devrites@latest --help for the full option list.

Bash bootstrap

If Node.js is not available, use the bootstrap script. It needs curl and tar.

# Install the latest release in the current project
curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash

# Install in another project
curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash -s -- --target /path/to/project

# Preview without writing files
curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash -s -- --dry-run

The installer records every managed project file in .claude/devrites.manifest. Update and uninstall use that manifest, preserve .devrites/, and avoid removing files they do not own. The optional shared devrites-engine binary is the only artifact that may be installed outside the project.

Claude Code and Codex integration

Claude Code receives skills under .claude/skills/, agents under .claude/agents/, and DevRites hooks merged into .claude/settings.json. Existing settings remain in place.

Codex receives the same skills under .agents/skills/, custom agents under .codex/agents/, hooks under .codex/hooks.json, and a marked guidance block in AGENTS.md. Existing AGENTS.md content remains in place. Codex users invoke skills with $rite, $rite-spec, or /skills and should review project hooks through /hooks.

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 42 skills: 30 public and 12 internal. The public surface contains the rite menu and 29 rite-* workflows and utilities. Eleven devrites-* specialists load when a matching task needs them; devrites-lib carries the shared contracts and engineering standards.

Fourteen agents ship with the pack. Thirteen are read-only reviewers or analysts, including devrites-retrospector, which reads the shipped archive. devrites-slice-wright is the only agent allowed to edit a feature slice.

The authoritative skills catalogue lists every skill and agent. The flow diagrams show routing, reviewer fan-out, and namespace boundaries.

Engineering standards and UI work

The stack-agnostic standards live under .claude/skills/devrites-lib/reference/standards/. Every workflow loads the small core first, then only the standards needed for that phase. Project conventions override generic advice, and .devrites/principles.md overrides both. The standards index 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, while Prove collects runtime and browser evidence. The guidance checks WCAG 2.2 AA and, when performance is measurable, targets LCP at or below 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 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. If available, codegraph or graphify can answer structural questions, and Playwright MCP can collect browser evidence. 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. The npm shim prefers an explicitly configured engine or a local engine/devrites-engine, can download a checksummed release binary, can build a temporary engine from the local Go source, and finally falls back to an existing devrites-engine on PATH. Use --no-binary or DEVRITES_NO_BINARY=1 if you do not want the installer to keep the shared binary outside the project.

Workflow state is read through the engine rather than shell injection. The installer never writes defaultMode: bypassPermissions. Skills use networked research only through host tools you invoke or configure.

Read SECURITY.md for the threat model, managed deployment guidance, and private reporting instructions.

Repository layout

bin/               npm CLI shim
engine/            Go control plane and tests
pack/.claude/      canonical skills, agents, hooks, 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

For local development:

npm install
npm run validate
npm test
(cd engine && go test ./... -count=1)

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 for the development workflow and review requirements.

Documentation

• Quick reference
• Worked examples
• Command map
• Skills catalogue
• Architecture
• Lifecycle diagrams
• Engine CLI
• Release process
• Changelog
• Releases

Community and license

Please read the contribution guide and code of conduct before opening a change. Maintainer ownership is documented in CODEOWNERS, and third-party notices are in NOTICE.md.

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 for the full terms.