living-architecture

A Claude Code plugin + CLI for agents writing Python and TypeScript code

• Normative principles attached to a LikeC4 architecture model, which also serves as an import whitelist.

• Enforced by a complete PR workflow that generates OpenSpec changes, whose archives double as ADRs.

Introduction

Every PR an agent writes can be reasonable on its own while the codebase still drifts, one random decision at a time. Putting every rule for every component into CLAUDE.md bloats context to the point where they are all ignored anyway. Random agent decisions from one PR are treated as design patterns by the next session, with the codebase gradually growing bizarre structure no one wanted. And six months later, nobody can say why the code is the way it is.

The plugin, la, prevents architectural drifts via these interlocking components:

• Principles attached to the parts of your code. A LikeC4 model maps your packages to elements, and each element carries its own arc42 file of normative principles, each tagged with how it is enforced. Every stage of a change starts by reading the principles of what it touches, and changing a principle needs your approval.
• A complete PR workflow. /la:pr interviews you into a Codex-reviewed plan, writes the failing tests, implements until they pass, then loops deterministic checks (lint, typing, share of comment lines in the code, and more), CI, Codex, CodeRabbit and Sonar until every gate is clean. Each stage ends at a hard stop and resumes from the branch name alone.
• A decision record for every PR. The plan is a validated OpenSpec change. Before the PR merges, it is archived in the same PR as the code, with the decisions and the alternatives rejected: an ADR you never had to write.
• An architecture that is enforced, not just drawn. The model's arrows are also a whitelist for which modules can import which, and la-arch-check fails when the real imports disagree.

For the details, see How it works and Living architecture in questions and answers.

For an example of a project using this, look at SLayer, here is a juicy example of a real-world principles document.

Install

# the plugin
/plugin marketplace add MotleyAI/living-architecture
/plugin install la@living-architecture

# the commands (la-*, dr-*), pinned to the same version as the plugin, from your repo's ecosystem
uv tool install living-architecture==0.5.0      # Python repos (Python >= 3.11)
npm install -g living-architecture@0.5.0        # TypeScript/JavaScript repos (Node >= 22)

The commands come as a PyPI package and an npm package of the same name, with identical behaviour. Each serves its own ecosystem natively, needs nothing from the other in a single-language repo, and calls the other for the other language's files in a mixed repo (details). Skills check that the installed commands match the plugin before they run; a plugin update within the same minor version needs no reinstall.

living-architecture.yaml records the repo's format version. After an upgrade that changes the format, most commands refuse to run on the repo until you run la-arch-migrate once, and la-doctor says so.

Quick start

In the repo you want to onboard, run:

/la:init

It detects your tracker, test, lint and type-check commands, Codex, Sonar and any existing OpenSpec or architecture setup, then proposes a living-architecture.yaml and asks only about what it cannot detect. It then offers to set up OpenSpec, record the type-check baseline and build the architecture with /la:arch-init, which starts from a model measured from your code and then interviews you about the target structure and the principles.

Just enforce the architecture

You don't need the PR workflow or OpenSpec to hold an agent to the model and its principles: decline OpenSpec in /la:init, which will ask you to build the model with /la:arch-init; then point the agent at the

/la:living-architecture

skill, for example in your CLAUDE.md or AGENTS.md.

The skill has the agent read the principles of every part of the code it touches before changing it, and run three checks before it finishes: la-arch-check holds the imports to the model's arrows and checks the principles' tags, likec4 validate checks the model itself, and la-typecheck runs basedpyright (or tsc) against a baseline that only shrinks.

To run the same checks in CI, see Running the checks in CI.

Use the PR workflow that enforces architecture and creates OpenSpec

Start each change on a branch named after its issue with:

/la:pr

This will guide you through each of the stages of the PR workflow; at the end of each stage it will tell you to call /clear and start the next stage by calling /la:pr again.

Skills

Skill	Purpose
la:init	Onboard a repo: detect its tools, write living-architecture.yaml, then set up OpenSpec and build the first architecture model and its principles with la:arch-init
la:pr	Run a change through plan → failing tests → implementation → review
la:deterministic-refactor	Rename or move Python or TypeScript code, proven complete by the type checker

These skills call helper skills that you can also run on their own; see Skills.

How it relates to other tools

• Import-boundary checkers (import-linter for Python; dependency-cruiser, eslint-plugin-boundaries and Nx module boundaries for TypeScript) check imports against rules in a config file. In la the rules are the same diagram the agent reads, they must match the code in both directions, one model covers Python and TypeScript, and the import law is only the backbone that the principles and the specs hang on. If all you need is layer rules for one language, those tools are lighter.
• OpenSpec on its own gives you the spec format and the archive. la drives it: the plan stage writes and validates the change, the later stages hold the code to it, and the review stage archives it with the PR.
• ADRs written by hand tend to stop being written. Here the decision record is a by-product of planning the change, so every PR has one.

Prerequisites

Always: git, bash, gh (authenticated) and jq.

Per repo language (la-doctor checks them):

Language	Needs
Python	Python >= 3.11; the PyPI package; basedpyright in the project env for the type-check gate
TypeScript	node (>= 22) and npx; the npm package; tsc in node_modules for the type-check gate

The rest is optional. /la:init detects what you have, asks before turning on anything it can't find, and records the choice in living-architecture.yaml:

Gate	Needs
tracker: linear	the Linear MCP server
tracker: github	nothing beyond gh
openspec: true	npx (the OpenSpec CLI)
architecture: true	npx (the LikeC4 CLI)
reviewers.codex: true	the Codex MCP server (mcp__codex__codex)
Sonar on your PRs	the SonarQube MCP server

Background

The ideas behind the plugin, and how it came out of the SLayer codebase, which uses it:

• Why I no longer read code (much): the four-stage PR flow
• How I enforce architecture on coding agents: modularity and principle-based development
• Living architecture, enforced: the LikeC4 import law and the arc42 principles

Documentation

• How it works: the principles, the PR workflow, its ADRs and the import check, and how to use the check on its own
• Living architecture in questions and answers: the problems it solves, one by one
• Skills: main and helper skills
• Configuration: living-architecture.yaml and the language sections of architecture/index.yaml
• Commands: the la-* and dr-* commands
• Running the checks in CI
• Deterministic refactoring
• Development: working from a checkout, layout, releasing
• Contributing and release notes