archsteer 0.3.0

Living Architecture Control Plane for the AI-Dev Era

ArchSteer

Living Architecture Control Plane for the AI-Dev Era.

AI agents now write code faster than any architect can review, document, or govern it. Docs rot instantly, the real architecture is invisible, structural decisions get made silently, and intended architecture drifts with every edit. ArchSteer is the always-current architecture system of record + governance plane: it derives the real architecture from code, keeps living docs and ADRs auto-built, surfaces every major decision for the architect to ratify, enforces declared intent as code-level fitness functions, and steers AI agents to conform instead of replicating local slop.

Everything is a projection of one code-derived model — .archsteer/model.json.

                    .archsteer/model.json  (single source of truth)
                                 │
   MAP ──── DOCUMENT ──── GOVERN ──── STEER ──── EVOLVE
  model    living docs   fitness     agent     report.html
  from     + auto ADRs   functions   guardrails  (drift/
  source   + diagrams    + ratchet   + (MCP)     decisions)

Install

pip install archsteer                 # regex engine, zero native deps
pip install "archsteer[treesitter]"   # optional native acceleration

Quickstart

archsteer init      # scaffold .archsteer/ + seed intent (Express → Next.js + repository)
archsteer map       # build model.json from source
archsteer docs      # regenerate .archsteer/architecture.md (deterministic, Mermaid)
archsteer govern    # conformance + drift score by rule
archsteer adr       # draft ADRs for new structural decisions (architect-in-the-loop)
archsteer baseline  # accept current debt — the ratchet
archsteer steer -f src/controllers/payment.js -t "add refund endpoint"
archsteer check     # CI/pre-commit: fail on NET-NEW violations only
archsteer report    # self-contained .archsteer/report.html

The three design guarantees

1. Ratchet, not freeze. archsteer check blocks only net-new violations against a baseline — teams keep shipping features while debt can only shrink.
2. Conservative, architect-in-the-loop ADRs. Only external-boundary changes (new dependency, new datastore, new layer) draft an ADR — never internal reshuffles, never auto-committed.
3. Sharp agent steering. Guardrails injected into CLAUDE.md / AGENTS.md are scoped to the files in play and point at the governing ADR — they don't dump the whole model into the context window.

Declaring intent — .archsteer/architecture.yaml

target: "Migrate Express + raw SQL to Next.js route handlers + the repository pattern"
layers: [route, controller, service, repository, model]
rules:
  - id: no-raw-sql-outside-repository
    type: required_layer_for_data_access
    allowed_layers: [repository]
    operations: [RAW]
    severity: error
    adr: .archsteer/adr/0001-repository-pattern.md
    steer: "Wrap all queries in a repository under src/repositories/. No raw SQL elsewhere."

Rule types: required_layer_for_data_access, forbidden_import, forbidden_data_access, forbidden_layer_edge.

CI / pre-commit

• GitHub Action: .github/workflows/archsteer.yml (maps, drafts ADRs, runs the net-new gate, uploads report.html).
• Git hook: cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit.

Try the demo

cd examples/demo-repo
archsteer init && archsteer map && archsteer report   # open .archsteer/report.html

Roadmap

• Phase 2 — cloud control plane (Next.js + Supabase): multi-repo situation room with drift/decision time-series.
• Phase 3 — archsteer mcp: an MCP server so agents query the live model + intent mid-edit.
• Phase 4 — auth, org/repo model, billing.

Development

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q