living-architecture

A Claude Code plugin (la) plus its command-line tools that keep agent-written code from drifting into spaghetti, and keep each change on a reviewed plan.

• An architecture that is enforced, not just drawn. A LikeC4 model maps nodes to code modules, and its arrows decide which module may import which. la-arch-check measures the real imports against the model. Grandfathered arrows are marked #legacy and only ever shrink. Each node carries arc42 principles with status tags, and agents treat the model and the principles like tests: changes need your approval.
• A four-stage PR flow. /la:pr interviews you into a Codex-reviewed OpenSpec plan, writes the failing tests, implements until they pass, and then loops CI, Codex, CodeRabbit and Sonar reviews until every gate is clean. Each stage resumes from the branch name alone, and the plan is archived with the code.
• Refactoring without import churn. Python and TypeScript moves and renames rewrite every import automatically, and the type checker proves nothing was left dangling.

The longer version is in Living architecture, explained.

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.3.1      # Python repos
npm install -g living-architecture@0.3.1        # TypeScript/JavaScript repos (Node >= 22)

The commands ship as two twins with one contract: a PyPI package and an npm package of the same name. 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.

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 model with /la:arch-init. After that, start each change with /la:pr on a branch named after its issue.

Skills

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

Languages

A repo's languages are those with a root marker (pyproject.toml/setup.py; tsconfig.json) and source files, or a commands.typecheck entry, which a language needs when its marker is not at the root (like the web/tsconfig.json below); la-config get languages lists them. The architecture model declares one section per language in architecture/index.yaml, and a mixed repo has both:

python:
  root_package: mypkg                 # the package the python root maps to
  source_root: src                    # optional
typescript:
  root_package: src                   # the directory the typescript root maps to
  source_root: web                    # optional
  tsconfig: web/tsconfig.json         # optional: default the nearest tsconfig.json
legacy_arrows: {baseline: 0}

Pin the architecture check in CI to a release, in your ecosystem's form:

# Python
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- run: uvx --no-build --from living-architecture==0.3.1 la-arch-check
# TypeScript
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- run: npx -y -p living-architecture@0.3.1 la-arch-check

Prerequisites

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

Per repo language (la-doctor checks them):

Per gate, as living-architecture.yaml enables it:

Documentation

• Living architecture, explained
• Skills: main and helper skills
• Configuration: living-architecture.yaml
• Commands: the la-* and dr-* commands, and CI
• Deterministic refactoring
• Development: working from a checkout, layout, releasing