{
  "markdown": "<!-- mcp-name: io.github.einvoice-dev1/archsteer -->\n\n# ArchSteer\n\n[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2Farchsteer)](https://www.archsteer.com)\n[![PyPI](https://img.shields.io/pypi/v/archsteer)](https://pypi.org/project/archsteer/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n**Living Architecture Control Plane for the AI-Dev Era.**\n\nAI agents now write code faster than any architect can review, document, or govern it.\nDocs rot instantly, the *real* architecture is invisible, structural decisions get made\nsilently, and intended architecture drifts with every edit. ArchSteer is the always-current\narchitecture **system of record + governance plane**: it derives the real architecture from\ncode, keeps living docs and ADRs auto-built, surfaces every major decision for the architect\nto ratify, enforces declared intent as code-level fitness functions, and steers AI agents to\nconform instead of replicating local slop.\n\nEverything is a projection of one code-derived model — `.archsteer/model.json`.\n\n**Local by default:** the X-ray and governance workflow runs locally and never uploads or\nexecutes your repository's source code. It needs no account, API key, or configuration\nbefore the first scan; cloud snapshot publishing is a separate, explicit `push` command.\n\n```\n                    .archsteer/model.json  (single source of truth)\n                                 │\n   MAP ──── DOCUMENT ──── GOVERN ──── STEER ──── EVOLVE\n  model    living docs   fitness     agent     report.html\n  from     + auto ADRs   functions   guardrails  (drift/\n  source   + diagrams    + ratchet   + MCP       decisions)\n```\n\n## Install\n\n**As a Claude Code plugin** (recommended if you use Claude Code):\n\n```\n/plugin marketplace add einvoice-dev1/archsteer\n/plugin install archsteer@archsteer\n```\n\nThis installs the bundled MCP server (`current_architecture`, `get_target_pattern`,\n`check_file` — via `uvx`, no separate `pip install` needed) plus a skill that teaches\nthe agent when to x-ray, check, and steer on its own, and `/xray` / `/check` commands.\nSee [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) for the manifest.\n\n**As a CLI** (works with any editor/agent, or standalone):\n\n```bash\npip install archsteer                 # regex engine + local MCP server; no parser toolchain required\npip install \"archsteer[treesitter]\"   # optional native acceleration\n```\n\n(Since 0.4.1 the MCP server ships in the base install; `pip install \"archsteer[mcp]\"` still\nworks as a no-op alias.)\n\n**Languages:** JavaScript / TypeScript (Next.js App Router-aware, including\n`tsconfig.json` path-alias resolution — `@/lib/x` resolves to a real internal\nedge, not a phantom third-party dependency), Python, **Java** (Spring-aware),\nand **Salesforce Apex** (SOQL/DML + trigger/handler/selector conventions).\nLayer detection uses in-source signals first — Spring stereotype annotations,\nApex class-name conventions, Next.js reserved filenames (`page.tsx` →\n`page`, `layout.tsx` → `layout`, `route.ts` → `api`, regardless of directory)\n— then directory names.\n\n## Quickstart\n\nFor the fastest proof, run this in a repository and open the generated\n`.archsteer/report.html`:\n\n```bash\narchsteer init && archsteer map && archsteer report\n```\n\nThen add the controls you need:\n\n```bash\narchsteer init      # scaffold .archsteer/ + a starter rule pack auto-matched to your stack\narchsteer map       # build model.json from source\narchsteer docs      # regenerate .archsteer/architecture.md (deterministic, Mermaid) — includes a \"Start here\" hub/entry-point guide and a file-level component map\narchsteer graph <path>  # one component's direct dependencies + dependents — no intent required, just dropped into an unfamiliar file\narchsteer govern    # conformance + drift score by rule\narchsteer adr       # draft ADRs: new structural decisions + widespread rule violations\narchsteer baseline  # accept current debt — the ratchet\narchsteer steer -f src/controllers/payment.js -t \"add refund endpoint\"\narchsteer check     # CI/pre-commit: fail on NET-NEW violations only\narchsteer install-hooks   # wire `check` into a local git pre-push hook\narchsteer report    # self-contained .archsteer/report.html\n```\n\n`init` auto-detects your stack and seeds a matching baseline rule pack — edit\n`.archsteer/architecture.yaml` to fit your conventions, or pick one explicitly:\n\n| Pack | Detected by | Baseline rules |\n|---|---|---|\n| `java-spring` | pom.xml / build.gradle | persistence only in repositories; controllers never touch repositories; no hardcoded secrets; outbound calls confined to services |\n| `salesforce` | sfdx-project.json / force-app | SOQL only in selectors; logic-less triggers; no DML in controllers; no hardcoded secrets; callouts confined to services |\n| `python-service` | pyproject.toml / requirements.txt | persistence behind repositories; thin API handlers; no hardcoded secrets; outbound calls confined to services |\n| `nextjs-app-router` | package.json has `next`, an `app/` dir, no `express` | data access (Supabase/Prisma/raw SQL) and third-party calls confined to lib/ or a route handler; no hardcoded secrets |\n| `express-to-next` | package.json (fallback, or `express` present) | repository pattern; Express → Next.js migration; no hardcoded secrets; outbound calls confined to services |\n\nA repo with `next` as a dependency and an `app/` directory gets the App Router\npack; a `package.json` with `express` (even one migrating to Next) gets the\nmigration pack instead — those are different problems with different rules.\n\nEvery starter pack ships a **security baseline** — no hardcoded credentials/API\nkeys/tokens anywhere in source, and all outbound third-party calls confined to\nthe service layer — so day-one governance covers architecture *and* the two\nsecurity smells AI agents introduce most often.\n\n```bash\narchsteer init --pack salesforce   # override the auto-detection\n```\n\n## The three design guarantees\n\n1. **Ratchet, not freeze.** `archsteer check` blocks only *net-new* violations against a\n   baseline — teams keep shipping features while debt can only shrink.\n2. **Conservative, architect-in-the-loop ADRs.** Two narrow sources, both opt-in review —\n   never auto-committed. Across time: external-boundary changes (new dependency, new\n   datastore, new layer) — never internal reshuffles. Within a snapshot: a rule violated\n   in 3+ components — a genuine pattern worth ratifying or relaxing, not a one-off left to\n   `check`/`govern`. Drafts are idempotent; re-running never duplicates one already on disk.\n3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md`, `AGENTS.md`, and\n   `.cursor/rules/archsteer.mdc` (an always-on Cursor rule) are scoped to the files in play and\n   point at the governing ADR — they don't dump the whole model into the context window.\n\n## Declaring intent — `.archsteer/architecture.yaml`\n\n```yaml\ntarget: \"Migrate Express + raw SQL to Next.js route handlers + the repository pattern\"\nlayers: [route, controller, service, repository, model]\nrules:\n  - id: no-raw-sql-outside-repository\n    type: required_layer_for_data_access\n    allowed_layers: [repository]\n    operations: [RAW]\n    severity: error\n    adr: .archsteer/adr/0001-repository-pattern.md\n    steer: \"Wrap all queries in a repository under src/repositories/. No raw SQL elsewhere.\"\n```\n\nRule types: `required_layer_for_data_access`, `forbidden_import`, `forbidden_data_access`,\n`forbidden_layer_edge`, `forbidden_security_finding` (hardcoded secrets), and\n`required_layer_for_external_call` (confine outbound HTTP/SDK calls to a layer).\n\n## Using with AI agents (MCP)\n\n`archsteer mcp` runs a local MCP server over stdio — spawned by your own editor/agent,\nnever hosted by us. It reads only what `init`/`map`/`govern` already wrote to `.archsteer/`\non disk, so there's no network call and nothing leaves your machine. It exposes three tools:\n\n- `current_architecture` — component/layer counts, conformance/drift, the declared target.\n- `get_target_pattern` — the invariants that apply to a file, *before* you write to it.\n- `check_file` — whether a file you just edited conforms, without waiting for CI.\n\n**Using the [Claude Code plugin](#install) above?** This is already wired up — skip to\n[Quickstart](#quickstart). The rest of this section is for every other client.\n\nAdd it to Cursor with one click:\n[**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=archsteer&config=eyJjb21tYW5kIjoiYXJjaHN0ZWVyIiwiYXJncyI6WyJtY3AiXX0%3D)\n\nAdd it to Claude Code by hand (instead of the plugin), or any other MCP-compatible client:\n\n```bash\nclaude mcp add archsteer -- uvx archsteer mcp    # no separate pip install needed\n```\n\nOr in JSON config directly:\n\n```json\n{ \"mcpServers\": { \"archsteer\": { \"command\": \"uvx\", \"args\": [\"archsteer\", \"mcp\"] } } }\n```\n\n(Already have `archsteer` on PATH via `pip`/`pipx`? `{\"command\": \"archsteer\", \"args\": [\"mcp\"]}`\nworks identically — `uvx` just means no install step at all.)\n\nAlso published to the [official MCP registry](https://registry.modelcontextprotocol.io) as\n`io.github.einvoice-dev1/archsteer`.\n\n## CI / pre-commit / pre-push\n\n- GitHub Action: `.github/workflows/archsteer.yml` (maps, drafts ADRs, runs the net-new gate,\n  uploads `report.html`).\n- Local pre-push hook: `archsteer install-hooks` wires `archsteer check` into\n  `.git/hooks/pre-push` — an architecture conformance score printed on every push,\n  blocking only NET-NEW error violations (the same ratchet as CI, just earlier feedback).\n  `archsteer map`/`check` cache per-file parse results in `.archsteer/parse_cache.json`,\n  so a push that only touches a handful of files re-parses just those files, not the\n  whole repo. Uninstall with `archsteer install-hooks --uninstall`.\n- Already using husky, pre-commit, or lefthook? Add `archsteer check` as a step instead\n  of the raw git hook, e.g. a `.husky/pre-push` containing `archsteer check`.\n\n## Conformance badge\n\nIf your repo pushes snapshots to the situation room (`archsteer push`), its latest\nconformance score is a live badge — the one at the top of this README is this repo\ngoverning itself:\n\n```markdown\n[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)\n```\n\nReplace `YOUR-REPO` with the repo name `archsteer push` reports. Green at ≥90%, grey while\nyou're still x-ray-only (no `architecture.yaml` declared yet).\n\n## Try the demo\n\n```bash\ncd examples/demo-repo\narchsteer init && archsteer map && archsteer report   # open .archsteer/report.html\n```\n\n## Roadmap\n\n- **Shipped** — cloud control plane (Next.js + Supabase): multi-repo situation room with\n  drift/decision time-series. `archsteer mcp`: a local MCP server so agents query the live\n  model + intent mid-edit. An org-wide, hosted MCP server (Team tier) so agents can ask\n  cross-repo questions against the situation room — \"what's our drift index,\" \"which repos\n  have pending ADRs\" — the same data as the dashboard, over MCP. A [Claude Code\n  plugin](#install) (skill + commands + the MCP server, one install). A dedicated\n  **Next.js App Router pack** (layers from `page.tsx`/`layout.tsx`/`route.ts`,\n  `tsconfig.json` path-alias resolution, Supabase/Prisma-aware data-access detection).\n  `archsteer install-hooks`: the same net-new conformance ratchet as CI, wired into a\n  local git pre-push hook.\n- **Later** — a VS Code extension (inline diagnostics, status-bar score — the CLI/MCP\n  already work in any editor today), auth, org/repo model, billing.\n\n## Development\n\n```bash\npython3.11 -m venv .venv && source .venv/bin/activate\npip install -e \".[dev]\"\npytest -q\n```\n\nFound a surprising edge, a false positive, or a stack ArchSteer should understand better?\n[Open an issue](https://github.com/einvoice-dev1/archsteer/issues) with the language,\nframework, and smallest reproducible example. Builder feedback directly shapes the\ndetectors and starter rule packs.\n",
  "bytes": 12042,
  "sha": "fa3081c2a1742a2217f65581a1baa301b722529556c237d1c71214b1c9751d7f",
  "repo_slug": "einvoice-dev1/archsteer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_einvoice_dev1_archsteer_54c5fe0f/readme"
}