How DevArch Works

The pieces

DevArch is a methodology and tooling layer that runs inside Claude Code. There is no runtime dependency, no service, and no library to import. What gets installed is:

A ruleset — one global file, ~/.devarch/DEVARCH.md. Each project's CLAUDE.md imports it with a single line. The ruleset tells Claude when to do things: when to plan, when to verify, when to summarize, when to stop and ask.
Agents — subagent definitions Claude Code runs on specific triggers: a pre-session auditor, a session planner, a mutation verifier, a work-summary writer, commit orchestrators, and several more.
Hooks and gates — shell scripts wired into Claude Code's lifecycle events. These are mechanical, not advisory: the session-start hook injects prior context before the first prompt, and the planning gate blocks file edits at the tool level until a plan is approved.
Commands — /devarch:* skills you invoke deliberately: recap, standup, finalize, brainstorm, and the review commands covered below.
A CLI — devarch handles installation concerns: init, license, activate, update.

DevArch operates entirely offline. There are no external integrations, no webhooks, no API tokens, and no telemetry. The license is a signed file validated locally, not a server check.

Where things live

~/.devarch/ — the installation: ruleset, agents, hooks, CLI. Installed once per machine.
In each project:
- CLAUDE.md — a thin pointer that imports the global ruleset.
- docs/context/ — session summaries, the project profile, and per-session state files. This is the memory that carries across sessions.
- docs/work/<feature-slug>/plan.md — session plans, with a pointer file marking the current one.
- docs/adrs/ — Architecture Decision Records (ADRs) — one short file per decision made.
- docs/ddd/ — domain notation, when the modeling capabilities are active.

Every artifact is plain Markdown or YAML committed to the repo, so it travels with git and stays readable without DevArch installed.

The session lifecycle

This is the core of the product — what actually happens, in order, each time you work.

Session start

The session-start hook assigns a session ID and injects the previous session's summary before your first prompt. Claude presents a short recap — what was done, status, next steps — and runs the pre-session audit agent in the background, which reads recent summaries and reports unresolved blockers, recurring issues, and stale artifacts. If the project profile (stack, domains, conventions) is missing or older than seven days, it gets regenerated.

Planning

DevArch has its own planning skill — the session-planner agent, distinct from Claude Code's built-in plan mode. When you state a non-trivial goal, it decomposes the goal into session-sized phases — each with a budget, entry state, deliverables, and exit criteria — and writes the plan to docs/work/<slug>/plan.md. It doesn't plan from the goal alone: it plans from the project's recorded state — ADRs, the project profile, domain notation, prior open items — and lists every reference it consulted in the plan. This is how decisions become work: one or more ADRs ("adopt event sourcing", "split the billing context") translate directly into the phases that implement them. The planning gate then blocks Edit/Write until you approve the plan; /devarch:plan-review runs automatically first (see the decisions section below). Trivial changes skip planning entirely.

Implementation

The coding-discipline rules apply as code is written (next section). After edits to side-effect functions, the mutation-verification agent checks that claimed state changes actually occur and that tests assert on them. On long sessions, a checkpoint agent runs roughly hourly to catch scope drift. Context-budget hooks emit notices at 70/90/100%, shifting the session toward wrapping up rather than starting new work.

Decision capture

When a choice constrains future sessions — a technology, a boundary, a trade-off — DevArch asks whether it's worth recording and, if you confirm, writes an Architecture Decision Record (ADR) to docs/adrs/ with four sections: context, decision, consequences, and the session that produced it.

Session end

Saying "commit", "push", "done", or running /devarch:finalize triggers the work-summary writer before the commit: goal, status, files touched, decisions, open items. The summary is staged with the commit. It's also what step 1 reads next time — that's the loop.

The design principle throughout: nothing depends on the developer remembering to run a step. Recaps, audits, gates, verification, and summaries all fire on their own triggers.

Coding discipline

The ruleset holds Claude to a defined quality bar while implementing:

Invariants are stated as guard clauses, assertions, or type constraints — not comments.
Boundaries are explicit: every file carries a header stating its purpose, public interface, and owning context; visibility mechanisms enforce what's internal.
Behavior Statements precede tests. For every side-effect function, Claude states in conversation: what it changes (DOES), under what conditions (WHEN), why it matters (BECAUSE), and when it refuses (REJECTS WHEN). Tests are derived line-by-line from that statement.
Test grading. Suites are graded before they ship: tautological or assertion-free tests are RED (rewritten immediately); tests that check return values or mocks instead of actual state changes are YELLOW (fixed before commit); only tests that assert on real state mutations are GREEN. The mutation-verification agent cross-checks this independently.
No commit without the test suite passing.

