ArchSpine

Appearance

ArchSpineDeterministic context and architecture guardrails for AI coding agents.

Upgrade your Git repo with a `.spine/` control plane for MCP, rule-based governance, and AI-friendly code navigation.

Get Started
MCP Integration
View Demo
ArchSpine social preview

Deterministic context

Build a structured semantic mirror under `.spine/` so AI agents can navigate your codebase without consuming the whole repository as prompt context.

Architecture guardrails

Declare invariants in `.spine/rules/` and audit layer boundaries before AI-generated changes spread architecture drift.

Git-aware onboarding

Default to distributable `.spine` snapshots for team-facing repositories, while keeping local-only mode available for lighter setups during `spine init`.

MCP-ready workflows

Mount local project structure, responsibilities, and rule data into Cursor, Claude, and other MCP clients over STDIO.

Experimental view layer

Optionally derive `.spine/view/public-surface.json` and `.spine/view/risk-hotspots.json` as fast-reading aids without changing the main sync contract.

Measurable prompt engine

Use runtime modes, diagnostics, and corpus benchmarks instead of tuning generation behavior blindly.

The magic moment ​

Use the built-in demo project to show the full loop:

bash
npm run build
cd examples/demo-project
rm -rf .spine/index .spine/atlas
rm -f .spine/cache.db .spine/cache.db-shm .spine/cache.db-wal .spine/manifest.json .spine/languages.json .spine/.lock
node ../../dist/cli/index.js llm --project set provider mock
node ../../dist/cli/index.js sync
node ../../dist/cli/index.js check
node ../../dist/cli/index.js fix

Why this matters ​

Most AI coding tools still work by over-feeding source files into prompts and hoping the model reconstructs your architecture. ArchSpine changes the interaction model:

  • it turns repository structure into a queryable control plane
  • it makes rules explicit before edits happen
  • it gives MCP clients a stable, local source of truth
  • it defaults repositories toward distributable .spine Git behavior during initialization while keeping local-only mode available

Current runtime posture ​

The current 1.0.x line already includes:

  • mode as the primary runtime control surface: standard, heavy
  • advanced overrides still exist, but the normal product surface is mode=standard|heavy
  • diagnostics snapshots for prompt and relevance decisions
  • fixed corpus and comparison harnesses for prompt-policy regression
  • a heavier validate path that can prioritize semantic stability before markdown generation
  • a public CI split where the default gate stays product-focused and research bench coverage runs separately on demand

Use the runbook for operational details, the architecture overview and task-execution model for runtime boundaries, and the prompt-engine design docs for the architecture rationale.

Works well with ​

  • Cursor
  • Claude Desktop
  • Claude Code / CLI
  • custom MCP clients that support STDIO transports

English is the primary docs tree; zh-CN mirrors shipped behavior.

Released under Apache License 2.0