The full enterprise-architecture lifecycle — define, document, govern, maintain — as agent skills over a deterministic core.
Unstructured input in. Validated ArchiMate 3.2, generated views, ISO 42010 documentation and living governance out. All of it in git.
Quickstart · How it works · Tutorial · CLI reference · Rule catalogue · Design & research · Contributing
The model supplies judgement. The tooling supplies proof. Anything a language model asserts about ArchiMate semantics, or about what a source document says, is checked by code against vendored primary-source data before it can enter the repository.
That inverts the usual arrangement, and it is deliberate. The research this design is built on (full grounding) found three failure modes, and each one gets a mechanical answer rather than a hope:
| Documented failure mode | Mechanical answer |
|---|---|
| Relationship semantics is the weakest measured LLM capability on modelling tasks | Every relationship is checked against Archi's vendored, hash-pinned ArchiMate 3.2 matrix (11 569 permitted pairs) — REL001 even tells you when your endpoints are just swapped |
| LLMs fabricate citations — rationales quoting sentences that do not exist | Every concept carries a verbatim quote that the validator locates in the actual source file, or an explicit assumed: true with a rationale. There is no third option |
| EA repositories die of staleness — content nobody owns, that nobody revisits | Ownership and review dates are mandatory in the approved zone; dispensations expire loudly; the staleness queue is ordered by real consumer demand |
The worked example — a small fictional B2B food manufacturer — rendered by the built-in, dependency-free SVG renderer from the same deterministic layout the compiler uses:
A clean gate, with the one declared assumption surfaced instead of buried:
$ python -m easkills validate --root eval/example
EA model validation -- zone 'approved' at .../eval/example
ArchiMate oracle 3.2; 17 elements, 15 relationships, 4 views
INFO PROV006 model/approved/strategy.yaml:elements[3] [goal-shorten-lead-time]
assumed, pending confirmation: Inferred from operational pain described in the
interview, not stated as a goal by any stakeholder. Needs confirmation at the
next architecture board.
0 error(s), 0 warning(s) -- PASS
And what a real catch looks like:
ERROR REL001 model/approved/broken.yaml:relationships[1] [rel-swapped]
Realization from BusinessProcess 'process-invoicing' to ApplicationComponent
'app-finance' is not permitted by the ArchiMate 3.2 relationship matrix.
Permitted here: Association, Flow, Serving, Triggering -- it is permitted in the
opposite direction, so the endpoints are probably swapped
Output is colorized on interactive terminals and degrades to plain text in pipes, CI
logs and captures — colour is display, never data (NO_COLOR / FORCE_COLOR
respected).
git clone https://github.com/dithiothreitol/ea-skills.git && cd ea-skills
python -m pip install -r requirements.txt
# Tour the worked example: every gate, end to end
python -m easkills validate --root eval/example # model gate
python -m easkills validate-facts --root eval/example # evidence gate
python -m easkills validate-gov --root eval/example # governance gate
python -m easkills compile --root eval/example # -> ArchiMate Open Exchange XML
python -m easkills docs --root eval/example # -> ISO 42010 description + SVGs
python -m easkills context --root eval/example --scope app-erp-core # agent context pack
python -m easkills impact --root eval/example --scope app-erp-core # blast radius of a change
python -m easkills roadmap --root eval/example # plateaus, gaps, unscheduled intentTo start your own architecture repository, copy template/ and follow
the Getting-started tutorial — from a raw interview to a
validated model, rendered views and a generated architecture description.
Already have a model? import reads an ArchiMate Open Exchange export (Archi,
and most commercial tools) into model/staging/, and intake-csv turns an
application-inventory spreadsheet into a source document whose quotes stay verifiable.
Both land as proposals: nothing imported counts as evidence until someone vouches
for it. See ea-import.
flowchart LR
SRC["facts/sources/<br/>interviews, exports,<br/>documents"]
FACTS["fact register<br/>verbatim quotes,<br/>mechanically verified"]
STAGING["model/staging/<br/>machine proposals"]
APPROVED["model/approved/<br/>human-signed"]
XML["ArchiMate<br/>Open Exchange XML"]
DOCS["ISO 42010 description<br/>+ SVG views"]
PACKS["agent context packs"]
GOV["governance log<br/>standards · decisions ·<br/>waivers · services"]
SRC -- "ea-intake<br/>chunk / extract / verify" --> FACTS
FACTS -- "ea-capability-map<br/>ea-model" --> STAGING
STAGING -- "promote gate<br/>(human sign-off)" --> APPROVED
APPROVED -- compile --> XML
APPROVED -- "docs / render" --> DOCS
APPROVED -- context --> PACKS
GOV <-->|"requests · delta ·<br/>compliance · waivers"| APPROVED
Every arrow is a deterministic command with an exit-code contract, and every stage is
driven by one of the 25 agent skills — from ea-intake through
ea-approve to ea-board. The orchestrator (ea-run) routes requests catalog-first
and keeps the stage order honest.
| Stage | Skills | Deterministic gate |
|---|---|---|
| Ingest | ea-intake, ea-delta-ingest, ea-import |
validate-facts, coverage --min-coverage; intake-csv makes a spreadsheet citable; import lands in staging, all assumed |
| Model | ea-capability-map, ea-model, ea-validate |
validate (staging as overlay), 3-repair cap |
| Publish | ea-approve |
promote — the only write path into approved/ |
| Document | ea-stakeholders, ea-views, ea-docs |
docs, render, ISO loop rules, freshness CI check |
| Govern | ea-standards-base, ea-dispensation, ea-adr, ea-compliance, ea-service |
validate-gov — expiry and SLA are enforced, not filed |
| Maintain | ea-health, ea-change-triage, ea-board, ea-context |
kpi, debt, staleness, conformance, correspondences, roadmap, delta, context, impact |
| Assess | ea-model, ea-capability-map, ea-align |
readiness — the per-layer definition of done, every checkpoint naming its elements; align --strict — the model against a hash-pinned reference architecture, every unmapped node a named gap and every exclusion a recorded decision |
| Propose | ea-align, ea-adr |
propose --from align|readiness|overlap|time — findings become staging skeletons with derived ids; the prose, the owner and the review date stay human, and the gate enforces it. Refuses rather than emitting anything the gate would reject |
| Comply | ea-regulatory, ea-ai-governance |
dora-register and ai-act-register — the Register of Information and the AI system inventory from the approved model, each naming the fields it could not fill; control gaps ride align as ALN004 |
| Consume | ea-check |
check --scope inside a product repo — standards lifecycle vs declared dependencies |
| Evaluate | ea-eval |
score --min-f1 against the golden set; the score names every unmatched item, and relationships the model only implies count as half a match via ArchiMate's derivation rules |
Authoring format is fragmented YAML (model/<zone>/*.yaml), so git diffs stay
reviewable at concept level. Open Exchange XML is a build artifact, never hand-edited.
Identifiers are author-supplied stable slugs, so re-running a pipeline produces a
reviewable diff rather than a rewrite.
Two zones, one write path. staging/ holds machine proposals; approved/ holds
human-signed content. Staging validates as an overlay on approved (a proposal may
reference approved elements; re-using an id proposes an update), so skills model the
delta rather than copying the world. The only way into approved is
python -m easkills promote, whose gate validates the merged result by approved-zone
standards — ownership and review dates, advisory while drafting, block there. The git
commit of the move is the approval record.
The skills are measured, not just the tooling. Prose cannot be executed by pytest, so
the product used to be the untested half. eval/harness/ now runs the skills against the
golden set with an API key — a blind scratch repository, the pipeline the prose describes,
three runs per case because the spread is the honest part — and scores the result; a second
harness checks that the governance skills produce records satisfying their own rules. Five
of the 24 skills are measured that way and the coverage page says
exactly which, including the two nothing mechanical covers. The first baseline paid for the
harness the same day by exposing three prose defects invisible to reading.
Intake comes first and is measured. ea-intake extracts a fact register
(facts/register/*.yaml) from raw sources chunk by chunk: atomic statements, each with
a verbatim quote the validator locates mechanically, plus an entity table
(facts/entities.yaml) so "the portal" and "Order Portal" stay one thing. Facts have
no assumed escape hatch — what the sources do not say becomes a clarification
question, and the coverage report lists every source statement no fact cites, with
line numbers, so "we ingested everything" is a checked claim rather than a felt one.
Every model concept is evidenced or declared. Each element and relationship carries
provenance — a source file plus verbatim quote which the validator locates in the
actual file, or a reference to a fact whose quotes are re-verified transitively — or
assumed: true with a rationale, which surfaces as an open question. There is no
third option, and no way to quietly invent an element.
elements:
- id: app-erp-core
type: ApplicationComponent
name: ERP Core
owner: finance-systems@aurorafoods.example
lastReviewed: 2026-06-30
properties:
timeDisposition: Tolerate # portfolio views come free, not from re-modelling
lifecycle: active
provenance:
- file: facts/sources/interview-operations-2026-07-15.md
quote: The ERP core holds the master order records and does the invoicingThe motivation layer binds, mechanically. Requirements, constraints, principles
and goals carry an appliesTo selector naming the elements they bind; the validator
checks every binding resolves and that selectors stay on motivation elements.
Views declare content, not geometry — and a purpose. A view lists which elements
to show and which declared stakeholder concerns it frames (ISO 42010's loop:
stakeholder ↔ concern ↔ view, closed by the ISO* rules). The compiler computes a
deterministic layered layout; the renderer draws the same layout as dependency-free,
byte-stable SVG. Neither a person nor a model hand-places coordinates, so diffs stay
about architecture.
Governance is records + gates + diffs, git-native. Standards live one per file with a lifecycle; an element referencing a retired standard is an error unless an open dispensation covers it — and dispensations carry a schema-mandatory expiry that turns into an error the day it passes, so exceptions stay governed instead of silent. Decisions are MADR-shaped with mandatory rationale (ISO 42010 §6.10); compliance verdicts use TOGAF's six levels, and a non-conformant verdict with no follow-up is flagged. The git commit of any record is its audit trail.
EA runs as a service, and demand steers maintenance. The catalog (services/)
defines what EA provides — every offering with a named owner, a fulfilment path and an
SLA in days, schema-mandatory. The demand ledger (governance-log/requests/) records
who asked for what: fulfilment must point at the deliverable, refusals need a written
reason, and an open request past its SLA lands in KPI as a breach. Demand feeds back:
the staleness review queue orders by how often consumers actually ask about an
element, and never-requested content is named a de-scoping candidate — architecture
grows on demand, and rots only where nobody is looking anyway.
The model governs agents, not just people. python -m easkills context --scope <system> produces a scoped extract for coding agents in downstream repos: binding
requirements via appliesTo, standards with lifecycle and waivers, applicable
decisions, integration neighbours — opened by a mandatory freshness label, because a
stale model served as binding constraints carries false authority.
Documentation is generated, committed, and provably fresh. python -m easkills docs produces the architecture description (Clause 6 shape: stakeholders → concerns
→ views, plus portfolio TIME quadrants, capability support and every open assumption)
from model/approved/ only. Output is deterministic — the "as of" date is the newest
lastReviewed in the model, not the wall clock — so the generated files are committed
and CI fails when they go stale.
"Is this layer done?" is measured against two yardsticks, not a feeling. coverage
answers did we model what we were told; align answers did we model what a business
like this has — against a reference architecture in reference/<name>/: a
hash-pinned taxonomy plus a human-authored mapping. Every node comes back covered,
partial, a named gap, or out-of-scope with a mandatory rationale, because a gap
somebody decided about and a gap nobody noticed must not look the same. Coverage claims
resting on staging proposals do not count, exclusions inherit down a branch while
coverage claims never do, and a pack whose pins do not verify is refused rather than
read. Licensed reference models (BIAN, APQC PCF, eTOM) stay in the adopter's repository
under the adopter's licence — this repository ships the mechanism and only
openly licensed content.
The tool computes the exposure, the operator prices it. Debt is measurable — element-days
past the staleness threshold, dispensation-days open, elements on retired standards,
unrealized capabilities, surplus realizers. What any of that is worth is not, so nothing
here guesses: unit rates live in the adopter's ea.config.yaml, and with none configured
debt prints exposure exactly as it did before the feature existed. When a total is
printed it names what it left out — exposures with no rate, elements with no review date —
because a partial total that looks complete is the number that reaches a slide.
The oracle is vendored and hash-pinned. Semantic rules come from Archi's
relationships.xml (the ArchiMate 3.2 permitted-relationship matrix) and the Open
Group exchange schemas — not from rules typed from memory, and genuinely not fetched
at runtime: schema building runs with the network disabled at parser level, and a test
proves it. See oracle/NOTICE.md. The JSON Schema for the DSL is
generated from the same oracle, so the authoring format cannot drift from the
validator.
| Concern | What is used | How |
|---|---|---|
| Notation | ArchiMate 3.2 | Primary. Enforced from the machine-readable matrix, exported as Open Group Model Exchange XML. |
| Architecture description | ISO/IEC/IEEE 42010:2022 | Documentation structure and conformance checking: stakeholders, concerns, viewpoints, views, decisions with rationale, and §6.9 correspondences derived from the records that declare them — never authored twice. |
| Method and governance | TOGAF 10 | Used as vocabulary and for governance mechanics (conformance levels, dispensations with expiry, Phase H change classes) — not as a process to march through. |
| Detail design | UML | Secondary, where ArchiMate is too coarse (sequences, deployment). |
| Decisions | MADR | Architecture decision records in the governance log. |
On TOGAF specifically: the empirical case-study literature finds that even self-described TOGAF practices do not follow the ADM or use the Content Framework, and that the single most-used EA artifact in practice — the business capability map — is not in TOGAF's content metamodel at all. So this repository targets the artifact set practitioners are documented to actually use (capability map first, then landscapes, inventories, roadmaps, principles, standards, solution overviews, decision records) and implements TOGAF where it is genuinely strong: governance mechanics.
There is no shortage of adjacent work: Claude skills that advise on TOGAF, MCP servers that manipulate Archi models, tools that lint architecture-as-code in bespoke YAML, markdown-only governance frameworks, and commercial platforms with real ingestion agents. What is not otherwise available is the combination:
| Capability | ea-skills | mcp-archimate | 7bots / archimate-deep-agent | Transitrix | ArcKit | Ardoq |
|---|---|---|---|---|---|---|
| Packaged as agent skills | ✓ | — (MCP server) | — (platform) | partial (plugins) | ✓ | — (SaaS) |
| Unstructured-input ingestion | ✓ verified quotes (documents and spreadsheets) | — | ✓ | ✓ | partial | ✓ |
| Real ArchiMate model files (Open Exchange) | ✓ XSD-validated, both directions (compile + brownfield import) | ✓ | ✓ | — (custom YAML) | — (markdown) | — |
| Generated views | ✓ deterministic SVG | ✓ | — | — | — | ✓ |
| Per-element source traceability | ✓ mechanically verified | — | ✓ claimed | partial | ✓ doc-level | partial |
| Deterministic semantic validation | ✓ vendored 3.2 matrix | ✓ | — | ✓ (own rules) | — | partial |
| Standards-shaped documentation (ISO 42010) | ✓ + conformance checklist | — | — | — | — | — |
| Governance + maintenance (SIB, dispensations with expiry, debt, staleness, service catalog, agent context packs) | ✓ | — | — | partial (PR gate) | partial (docs) | partial |
| Impact analysis / dependency traversal | ✓ declared propagation per relationship type | — | — | — | — | ✓ |
| Roadmap / target-state planning | ✓ ArchiMate plateaus, gated (PLAT*) |
— | — | — | — | ✓ |
| Regulatory reporting (DORA Register of Information) | ✓ generated from the model, gaps named in the document, explicitly not an attestation | — | — | — | — | partial |
| Reference-architecture alignment | ✓ hash-pinned taxonomy, gap per node, exclusion needs a rationale | — | — | — | — | ✓ (content bundled) |
| Application rationalization / duplicate-functionality detection | ✓ derived from realization edges, printed with each realizer's portfolio properties; never auto-concluded | — | — | — | — | ✓ |
| Technology-debt sizing and costing | ✓ exposure derived, priced only by the operator's own rates; the total names what it left out | — | — | — | — | ✓ |
Verified against the 2026-07-29 competitive survey behind
docs/BLUEPRINT.md; the ea-skills column reflects this
repository as of 2026-08-07. Neighbours move fast, so this table carries a standing
obligation: re-check monthly, and correct it when a claim stops being true — it is
tracked as an open item below and in BLUEPRINT §8a, because no
test can check a competitor's changelog. Each capability exists somewhere; the
integration is the contribution, and the governance end is where it is thinnest
elsewhere.
If a row is wrong about your project, please open an issue and it will be corrected.
Every — here means not found in that project on the survey date, which is a statement
about one afternoon's reading and not about the project's intent or roadmap. The dates
above are in the table so that a stale claim can be recognised as stale rather than
argued with.
Phases 0–7 are complete — see CHANGELOG.md for the full history and BLUEPRINT §8a for per-phase design decisions.
| Phase | Scope | Status |
|---|---|---|
| 0 | Deterministic core: DSL, three-layer validator, Open Exchange compiler, oracle pinning | done |
| 1 | Intake: fact register with verified quotes, chunker, coverage, clarification questions | done |
| 2 | Modelling: capability map as spine, overlay staging, gated promotion, motivation layer | done |
| 3 | Documentation: ISO 42010 loop, SVG rendering, generated architecture description | done |
| 4 | Governance & maintenance: SIB, dispensations, ADRs, compliance, health reports, agent context packs | done |
| 5 | Evaluation: golden-set regression harness, capability comparison | done |
| 6 | Service layer: offering catalog with SLAs, demand ledger, demand-weighted maintenance | done |
| 7 | Reference, regulation, proposal: alignment to reference architectures, per-layer readiness, rationalization, cost, regulatory reporting, generated proposals, maturity | done |
Deliberately open (decisions, not backlog): the network facade (MCP/HTTP) over the
read-only commands stays deferred until the demand ledger shows someone asking for it —
ea-check shipped without it, and needs no service to run; §6.9 correspondences to AD
elements in another architecture description stay underived, because nothing here can
check the far end of one; the comparison table above carries a monthly
re-check obligation that nothing can automate; and the worked example carries
scheduled failures (a dispensation expiring 2027-06-30, a staleness horizon in
mid-2027) as maintenance rehearsals — renewing the records, not weakening the gates,
is the drill.
easkills/ deterministic tooling (oracle, DSL, validators, compiler, renderer,
docgen, governance, correspondences, impact, roadmap reports,
reference packs and alignment, exchange importer, CSV intake,
context packs, scorer, CLI)
oracle/ vendored, hash-pinned rule data + NOTICE.md
references/ the open reference-model library adopters copy from (public domain /
public law only -- licensed models live in the adopter's repository)
schema/ JSON Schemas -- all generated, never hand-edited
skills/ the 25 agent skills (this is the product)
template/ scaffold to copy for a new enterprise
eval/example/ worked example, clean (doubles as the largest golden case)
eval/golden/ golden-set cases for the regression harness
eval/harness/ the skill-prose harnesses: scored runs + governance contracts (API key,
never in the default gate -- the only code here that reaches a network)
eval/fixtures/ negative fixtures -- every rule violated on purpose, proven by tests
tests/ pytest suite: the gates, the generators, and the claims these docs make
docs/ GETTING-STARTED, CLI reference, RULES catalogue, BLUEPRINT (design)
| Document | What it covers |
|---|---|
| Getting started | Tutorial: from a raw interview to a validated, documented architecture |
| CLI reference | Every command, flag and exit-code contract |
| Rule catalogue | All 146 validation rules with severities and rationale |
| Blueprint | The research-verified design: decisions, evidence, per-phase log |
| Golden set | How pipeline quality is measured |
| Skill coverage | Which instrument measures which skill — including where nothing does |
| Contributing | Dev setup, conventions, how to add a rule or a skill |
Contributions are welcome — the conventions are strict but few, and every one of them is enforced by a test rather than a review comment. Start with CONTRIBUTING.md; the short version:
- every new validator rule ships with a negative-fixture case, a RULES.md row and a test;
- generated artifacts (schemas, example docs) are regenerated in the same commit;
- gold's authored content never changes in the same commit as skill changes (its
generated
eval/example/docs/regenerates with the tooling — that is convention 2); - the worked example stays at zero findings, warnings included.
python -m venv .venv && .venv/Scripts/python -m pip install -r requirements.txt
.venv/Scripts/python -m pytest tests -q # the suite
.venv/Scripts/python -m easkills oracle-info # oracle version + pin statusMIT for the code and documentation authored here — see LICENSE. Third-party
material distributed alongside it keeps its own terms, and NOTICE.md names
every case: the oracle vendored under oracle/ (detail in
oracle/NOTICE.md), the openly licensed packs under
references/, and the standards this repository implements without
reproducing.