A Goals tree rendered from the worked example.
Open methodology and tools to describe an enterprise as text — and let humans and machines run it together.
Just want to see a diagram render from text? You don't need the methodology for that. Install Transitrix Studio, write a few lines of text, and watch it draw — about 5 minutes, no repository, no setup. → Draw a diagram → Transitrix Studio
Setting up an architecture repository for a team or company? You're in the right place. Start with the Quick start below.
Transitrix is a lightweight, Git-native methodology for representing and managing enterprise architecture as text. Models, processes, capabilities, goals, and architectural relations live as YAML files in a repository. Diagrams, dashboards, and reports are derived from those files automatically.
It builds on ArchiMate 3.2, BPMN 2.0, and the Capability Maturity Model, and adds value at the layer above: how the model is stored, versioned, validated, rendered, and acted upon by both humans and software agents.
License: MIT.
Transitrix is the foundation for an Enterprise Memory — a durable, EA-grounded store of organisational knowledge that humans and AI agents share and reason over, built on a formal model rather than free-form notes or opaque embeddings. → Enterprise Memory deployment guide (personal-scale second brain and enterprise-scale Knowledge Store).
The fastest way in is the onboarding Skill — it scaffolds a clean zoned repo and walks you through your first model file. Paste this into any coding agent — Claude Code, Cursor, Copilot Chat, Gemini CLI:
Fetch and follow
https://raw.githubusercontent.com/transitrix/methodology/main/transitrix/skills/onboard/SKILL.md
— for any templates/<file> path it references (incl. ${CLAUDE_SKILL_DIR}/templates/<file>),
fetch it instead from
https://raw.githubusercontent.com/transitrix/methodology/main/transitrix/skills/onboard/templates/<file>
The skill asks what you want to model first, scaffolds the canon/ + field/ + codex/ layout, and authors a starter file with validation for whichever notation fits — a Goals tree is a common starting point, the simplest notation to start from, but any notation is a valid first artefact.
Using the Claude Code plugin workflow instead? Same result, from the terminal claude CLI:
/plugin marketplace add transitrix/methodology
/plugin install transitrix@transitrix-methodology
/transitrix:onboard
Prefer to do it by hand, or not working with a coding agent? Follow the manual walkthrough in GETTING_STARTED.md — create and validate a one-goal tree, then explore the worked transitrix/acme-corp example. To validate as you go, install Transitrix Studio (VS Code) for live preview, or run npx @transitrix/cli validate <file> (on Windows PowerShell, use npx.cmd — see Validation).
New to the ideas behind it? Read method/01-foundations.md for the why — but you don't need it to start.
GETTING_STARTED.md— a first modelling session, step by step, illustrated against theacme-corpworked example.WALKTHROUGH.md— a guided tour of theacme-corpworked example, read as one story.notations/CONVENTIONS.md— ID grammar, naming, and best-practice checklist for authoring canon content.patterns/— Concrete deployment patterns for common scenarios (Transitrix Alone, Knowledge Store, Network Catalogue, ADR Registry, MCP Server exposure, Enterprise Memory, Personal Memory, Baseline & Audit Trail).patterns/implementation-tiers.md— two implementation tiers (Simple / Full): what belongs in each, where the boundary sits, and how the upgrade path works.
- Desktop model workplace — Qualified read-only setup paths for ChatGPT Desktop and Claude Desktop, with connection and evidence checks.
- Repository MCP for enterprises — Recommended scoped access, compatible assistant modes, deployment choices, and acceptance scenarios.
method/— the methodology itself, one file per reader question, numbered in reading order:00-glossary.md(terminology) ·01-foundations.md(what/why) ·02-repository.md(layout) ·03-modelling.md(elements/relations) ·04-notations.md(the notation kit) ·05-working-the-model.md(change lifecycle, validation) ·06-team-operations.md(a team's own decisions/work) ·07-decisions.md(the ADR record + multi-repo aggregation) ·08-governance.md(who may change what, what gates it) ·09-releases-and-propagation.md(how a new version reaches you, including catalogue integration).- Adopter guides — recommendations, proposals, and task and component procedures that don't fit the reading order above (unnumbered — a menu, not a sequence): modelling capabilities, modelling complex processes, adopting the Architecture Decision Log, how a release records the systems it was assembled on, how a model-backed document prints, how a model-backed document is versioned, how to preserve issued document versions.
notations/README.md— the canonical notation index;notations/CONTRACT.mdand the per-notation specs are the authoritative source for the model in detail.notations/views/documents/DIRECTIVE_LANGUAGE.md— the.ttrsdocument source format: one directive language shared by every document kind (mrd,srs,sdd,sds, …, the middle segment of<basename>.<kind>.ttrs). Canonical public explanation: transitrix.com/ttrs.transitrix/templates— forkable starter templates (RACI, …): fork, edit for your own organisation, validate.
Process & releases:
CHANGELOG.md— release history (Keep a Changelog; SemVer pernotations/CONTRACT.md§10).RELEASING.md— per-release operational checklist for the maintainer.NOTATIONS_AUDIT.md— maintainer audit of open shape decisions a linter can't make.migrations/— per-release migration recipes.
Tooling:
integration/studio.md— how to use Transitrix Studio (the reference VS Code extension and CLI for editing all Transitrix custom formats).integration/plantuml.md— adopter guide for the supplementary.pumldiagram workflow (sequence, component, deployment, …).integration/tooling.md— broader tooling and ecosystem notes.integration/ci-example.yaml— CI template that gates pull requests on validation.transitrix/— the Claude / Copilot Agent Skills plugin (skills/onboard/,skills/ingest/, …).packages/— versioned tooling packages, e.g.@transitrix/ingest-cli.scripts/— repo-level doc-lint scripts.
Per-organisation:
organizations/<org>/README.md— organisation overview.organizations/<org>/GETTING_STARTED.md— onboarding.organizations/<org>/CONVENTIONS.md— local naming overrides.organizations/<org>/.templates/EXAMPLES.md— worked examples.
The repository has three buckets:
- Spec — what adopters consume:
notations/(CONTRACT, IDS_AND_REFERENCES, ELEMENT_PRIMITIVES, MANIFEST, COVERAGE_PROFILES, plusviews/,elements/,examples/),method/(includingmethod/00-glossary.md),guides/(task procedures),migrations/. - Worked example — a sample organisation to learn from, maintained as a standalone reference repo:
transitrix/acme-corp. Path references elsewhere in this repo of the formorganizations/acme_corp/...point into that repo — clone it toorganizations/acme_corp/locally to follow them verbatim, or browse it directly on GitHub. - Tooling — what you install or run:
transitrix/skills/(Agent Skills — onboard, ingest),packages/(CLIs — e.g.@transitrix/ingest-cli),integration/(Studio / CI),scripts/(doc-lint).
See Documentation above for the full list of root-level files and what each is for.
- The architecture is YAML files in Git — atomic elements and atomic relations, separated.
- Linters enforce syntax, atomicity, referential integrity, and policy on every commit. Type and layer rules are available via
@transitrix/cli --scope=repo. - Transitrix Studio is the reference editor — a VS Code extension and CLI that handles every Transitrix custom format.
- Diagrams are rendered by a shared OSS library (
@transitrix/diagrams) so the same picture appears in Studio, in DSM, and in any other host. - Every change goes through a pull request. Code review = architecture review.
Transitrix defines text-native notations for the most common enterprise-architecture artefacts — process diagrams (BPMN), goals trees, capability maps, the DGCA strategy chain, action networks, process maps, blocks, products and applications catalogues, scenarios, issues, and process blueprints — plus element notations for the codex, requirements, assertions, relations, actors, and stakeholders. Each view notation has a *.<short-name>.transitrix.yaml extension and a notation: header.
See notations/README.md for the canonical index of every notation — short names, file extensions, and spec-maturity status (draft / documented / stable) — and method/04-notations.md for the rationale. The catalogue is not duplicated here, to keep a single source of truth.
Transitrix separates validation by responsibility — view notations, element primitives, relations, and repo structure. As you author, a single view file validates inline in Transitrix Studio (on save) or with npx @transitrix/cli validate <file>. All canonical *.<short-name>.transitrix.yaml extensions are accepted without --ext; pass --ext <notation-name> only for a non-canonical extension outside the built-in registry. On Windows PowerShell with a restricted execution policy (the default on many workstations), invoke as npx.cmd @transitrix/cli validate <file> — the unsuffixed npx resolves to a .ps1 wrapper that the policy refuses to launch. Across the whole repository, the model-integrity linter .validators/lint.py runs the element/relation/structure checks — atomicity (no relations inside element files), referential integrity (every relation endpoint exists), and policy (Active status requires an owner; deprecated elements reference successors) — over canon/ and gates pull requests in CI. Type and layer rules are available via npx @transitrix/cli --scope=repo. See integration/ci-example.yaml for the pipeline.
| Pattern | Structure |
|---|---|
| Single organisation | organizations/my_company/ with full structure |
| Multiple business units | organizations/group/, organizations/bu_a/, organizations/bu_b/ |
| Multi-tenant SaaS | organizations/customer_*/, organizations/shared_infrastructure/ |
| Advisory / portfolio | One repo, one organisation per portfolio company |
Each organisation is structurally isolated. They share methodology, validators, and templates; they don't share state.
Transitrix — including the DGCA notation that forms part of it — is authored by Valerii Korobeinikov. The methodology is published under the MIT license as open documentation. Contributions are welcomed — see CONTRIBUTING.md.
Contact: hello@transitrix.com
Work for this repository is filed in transitrix/transitrix-hq, not in this repository's issue tracker. That repository is private; if you'd like to contribute or report feedback, open a pull request here or email hello@transitrix.com.
Methodology status: 1.0 (stable) — see CHANGELOG.md for the current release and notations/CONTRACT.md §10 for the compatibility policy.
Last updated: 2026-07-05