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

archspec's three skills (architecture-sync, architecture-investigate, architecture-implement) are portable across Claude Code, Codex, and opencode. Pick the option that matches your setup.

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 — any agent, via npx skills

# installs the 3 archspec skills into every detected agent
npx skills add krus210/archspec
# or scope it: -a claude-code (repeatable), -g (global), -y (no prompts),
#   --skill architecture-sync --skill architecture-investigate --skill architecture-implement

install / i / a are aliases of add. This installs skills only — the /archspec:* slash commands and git hooks come with Option A (or a manual clone). npx skills is the vercel-labs/skills CLI.

Option C — Codex (manual)

git clone https://github.com/krus210/archspec
mkdir -p .agents/skills   # or ~/.agents/skills for a global install
cp -r archspec/skills/architecture-sync        .agents/skills/
cp -r archspec/skills/architecture-investigate .agents/skills/
cp -r archspec/skills/architecture-implement   .agents/skills/

Older Codex builds scan ~/.codex/skills/ instead. Invoke a skill by typing $architecture-sync (or the skill name) or picking it from /skills.

Option D — opencode (manual)

git clone https://github.com/krus210/archspec
mkdir -p .opencode/skills   # or ~/.config/opencode/skills for a global install
cp -r archspec/skills/architecture-sync        .opencode/skills/
cp -r archspec/skills/architecture-investigate .opencode/skills/
cp -r archspec/skills/architecture-implement   .opencode/skills/

Append the archspec block (skills/architecture-sync/templates/CLAUDE.archspec-block.md) to AGENTS.md — the canonical cross-tool instructions file opencode reads (CLAUDE.md is only a fallback when no AGENTS.md exists). Optional command files go in .opencode/command/archspec/. Requires opencode ≥ v1.0.190 for native skills support.

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 AGENTS.md (the canonical cross-tool instructions file) and CLAUDE.md (Claude Code's native file). It runs the same way once the skill is loaded on any host: Claude Code /archspec:init; Codex $architecture-sync and ask it to bootstrap; opencode load the skill and ask it to bootstrap.

What you get

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