@riekelt/guarding-architecture
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.
Principal engineer
Engineering discipline as skills: the judgment layer for coding agents, distilled from conventions used across my own repositories. Evidence over theory, failures that cannot pass silently, one home per fact, verification as the definition of done, and fixes that never outgrow their trigger.
One core skill holds the hard rules, the risk tiers, and the routing; ten discipline skills build on it.
| Skill | Use when |
|---|---|
| principal-engineering | Any non-trivial engineering work. The foundation: the pre-change checkpoint, the hard rules, the rule lifecycle. |
| grounding-before-coding | Starting a change, a debug, or work in unfamiliar code: map the real code and data first, never guess conventions. |
| handling-failures | Any error path, catch block, fallback, or default: the no-silent-swallows contract. |
| keeping-one-source-of-truth | Adding data, config, state, or anything that could exist twice: derive rather than store, absorb duplicates. |
| verifying-before-done | About to say done, fixed, or passing: drive the change at its surface, run the proof, distrust green suites, own failing gates. |
| operating-safely | Deleting, overwriting, restarting, secrets, live systems, concurrent sessions: the destructive-op guards, secrets hygiene, operator-owned process lifecycles. |
| scoping-changes | Sizing a fix, drifting scope, "while you're at it": size to trigger, decompose instead of descoping. |
| testing-changes | Deciding what tests a change owes, or the test diff is empty: tests move with behavior, the bug-regression pattern, discriminating assertions. |
| writing-unit-tests | Writing or fixing a unit test, or a test is flaky or unreadable: behavior not implementation, names as claims, determinism, mock policy. |
| guarding-architecture | Crossing module boundaries or touching stated principles: named, enforced invariants with statement, rationale, and guard; violations mean redesign. |
| adding-dependencies | Adding, updating, vetting, or removing a package, library, or base image: the exhaust-what-you-have ladder, posture declarations, pin-and-prove updates. |
The technical-writer plugin governs the documents around the work (specs, decisions, changelogs, runbooks, postmortems, issues). These skills govern the engineering itself and defer to technical-writer for the prose.
Agents and commands
Beyond the skills, the plugin ships one subagent definition and two commands (Claude Code; other platforms load what they support):
| Component | What it does |
|---|---|
change-verifier agent |
Independent verification of a completion claim: diff versus claim, drive the surface, probe beside the change, then the gates, sweep the blast radius. Never fixes what it finds. |
/verify [claim] |
Dispatches a change-verifier on the current claim and relays VERIFIED, CONTRADICTED, or UNVERIFIABLE unaltered. |
/preflight [task] |
Fills the pre-change checkpoint (Grounded, Blast radius, Invariants, Verify) from the real repository before the change starts. |
Install
Claude Code:
/plugin marketplace add riekelt/principal-engineer
/plugin install principal-engineer@principal-engineer
Other agents: point the platform's plugin loader at plugins/principal-engineer/, or symlink the directories under plugins/principal-engineer/skills/ into the agent's skills directory.
Repository layout
package.json # version stamped by the release
CHANGELOG.md # generated by semantic-release
.claude-plugin/marketplace.json # Claude Code marketplace manifest
.agents/plugins/marketplace.json # generic agents marketplace manifest
.github/workflows/release.yml # semantic-release on push to main
.releaserc.json # release config; stamps versions into package.json and the plugin manifests
plugins/principal-engineer/
agents/ # change-verifier subagent definition
commands/ # /verify, /preflight entry points
.claude-plugin/plugin.json # per-platform plugin manifests
.codex-plugin/plugin.json
.cursor-plugin/plugin.json
evals/evals.json # persisted pressure-test prompts
evals/trigger-evals.json # persisted trigger-firing prompts
skills/
principal-engineering/ # core: checkpoint, hard rules, routing
grounding-before-coding/
handling-failures/
keeping-one-source-of-truth/
verifying-before-done/
operating-safely/
scoping-changes/
testing-changes/
writing-unit-tests/
guarding-architecture/
adding-dependencies/
Releases
Conventional Commits on main drive semantic-release: commit subjects become the changelog, and the release stamps the version into package.json and all three plugin manifests. semantic-release generates CHANGELOG.md; do not hand-edit it.
License
MIT
Loading...
Select a file to preview
Analyzing security...
Checking scan reports and verification data.
Bill of Materials
Everything this skill can do — files, network, commands, and more.