Archkeep

Why Archkeep

Architecture rarely fails all at once. It erodes.

A team agrees on layers, ownership and dependency boundaries. Then the repository changes: a convenient import crosses a boundary, a temporary exception becomes permanent, documentation drifts from reality, and coding agents make the same problem scale faster.

The build can still pass. Tests can still pass. A linter can still report clean.

The missing question is:

Does the code still conform to the architecture we chose?

Archkeep turns that question into a machine-checkable contract.

The core idea

ARCHITECTURE INTENT
        ↓
OBSERVED REALITY
        ↓
DETERMINISTIC EVIDENCE
        ↓
AUTHORITATIVE VERDICT

You declare the boundaries and dependency rules that matter. Archkeep statically observes the repository, builds the relevant graph and evidence, compares reality with intent, and returns a deterministic verdict.

The same authority can be used by humans, CI and coding agents.

Why it is different

Archkeep does not replace these tools. It owns the architectural boundary between them.

How it fits agentic development

Human declares architecture
            ↓
      Coding agent
   reads architecture context
            ↓
       changes code
            ↓
       Archkeep check
            ↓
     deterministic verdict
            ↓
             CI

Agents may inspect, explain and propose. They do not redefine the architecture when their changes disagree with it.

Core capabilities

• Architecture enforcement — dependency and boundary rules across polyglot repositories.
• Deterministic evidence — 24 commands with versioned, byte-stable JSON; reproducible verdicts with coverage and provenance.
• Governance — waivers, ADRs, fitness functions and explicit decisions.
• Architecture evolution — drift, change impact, history, health and debt.
• Agent integration — CLI, MCP, VS Code and architecture-aware agent skills.

Polyglot by design

Archkeep evaluates architecture across Go, Rust, Python, TypeScript/JavaScript, Vue, Java/Kotlin and C# repositories, while integrating with workspace systems such as Nx and Moon or discovering projects natively.

The goal is one architectural policy across language boundaries, not one enforcement mechanism per language.

Quick start

pnpm add -D @ecoma-io/archkeep

Register Archkeep with Nx, use the native archkeep.json workspace discovery, or configure the integration appropriate for your repository.

Then run:

pnpm exec archkeep check

For an existing repository, start with discovery:

pnpm exec archkeep discover

Node.js ≥ 22 is required. No language toolchain is required for static analysis.

→ Getting started

A small example

Declare a rule such as:

export const depConstraints = [
  {
    sourceTag: "layer:domain",
    onlyDependOnLibsWithTags: ["layer:domain"],
    description: "The domain outlives frameworks, queues and databases.",
  },
];

If a domain project imports infrastructure:

libs/pricing/src/discount.go:14:2  onlyTagsConstraintViolation
  A project tagged with "layer:domain" can only depend on libs tagged with layer:domain
  import      "github.com/acme/mq-client/publish" (static)  pricing → mq-client
  constraint  sourceTag layer:domain → onlyDependOnLibsWithTags [layer:domain]
  rule        The domain outlives frameworks, queues and databases.

The important part is not only that the check fails. The verdict carries the evidence and points back to the architectural rule that caused it.

Used in the Ecoma ecosystem

Archkeep is dogfooded by:

• Loom
• Action-Agents
• Release-Craft

Documentation

• Getting started
• Architecture model
• Governance lifecycle
• CLI reference
• Integrations
• Agent skills
• Full documentation

Contributing

The most valuable contribution is a missed violation: a real architectural boundary that Archkeep failed to detect.

See CONTRIBUTING.md, Code of Conduct and SECURITY.md.

License

Apache License 2.0