guarding-architecture skill (riekelt): named invariants with a build-failing guard

Makes Claude treat module boundaries as named rules with a written reason and a test that fails the build.

Installs: 20.3K; on skills.sh
Stars: 7; on GitHub
Updated: Sep 2026; last repo commit

guarding-architecture applies when a change crosses module boundaries, adds a dependency direction between modules, touches a critical path, or conflicts with a stated principle. It asks for every structural invariant to have a name, a written rationale and a mechanical guard, such as an architecture test that fails the build. A design that violates a named invariant is redesigned, and a genuine exception is proposed as an amendment instead of argued into a spec. It names principal-engineering as required background.

Good for

Teams with layering or dependency-direction rules that keep eroding
Architects who want invariants written down with their rationale
Developers whose Claude changes cross module boundaries

Install guarding-architecture

Claude Code

Copy this prompt.

Install the guarding-architecture skill in Claude Code. Run this command:

/plugin marketplace add riekelt/principal-engineer
/plugin install principal-engineer@principal-engineer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The plugin installs all 11 skills in the repo, plus one agent (change-verifier) and two commands (/verify and /preflight), counted from the git tree. guarding-architecture names principal-engineering as required background, so the skills CLI and folder routes below install both. There is no Claude app upload route: the README documents only the Claude Code plugin and the other-agents routes.

From the project README. Source.

What's in the skill

When it loads

Use when a change crosses module boundaries, adds a dependency direction between modules, touches a critical path, or conflicts with a stated principle - and when writing or updating architecture principles themselves. Encodes structural invariants as named, enforced contracts: statement, rationale, guard. Use whenever "we'll just import it from there for now" appears, which is how boundaries die.

Sections in SKILL.md

Overview
The pattern
Common invariant classes
Common mistakes

Key facts

Author: riekelt (named as author in the plugin manifest)
License: MIT per the README and plugin.json; the repo has no LICENSE file and GitHub shows none
Installs on skills.sh: 20,345 (Nov 2, 2026)
GitHub stars: 7 for the whole riekelt/principal-engineer repo (Nov 2, 2026)
Last repo commit: Sep 11, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 1 file: SKILL.md (counted from the git tree)
Part of: The principal-engineer plugin: 11 skills, 1 agent and 2 commands (counted from the git tree)
Needs: The principal-engineering skill, named as required background in SKILL.md
Works in: Claude Code via the plugin; other agents via a plugin loader or symlinked skill folders, as the README describes

What it includes

Numbered and citable, each with a statement, rationale and implications
The rationale is a concrete failure narrative, told from an incident.
Write · Name the invariants
Principles in one document, their current realization in a companion
When the two disagree, the invariant governs and the realization document gets corrected.
Write · Split stable from volatile
Adds architecture tests that fail the build for each enforceable invariant
Dependency directions, package boundaries, layering and forbidden imports. What cannot be build-enforced becomes a named review check.
Runs code · Enforce mechanically
A design that breaks a named invariant is redesigned, not justified
Watering the contract down to match nonconforming code is the banned move.
Read · Violations mean redesign
A design on guarded ground shows how it upholds each invariant
The reviewer checks claims against named invariants instead of debating taste.
Write · Specs show conformance
Proposes an amendment, or a dated waiver with an expiry and owner sign-off
Silent exceptions are how an invariant becomes a suggestion.
Write · Exceptions are amendments
Surfaces an unexplained exclusion to the invariant's owner
Extending an exclusion list "like the others did" ratifies erosion.
Read · Unexplained guard exclusions
Five examples: one owner, dependency direction, hot path, fail-closed, migrations
Offered as examples rather than mandates.
Read · Common invariant classes

From the official docs

Permissions

Low risk

guarding-architecture is instructions for Claude and the plugin route adds an agent and two commands. Our advice: review the diff after each session and keep your tool's permission prompts on.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can add checks that fail your build
SKILL.md says each enforceable invariant gets an architecture test that fails the build. Review new guard tests before you merge them. github.com
The plugin route adds an agent that can run shell commands
change-verifier lists the tools Read, Glob, Grep and Bash, and the plugin adds the /verify and /preflight commands. The repo tree has no hooks or MCP config files. Use the skills CLI route to install only this skill. github.com

Technical details

Turning on read-only	SKILL.md describes no read-only mode.
Sign-in and keys	SKILL.md names no account, key or token.
Scopes	Claude writes architecture tests and principle documents in your repository The plugin route also installs 10 other skills, one agent and two commands

Questions

What does guarding-architecture do?

It makes Claude treat structural rules as named invariants. Each gets a written reason and a guard, ideally a test that fails the build, and a design that breaks one is redesigned instead of excused.

How do I install it?

Use the install box at the top. The skills CLI and folder routes add principal-engineering as well, because this skill names it as required background. The plugin route installs all eleven skills.

Can I still make an exception?

Yes, in one form. SKILL.md says a genuine exception proposes an amendment that names the invariant and the boundary of the bend. A temporary exception is a dated waiver with an expiry condition and the owner's sign-off.

Does it add tests to my build?

It tells Claude that every enforceable invariant gets an architecture test that fails the build. That means Claude may add checks that can fail your CI, so review them like any other test.

Does it work in the Claude app or Codex?

The README documents the Claude Code plugin and, for other agents, a plugin loader pointed at plugins/principal-engineer/ or symlinked skill folders. It documents no Claude app upload route.

Is it safe to install?

The skill folder bundles no scripts. It can lead Claude to add architecture tests and write principle documents in your repository. The plugin route also adds an agent, covered under "Watch out for".

Information

updated Nov 2, 2026

Repository: riekelt/principal-engineer
Folder: plugins/principal-engineer/skills/guarding-architecture

riekelt/principal-engineer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

guarding-architecture SKILL.md · github.com
principal-engineering SKILL.md · github.com
README · github.com
plugin.json · github.com
change-verifier agent · github.com