archspec

archspec

Spec-driven architecture validation for microservices.

What it does

archspec captures a microservice's architecture as a versioned, machine-readable contract (SERVICE_MAP.yaml), generates Mermaid diagrams and ARCHITECTURE.md deterministically from it, and validates code changes against it on two layers:

• Deterministic gate in pre-commit (schema, cycles, breaking changes, exceptions)
• AI deep dive via /archspec:validate (idempotency, race conditions, eventual consistency)

                    ┌─────────────────────────┐
                    │  docs/SERVICE_MAP.yaml  │  ← single source of truth
                    └────────────┬────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        ▼                        ▼                        ▼
  /archspec:sync          pre-commit hook         /archspec:validate
  (Mermaid + ARCH.md)     (DET-001..015)          (AI-001..010)

Why

Pain	archspec answer
ARCHITECTURE.md rots — written by hand, updated by goodwill	Generated from YAML; CI fails on drift
C4 diagrams in Lucidchart aren't version-controlled	Mermaid in repo, deterministic
Invariants like "endpoint must be idempotent" live in tribal knowledge	Encoded in SERVICE_MAP.yaml; AI rules check the code
Reviewers can't mechanically check contracts	Pre-commit + /archspec:validate reports
New contributors need weeks to understand the bounded context	Read one YAML, get diagrams + invariants

5-minute install

Option A — Claude Code plugin (recommended)

/plugin marketplace add krus210/archspec
/plugin install archspec@archspec

After installation, run /reload-plugins (or restart Claude Code) so commands and skills become available.

Option B — standalone skills

git clone https://github.com/krus210/archspec
ln -s "$PWD/archspec/skills/architecture-sync"        ~/.claude/skills/
ln -s "$PWD/archspec/skills/architecture-investigate" ~/.claude/skills/

Bootstrap a service

cd path/to/your-service
/archspec:init

This creates docs/SERVICE_MAP.yaml, generates initial diagrams + ARCHITECTURE.md, installs the pre-commit hook, and appends the archspec block to CLAUDE.md.

What you get

archspec is intentionally small: each command/skill has a concrete artifact at the end, and those artifacts stay in the repo.

Flow	Output
/archspec:init / architecture-sync bootstrap	docs/SERVICE_MAP.yaml, docs/diagrams/{context,container,sequence}.mmd, generated docs/ARCHITECTURE.md, .servicemap/schema.json, docs/adr/, installed git hooks, and the archspec block in CLAUDE.md
/archspec:sync / architecture-sync	Regenerated Mermaid diagrams and the managed region of docs/ARCHITECTURE.md
/archspec:investigate / architecture-investigate	Read-only contract summary, clarification questions, an optional cross-check against a reference/golden spec, chat-only Mermaid for the proposed change, a YAML diff to apply before coding — including an edge_cases[] risk register that turns every finding into a DET-003-enforced test path — and a definition-of-done + validation loop to run after implementation
/archspec:validate	Markdown report grouped by BLOCK / WARN / INFO / SUPPRESSED, with file references and fix hints
/archspec:check-architecture	Monorepo-wide architecture audit across all SERVICE_MAP.yaml files

The generated diagrams are plain Mermaid, so a fresh /archspec:init produces reviewable text artifacts rather than screenshots. Example output from a task-service init is checked in under examples/task-service-init-output/docs/diagrams.

Context diagram:

flowchart LR
  subgraph this["task-service"]
    svc[task-service]
  end
  upstream_api-gateway[api-gateway] --> svc
  svc -.-> storage_task-store[("in-memory: task-store")]
  svc ==>|publish| topic_task-created>task.created]

Container diagram:

flowchart LR
  subgraph svc_box["task-service"]
    svc[task-service]
  end
  up_api-gateway[api-gateway] -->|CreateTask, GetTask, ListTasks| svc
  svc -.-> store_task-store[("in-memory: task-store")]
  svc ==>|publish v1| pub_task-created>task.created]

Sequence diagram: