Getting Started

Two ways in: start a brand-new project, or bring DevArch to a codebase you already have. Both take the same two setup commands — install, init — then diverge on how you get oriented.

Start a new project

1. Write a project overview

DevArch works from a single source of truth: a plain Markdown document describing what you're building — problem, users, the core idea, and a rough MVP scope. A few paragraphs is enough; the brainstorm will sharpen it.

~ % mkdir my-project && cd my-project
~/my-project % git init
~/my-project % $EDITOR docs/overview.md

# # Project Overview
# ## Problem — what hurts today
# ## Users — who feels it
# ## Core idea — the one-line pitch
# ## MVP scope — smallest useful version

2. Install and initialize

Run the self-contained installer once per machine, then initialize the project. init writes the CLAUDE.md that imports the DevArch ruleset — the directives, agents, and hooks that enforce discipline every session.

~ % bash devarch-universal.sh
[ok] Install complete! 'devarch' is on PATH.

~/my-project % devarch init
[ok] Created CLAUDE.md (imports the DevArch ruleset)
[ok] Project initialized!

On Windows, DevArch runs under WSL — install and use it from your WSL shell with the same universal installer. The Docker Container Kit is another option anywhere Docker runs.

3. Start Claude and read the overview

Launch Claude Code in the project. The DevArch session-start hooks restore context automatically; then point Claude at your overview so it understands what you're building before a single decision is made.

~/my-project % claude
[Session ID: …] DevArch ready.

> Read docs/overview.md and tell me what you understand about this project — and what's still unclear.

4. Brainstorm

Run /devarch:brainstormto turn a loose overview into a focused set of requirements and decisions. It's a conversation, not a one-shot report — Claude asks, you answer, and the thinking converges. The brainstorm captures everything in docs/brainstorm/{topic}/, ready to feed planning and your first session of real work.

> /devarch:brainstorm my-project
Reading docs/overview.md…

Let's start with the core concept — who is the primary user, and what do they do first?

…iterative Q&A…

[written] docs/brainstorm/my-project/overview.md
[written] docs/brainstorm/my-project/techstack.md

From here, DevArch's lifecycle takes over — planning gates, behavior statements, quality gates, ADRs, and session continuity. You direct the work; DevArch keeps the discipline.

Bring DevArch to an existing project

1. Point at the intent doc

An existing repo usually already describes itself — a README.md, a design doc, or a product brief. Just identify the file that best captures the project's intent. No need to rewrite it; that's the overview you'll point Claude at.

~/existing-app % ls docs README.md
README.md docs/architecture.md docs/product-brief.md

# Pick the doc that captures intent —
# README.md, a product brief, or a design doc.

2. Install and initialize

Same as a new project: run the installer once per machine, then initialize this repo. init adds the CLAUDE.md that imports the DevArch ruleset without touching your existing files. On Windows, run everything under WSL (see above).

~ % bash devarch-universal.sh
[ok] Install complete! 'devarch' is on PATH.

~/existing-app % devarch init
[ok] Created CLAUDE.md (imports the DevArch ruleset)

3. Grade the architecture

Start Claude, then run /devarch:architect-review. It grades the codebase across the categories an architect cares about — boundaries, cohesion, dependency direction, test posture — filtered to what's relevant to this project. This is your map before you change anything.

~/existing-app % claude

> /devarch:architect-review
Scanning sources, tests, and boundaries…

Boundaries B- — domain imports infrastructure in 3 places
Cohesion A- — modules are single-purpose
Tests C+ — high count, low assertion quality

4. Capture the decisions as ADRs

Existing codebases carry decisions no one wrote down. Have Claude read your docs and the code, draft Architecture Decision Records for the choices already made, then run /devarch:adr-review to check them for gaps and conflicts. Now future sessions stop re-litigating settled calls.

> Read docs/ and the codebase. Draft ADRs for the architectural decisions already made — one per decision, in docs/adrs/.

[written] docs/adrs/0001-monorepo.md
[written] docs/adrs/0002-event-sourcing.md

> /devarch:adr-review — check them for gaps + cross-ADR seams

5. Audit the tests

High test counts hide low-value suites. Ask Claude to grade the existing tests against DevArch's behavior-statement discipline — flagging tests that check return values or mocks instead of real state changes. You get a prioritized list of what to harden, not a vanity coverage number.

> Grade the test suite: which tests assert on real state mutations, and which only check return values or mocks?

YELLOW orders.test.ts — asserts on return value, not the persisted record
GREEN billing.test.ts — asserts on the charged amount in the DB

From here you're on the same lifecycle as any DevArch project — run /devarch:dashboard anytime for a health snapshot, and let the gates keep the discipline as you work.

Where DevArch does not belong

Do not run DevArch in CI, or in any automated production process.It is an extension of Claude Code, which means its rules are instructions to a model, not deterministic steps in a script. A model follows instructions well — that is the whole premise — but "well" is not "always," and the difference matters enormously depending on what is downstream. In an interactive session you are present: you see what ran, you notice what did not, and you correct it in the moment. A pipeline has nobody watching, so the same variance becomes a silent gap in your build.

We measured this rather than assuming it. Driven headlessly with claude -p, some rules that fire reliably in interactive sessions did not fire at all — repeatably, including against a production-sized repository. DevArch is built for the session where a developer is in the loop, and that is where its guarantees hold.

This is a statement about DevArch, not about automation. Use ordinary CI for the things CI is good at — running your tests, type checks, linters, and builds deterministically, every time. DevArch's job is the work that happens before the commit; your pipeline's job is verifying the result. The commit gate exists precisely so that the handoff between the two is clean.

Where to go next

• Commands — every DevArch command and the moment to reach for it.
• CLI in Action — a full session, init through commit, in real terminal output.
• The Trio Paradigm — the thinking behind the methodology.