How it works
The discipline is automatic.
DevArch hooks into Claude Code's lifecycle. You never invoke the gates or agents — they fire on their own, and nothing is lost between sessions. Two loops do the work: the session lifecycle and the project lifecycle.
The session lifecycle
What happens automatically in every session — from start to ship.
Session Start
Every session opens with the SessionStart hook creating session state and surfacing the previous session. DevArch presents a recap of where you left off, runs a pre-session audit for blockers and stale artifacts, and refreshes the project profile when it has gone stale.
Planning
State a non-trivial goal and the session-planner decomposes it into session-sized phases — first consulting your recorded decisions (ADRs, the project profile, and accepted proposal items from /devarch:proposal intake). plan-review then adversarially checks each phase against those references before you approve, and a gate blocks edits until you do.
Implementation
As you write code, hooks fire: boundary-check prompts for a Boundary Statement on cross-boundary state, the budget tracker warns at 70/90/100% of the phase budget, and mutation-verification confirms your tests assert on real state changes. A session checkpoint catches scope drift; decisions worth keeping become ADRs. When an ADR carries open questions, DevArch asks for consent — never resolving them itself — then /devarch:adr-interview walks them one at a time until the ADR is accepted.
Finalize
On ship, the work-summary-writer records what changed, the status, and any blockers; capability-sniffer suggests when to activate the team capability; and the PreCompact hook preserves the work log before context is wiped. Then it's committed and pushed — and the next session picks up exactly where this one ended.
The project lifecycle
Sessions are the inner loop. Skills, artifacts, and decision records connect them into a coherent project.
Explore ideas with a facilitated brainstorm; review the architecture periodically; snapshot project health on demand. Every session leaves a summary, every significant decision becomes an ADR, and every plan lives in docs/work. Start a new session tomorrow and the audit agent tells you exactly where you left off — the project accumulates discipline instead of eroding it.
The layer underneath
DevArch is built on Claude Code, and what it can promise depends on how Claude Code actually behaves — not on how it's assumed to behave. Five mechanics decide what a workflow layer is able to guarantee.
Instruction precedence
Claude Code composes a system prompt for every session — its own operating instructions, with your project's CLAUDE.md layered on top and claiming precedence over defaults. Both speak to the same questions: when to delegate work, how far to go beyond what was literally asked, when to confirm before acting. Where they agree, nothing surfaces. Where they compete, the resolution is a design decision rather than an accident, and it shifts as each model release follows instructions more literally than the last.
DevArch's ruleset is written against that boundary on purpose, not in isolation from it — and re-checked whenever either side moves.
The subagent boundary
When a subagent runs, its report returns to the main session — not to you. Anything the main session doesn't pass along, you never see. A specialist agent can produce a flawless report and still deliver nothing, because the report died at the hop.
Anything a DevArch agent produces for you is required to survive that hop intact — its specifics and its evidence markers included, not a paraphrase.
Hooks and real enforcement
Claude Code lets you intercept a tool call before it runs, and the exit code decides everything. One path stops the call and delivers the reason back to the model; another lets it through with the message going nowhere the model can read. A hook that prints a warning and reports success has blocked precisely nothing, whatever its text claims.
DevArch's gates are built on the path that actually blocks, and every gate's wording is reviewed together with its behavior — a banner claiming enforcement it doesn't perform is treated as a defect, not a style choice.
Context and compaction
Long sessions get summarized. As context fills, earlier turns are compacted away, and whatever lived only in the conversation goes with them — the reasoning, the rejected approaches, the thing you agreed on two hours ago.
Everything a future session needs is written to the repository before that happens: committed, shared, and readable by the next session and the next developer.
Validation per model
Instruction-following behavior is not a constant. It shifts between releases and does not transfer across model lines — a rule that fires correctly on one model is an untested assumption on the next.
DevArch validates its rules against each model it supports, records the result, and states the gaps rather than assuming them away.
None of this is visible while it works, which is the point. It becomes visible the moment a layer takes any of it for granted.