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.4.1      # Python repos (Python >= 3.11)
npm install -g [email protected]        # 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.

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.

After that, 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

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):

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:

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, and CI
• Deterministic refactoring
• Development: working from a checkout, layout, releasing
• Contributing and
  release notes