Quick start

Your first Transitrix artefact — a Goals tree rendered from a YAML file — in a few minutes.

Two ways in. Starting fresh — create a new repository for your organisation. Or joining — your organisation already has a Transitrix repository and you want to start contributing. Either way, install the two viewers first.

Install the viewers

Transitrix diagrams are plain text. Two editor extensions render them live as you type — together they cover every layer of one model, from the board to the developer:

One model, every layer. Studio renders the business-facing layers with purpose-built notations that go beyond generic diagramming — its BPMN, process and activity views, not stripped-down Mermaid copies. Mermaid then renders the technical layers Transitrix doesn't specialise — both from the same plain-text model, so a single source serves the board and the developer alike. And nothing is locked in: Transitrix is built on open standards (ArchiMate 3.2, BPMN 2.0), the technical views are standard Mermaid that renders in any tool, and the files stay diffable text on an open, MIT-licensed methodology — readable with or without us.

Starting fresh — a new repository

Scaffold a repo and author your first artefact: a Goals tree rendered from a .goals.transitrix.yaml file. Two ways.

The fast path — onboarding Skill

Requires Claude Code with access to the Claude marketplace. In a Claude Code session:

/plugin marketplace add transitrix/methodology
/plugin install transitrix@transitrix-methodology
/transitrix:onboard

The Skill asks what you want to model first, scaffolds the repo layout (canon/, field/, codex/), and authors a starter Goals tree file. Open it in VS Code — the diagram renders alongside as you type.

The manual path

No Claude Code required — and no public GitHub access needed.

  1. Open VS Code in a new empty folder (Studio installed — see above).
  2. Create the file views/goals/HELLO.goals.transitrix.yaml.
  3. Paste this into it: 
    notation: goals
spec_version: "0.1"

id: GOALS-HELLO-1
name: "Hello — Goals Tree"
description: "A starter Goals tree."
period: "2026"
version: "0.1"
date: "2026-01-01"
author: Me

goal_types:
  - { name: "Strategic Goal", level: 0 }
  - { name: "Tactical Goal",  level: 1 }

goals:
  - id: GOAL-1
    name: "Expand into new markets"
    type: "Strategic Goal"
    level: 0

  - id: GOAL-1-1
    name: "Enter the German market by Q3"
    type: "Tactical Goal"
    level: 1
    parent: GOAL-1

  - id: GOAL-1-2
    name: "Sign two distribution partnerships"
    type: "Tactical Goal"
    level: 1
    parent: GOAL-1

  - id: GOAL-2
    name: "Improve customer retention"
    type: "Strategic Goal"
    level: 0

  - id: GOAL-2-1
    name: "Reduce churn by 20% in H2"
    type: "Tactical Goal"
    level: 1
    parent: GOAL-2
  4. Studio renders the Goals tree in the preview panel. Edit a goal name — the diagram updates live.

To validate from the command line (requires npm): npx @transitrix/cli validate views/goals/HELLO.goals.transitrix.yaml

Joining a repository your organisation already has

Someone on your team has already set up the model. You don't scaffold anything — you clone it, watch it render, and make your first change like any other contribution.

  1. Clone the repository and open it in VS Code (both viewers installed — see above): 
    git clone <your-org-repo-url>
  2. Open any .transitrix.yaml file under canon/ or views/. Studio renders your organisation's real diagram beside it.
  3. Read AGENTS.md at the repository root — the orientation guide the repo ships with: where each zone lives (canon/, field/, codex/), which notations are in use, and the local conventions.
  4. Make a change — edit an element or add one — then validate it: 
    npx @transitrix/cli validate <file>
  5. Open a pull request. Architecture changes are reviewed like code, and the repository's CI re-runs validation on every PR.

That's the whole loop — clone, render, change, validate, PR — the same review-as-code workflow your team already uses for source.

What's next