Decisions: ADRs, adr-review, and plan-review

An Architecture Decision Record (ADR) is a short file that captures one decision: the context that forced the choice, what was decided, and what that decision constrains going forward. Writing decisions down only helps if something reads them back, though — so three pieces work together:

ADRs capture the decision when it's made — during a session (DevArch asks "ADR-worthy?"), or in bulk when onboarding an existing codebase by having Claude draft ADRs for the choices the code already embodies.
/devarch:adr-review checks the records themselves before you build on them: per-ADR completeness (is the context real, are the consequences stated?), and — when reviewing several together — cross-ADR seams: two decisions that conflict, a gap neither covers.
/devarch:plan-review checks new plans against the records. It re-reads each phase of a plan against every reference the planner consulted and flags CONTRADICTION (the phase violates a recorded decision), STALE ADR (the record no longer matches reality — the record gets fixed, not just the plan), or TENSION (worth a look). It runs automatically after planning and is silent when the plan is clean.

ADRs flow in both directions here. Downstream, they are planning input: the session-planner reads them and translates one or more decisions into the phases that implement them — an ADR is where work comes from, not just a constraint on it. And plan-review closes the loop on the way back: decisions are recorded, the records are audited, plans are built from them, and every plan is checked against them before the planning gate opens. A plan can't silently contradict a recorded decision, and a stale decision gets corrected rather than obeyed.

Getting started

Setup is three commands, once:

bash devarch-universal.sh            # installs to ~/.devarch — no sudo, no git needed
devarch init                         # in your project — writes the CLAUDE.md pointer
devarch license install @license.dvx # your signed license file

Use bash devarch-universal.sh, not ./ — files downloaded from the web lose their execute bit. Native Windows uses a PowerShell installer; a Docker Container Kit is available for fully isolated setups.

New project: write a short docs/overview.md — problem, users, core idea, MVP scope — then run /devarch:brainstorm, an iterative Q&A that turns the overview into concrete requirements and decisions, captured in the repo.

Existing codebase: point Claude at whatever doc captures the project's intent, run /devarch:architect-review for a graded assessment (boundaries, cohesion, dependency direction, test posture), have Claude draft ADRs for the decisions already embodied in the code, and grade the existing tests against the behavior-statement bar. From there both paths are on the same session lifecycle.

Command reference

Command	The moment for it
/devarch:recap	Session start — what happened last time, what's next.
/devarch:standup	Quick read on progress — done, next, blockers, lifecycle state.
/devarch:finalize	Done for now — summary, commit, push, clean hand-off.
/devarch:brainstorm	Rough idea → focused requirements, through Q&A.
/devarch:architect-review	Inheriting or revisiting a codebase — get the graded map.
/devarch:adr-review	Before building on recorded decisions — checks ADRs for gaps and cross-decision conflicts.
/devarch:plan-review	After planning, before implementing — flags phases that contradict your ADRs. Runs automatically.
/devarch:dashboard	One-page health snapshot: code, tests, plans, blockers.
/devarch:guide	Not sure which command fits — the map of all of them.

Capabilities

Everything above is the base capability, active for every project. Two further levels activate when a domain is complex enough to need modeling:

DDD Discovery (devarch activate ddd-discovery) — describe the domain in conversation; DevArch captures terms, contexts, scenarios, events, and commands as structured notation. The YAML is machine-state — you review plain-language summaries and correct in dialogue.
Domain Modeling (devarch activate domain-modeling) — the complete notation, code scaffolding from the model, cross-context maps, and validation that tightens as delivery approaches (commands need handlers, handlers need tests).

/devarch:ddd-assessment measures a project's domain complexity and recommends what, if anything, to activate. A capability-sniffer agent makes the same suggestion automatically when it detects domain-modeling signals in your work.

Requirements

Claude Code with a Claude subscription (DevArch runs inside it; the DevArch license is separate from Claude entitlement).
macOS, Linux, or WSL for the universal installer; native Windows via the PowerShell installer; the Docker Container Kit runs anywhere Docker does.
A git repository — DevArch's artifacts are plain files that live in the repo.

If DevArch is removed, every plan, summary, ADR, and model it produced remains in the repo as readable Markdown.