Enterprise Architecture as Code (EAaC)

Practice enterprise architecture as versioned, validated, code-like discipline — a deterministic engine that proves your architecture is consistent, with AI supplying only judgment, never the proof.

Why

Most enterprise architecture lives in slide decks and wiki pages. Three failures follow:

• Unvalidatable prose — "the architecture is consistent" is an assertion nobody can check.
• Monolithic, lock-in-prone tooling — one vendor's modeler owns your model.
• Ungrounded AI assistance — an assistant that says your design is sound is guessing.

EAaC separates the parts that must be provably correct from the parts that need judgment, gives the correct parts one host-agnostic home, and treats the body of architectural knowledge as data the system reads rather than logic it hardcodes:

• A deterministic Python core (ea-core) owns every operation with a single correct answer — validation, scaffolding, graph computation, reporting, and guarded file writes. Identical inputs produce byte-identical output. No LLM, no network, no wall-clock.
• AI agents live only on the surfaces (Claude / Antigravity plugins) and supply only judgment: conversational tailoring, artifact authoring, advisory synthesis. They propose; the core decides and writes.
• Method packs — artifact types, methods, relationships, and validation rules — are versioned data, read at runtime. Adopting a methodology is configuration, not a code change.

The result: your architecture is a typed, version-controlled repository whose consistency is an exit code, not an opinion.

Install

ea is a CLI. Install it in an isolated environment straight from GitHub:

pipx install git+https://github.com/adworzynski/ea-as-code.git          # `ea` on your PATH
uvx --from git+https://github.com/adworzynski/ea-as-code.git ea --help   # or run without installing

Pin a released version for a reproducible install:

pipx install git+https://github.com/adworzynski/ea-as-code.git@v0.1.0

Then fetch the method library — artifact types, methods, rules, and archetype presets — into your local cache. One online step; resolution is offline thereafter:

ea pack fetch https://github.com/adworzynski/ea-as-code.git   # packs + presets → ~/.cache/ea

Requires Python ≥ 3.10. Not on PyPI yet — install from git. Distribution rides git and files by design; there is no hosted pack registry.

A quick look

ea operates on another repository — one with an ea.manifest.yaml at its root.

Build one. With the library fetched (above), tailor a fresh repo and validate it. Every mutating command is dry-run by default: it returns a confirmation_token bound to the exact computed change, and you re-run with --confirm <token> to apply (the core refuses if the repository drifted):

mkdir my-ea && cd my-ea
ea init --confirm <token>                       # two-phase: plan emits a token, re-run to apply
ea preset list                                  # adoptable archetypes (resolved from the cache)
ea manifest adopt lean-ux --confirm <token>     # materialize definitions/ + write domains
ea project create checkout --confirm <token>
# …author artifacts via `ea scaffold` → draft → `ea commit`…
ea validate --all                               # status: ok (exit 0) or invalid (exit 3)

Or explore a built example. Clone and let the core prove an existing architecture consistent — the examples ship materialized definitions/, so this needs no fetch:

git clone https://github.com/adworzynski/ea-as-code.git
cd ea-as-code/examples/payments-oaa/repo
ea validate --all          # status: ok (exit 0) — the architecture checks out
ea manifest show           # read the org's tailoring: domains, archetype, policies

See the quickstart for the full walk-through, including the conversational surfaces.

How it works

The one integration boundary is the CLI contract: JSON on stdout plus exit codes. Everything above the line is judgment; everything below is determinism.

   Claude plugin   ·   Antigravity plugin   ·   CI / direct CLI      (contract consumers)
                              │  stable, versioned CLI contract
                              ▼
                     ea-core (Python ≥ 3.10)        deterministic, fully tested, no host/LLM knowledge
                              │  reads / validates
                              ▼
        Method Packs (data)   ·   Tailoring Manifest + typed Artifact Repository

It rests on eight principles; two are load-bearing:

• P1 — Determinism in code, judgment in prose. Anything with one correct answer is code; anything needing taste is an agent prompt.
• P2 — The dependency rule. ea-core never imports anything host- or LLM-related; the CLI envelope and exit codes are the only integration boundary.

Read docs/architecture.md for the full picture and docs/principles.md for the constitution.

Documentation & design

• Documentation — architecture · principles · CLI contract · quickstart
• Proposals — design changes are markdown documents reviewed as PRs and tracked with GitHub issues.
• Examples — fully-built EA repositories to explore and smoke-test against.

Contributing

Contributions are welcome under the project's Apache-2.0 license (inbound = outbound — no CLA). Start with CONTRIBUTING.md: it covers the issue → proposal → implementation-PR process and the development setup.

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

License

Licensed under Apache-2.0.