Getting Started

Two ways in: start a brand-new project, or bring DevArch to a codebase you already have. Both take the same three setup commands — install, init, license — 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, initialize, license

Run the self-contained installer once per machine, then initialize the project and install your license. 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!

~/my-project % devarch license install @license.dvx
[ok] License installed (valid)

On native Windows — no WSL, no Git Bash — use the PowerShell installer instead. It deploys the same agents and hooks and wires up the PowerShell hook variant automatically.

PS> pwsh -File devarch-windows.ps1
[ok] DevArch installed. Hooks and agents deployed; pwsh hooks wired.

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, domain modeling, 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, initialize, license

Same as a new project: run the installer once per machine, then initialize this repo and install your license. init adds the CLAUDE.md that imports the DevArch ruleset without touching your existing files. On native Windows, install with pwsh -File devarch-windows.ps1 (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)

~/existing-app % devarch license install @license.dvx
[ok] License installed (valid)

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 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.