Primer
How does DevArch work?
What DevArch is made of, where it lives on disk, and what it does during a development session. Fifteen minutes, no setup required.
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.
CLAUDE.md
in each project, 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 — one short file per decision made.
docs/proposals/
proposals: proposed work-sets of 1..n items awaiting acceptance, captured via /devarch:proposal.
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.
- 1
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.
- 2
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. 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 accepted proposals — and lists every reference it consulted in the plan. The planning gate then blocks edits until you approve the plan; plan-review runs automatically first. Trivial changes skip planning entirely.
- 3
Implementation
The coding-discipline rules apply as code is written. 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.
- 4
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 with four sections: context, decision, consequences, and the session that produced it.
- 5
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, proposals, and the three reviews
Two artifact registries feed the planner. 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. A proposalis a proposed work-set — 1..n items (a client punch list, a triaged issue set, a PRD's feature list) captured through /devarch:proposal, a facilitated intake that asks what's included, gives every item an id and a checkable "done when", and tracks per-item acceptance: you accept, reject, or defer each item individually. A proposal records intent to do; an ADR records a choice made — and neither helps unless something reads them back. Three reviews do:
/devarch:adr-review verifies decisions 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:proposal-review verifies intentions. It runs automatically when intake finishes and checks every item against the decision record and the work already tracked: an item that violates an ADR, duplicates tracked work, is too vague to ever plan, or is really an undecided decision in disguise — that last one can't be accepted until its ADR is written and accepted, so proposals can't smuggle decisions past the record.
/devarch:plan-review verifies decompositions. It re-reads each phase of a new 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.
And ADRs themselves can carry open questions: an ADR with unresolved questions stays a draft, and DevArch asks — never assumes — whether you want to run the open-questions interview (/devarch:adr-interview), which resolves them one at a time, folding each answer back into the record, until the ADR can be accepted.
Together they form one pipeline — proposal → plan → sessions — with ADRs as the constraint rail alongside. Both registries are planning input: the session-planner translates accepted proposal items and recorded decisions into the phases that implement them, cites item ids in those phases, and marks items done as sessions complete them. And every plan is checked against both registries before the planning gate opens — a plan can't silently contradict a decision or invent work nobody accepted, 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. On Windows, run it under WSL; 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, 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:proposal | A punch list, issue set, or PRD in hand — capture it as an accepted-or-not work-set. |
| /devarch:proposal-review | Before accepting proposal items — checks them against decisions and tracked work. Runs automatically. |
| /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. Further capabilities activate when the project needs them — two levels of domain modeling, and team mode for shared repos:
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).
Team
devarch activate team
Per-developer session context for shared repos: summaries and the current-plan pointer live under docs/context/<user>/, so teammates never collide or hijack each other's recap. Includes the read-only /devarch:team-standup rollup with cross-dev blocker detection. Solo repos are untouched until you activate it.
/devarch:ddd-assessmentmeasures 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; 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.
Ready to try it?
One product, everything included — Solo starts with a 14-day free trial.