# guarding-architecture

Enforces system boundaries by turning structural invariants into breaking build tests. Useful when code crosses module limits or adds unwanted cross-package imports.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 18000 installs · ★ 6
- Author: riekelt
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/guarding-architecture/SKILL.md
- Updated: 2026-09-11
- HTML: https://affpapa.org/en/nevibecode/skills/guarding-architecture

## What it does

The skill requires the `principal-engineering` skill as a prerequisite. It instructs the agent to treat invariants as strict contracts with an incident-backed rationale and automated guards. Rules kept only in memory get forgotten. Here they must break the build on forbidden imports or layer violations.

System definitions stay split in two parts. Core principles stay in a stable document free of class names, while implementations and tests live in an accompanying file. If code clashes with an invariant, the design must change. Weakening contracts to match nonconforming code is strictly disallowed.

Exceptions exist only as documented amendments or dated waivers with expiry criteria and owner sign-off. Bypassing a guard without an explicit waiver is treated as a hidden defect.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill guarding-architecture -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/guarding-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/guarding-architecture/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill guarding-architecture -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/guarding-architecture/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill guarding-architecture -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/guarding-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install riekelt/principal-engineer guarding-architecture
```

2. **Manually: put the files in place**
- File: `.github/skills/guarding-architecture/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill guarding-architecture -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/riekelt/principal-engineer --path plugins/principal-engineer/skills/guarding-architecture
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/guarding-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill guarding-architecture -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/guarding-architecture/SKILL.md

## When to use it
- convert architectural conventions into automated build tests
- prevent forbidden cross-package imports and circular dependencies
- isolate the hot path from slow I/O operations
- document structured temporary waivers with explicit expiry dates

## Example prompts
- Check if this new dependency direction violates domain isolation rules.
- Write an architecture test preventing the core module from importing web transport packages.
- Create an amendment proposal for this boundary exception with owner sign-off.

## Similar
- [architecture-compass](https://affpapa.org/en/nevibecode/skills/architecture-compass.md) — skill · 2700 installs
- [clean-architecture](https://affpapa.org/en/nevibecode/skills/pproenca-clean-architecture.md) — skill · 2000 installs
- [architecture-review](https://affpapa.org/en/nevibecode/commands/architecture-review.md) — command · 3419 installs
- [roblox-architecture](https://affpapa.org/en/nevibecode/skills/roblox-architecture.md) — skill · 2000 installs
- [architecture-optimization](https://affpapa.org/en/nevibecode/skills/architecture-optimization.md) — skill · 1300 installs
- [codebase-architecture](https://affpapa.org/en/nevibecode/skills/codebase-architecture.md) — skill · 441 installs

From the same set: [riekelt/principal-engineer](https://affpapa.org/en/nevibecode/by/riekelt/principal-engineer.md) — 9 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md