💂 Guardsman
No diff ships unchallenged.
The AI coding skill that reads your repo's standing orders, sizes every change by its blast radius, and never — never — lets unverified work past the post.
Meet the Guardsman
You've seen him. Bearskin down over his eyes. Boots planted. Tourists have tried everything to make him flinch — he doesn't, because the post is not a performance. He challenges whatever approaches, friend or stranger, five lines or five hundred: prove you belong here. Nothing passes without the countersign.
Guardsman puts him on duty in front of your codebase.
He doesn't watch trends. He watches the diff.
The problem: your agent has two failure modes
Failure mode #1: the over-build. You ask for a small feature. Your agent installs a dependency, writes a wrapper, adds a config layer, and starts an unprompted discussion about edge cases nobody has. You now maintain a small project where a few lines would do.
Failure mode #2 is worse, because it walks like it belongs. The confidently small diff. Minimal, elegant, five lines — written after reading half the flow, tested never, marching straight onto a path that handles money, auth, or your users' data. It compiles. It demos. It detonates in week three. A guard who waves through anything with a confident walk isn't a guard.
Most "write less code" advice fixes #1 and quietly makes #2 more likely. Guardsman is built to stop both at the post.
What Guardsman actually does
Three duties, every task:
- Reads the standing orders. Before writing anything, it detects your repo's real conventions — language, formatter, linter, actual test command — with a deterministic script, then greps how your codebase already solves the nearest similar problem. Your patterns win. Always.
- Sets the threat level. Every change gets a risk tier before a single line is written. Blast radius sets the tier — not how big or clever the code looks.
- Issues the challenge. Non-trivial logic isn't "done" when the code is written. It's done when it has answered the challenge — the check behind it actually run, in this turn, by the agent, with the output shown. Not left behind as homework for future-you.
Then he stands aside. Output format: code first, then at most three lines.
[code]
→ skipped: <X>, add when <Y>. verified: <how>. tier: <T>.
No essays. No feature tours. No design memoirs.
🎯 Risk tiers: the core idea
The insight most coding assistants miss: a five-line change to a payment path is more dangerous than a four-hundred-line internal script run once. Code size is not risk. Blast radius is risk.
| Tier | When | The challenge |
|---|---|---|
| trivial | Internal one-off, nothing downstream | One manual run, output shown |
| standard | Everyday feature work | One runnable check, written AND executed this turn |
| sensitive | Money, auth, user data in the blast radius | A real test exercising the failure path, with explicit coverage notes |
| critical | Getting it wrong is an incident | Full coverage — and if the repo has no harness reaching this path, that absence is surfaced as a blocker, never routed around |
Two rules that keep the tiers honest:
- When signals disagree, the higher tier wins.
- You can downgrade a tier explicitly. The agent never infers a downgrade just because the code looks simple. A confident walk is not a countersign — simple-looking is exactly how failure mode #2 marches past.
🪜 The build order
Once the tier is set, Guardsman climbs a strict ladder and stops at the first rung that holds:
- Does this need to exist at all? Speculative need = skip it, said in one line. (YAGNI)
- Already in this codebase? Reuse it. Rewriting what lives three files over is the single most common source of avoidable code.
- Stdlib does it? Per-language cheat sheets name the usual suspects.
- Native platform feature covers it? A DB constraint over app-level validation. CSS over JS. The platform already shipped it.
- Already-installed dependency solves it? Use it — and never add a new dependency for what a few lines can do, once you count its maintenance tail and the onboarding cost every future reader (human or agent) pays.
- Can it be one line? One line — after reading the full flow, never before.
- Only then: the minimum code that works, scaled to the tier.
And two refinements that separate a guardsman from a minimalist:
- Bug fix = root cause, not symptom. It greps every caller before touching the function. One guard in the shared function beats a patch in the one caller the ticket happened to mention — and silently fixes the sibling callers the ticket didn't.
- Cost of change, not just cost of code. YAGNI means don't build for a guess. It does not mean ignore the ticket already scheduled for next sprint. When a second consumer is near-certain, Guardsman adds the seam and says why in one line — because the rewrite next week is the expensive path, not the extra line today.
📖 The logbook: tech debt that can't hide
TODO comments rot. Nobody greps them, nobody triages them, nobody remembers why they exist. Guardsman replaces them with structured entries in the watch log — machine-readable, severity-tagged, dated:
# guardsman: retry capped at 3, no backoff config | severity:med | revisit:second-caller-appears | cost:none
Every deliberate shortcut carries its severity and its revisit trigger — both required. A bundled scanner (scripts/scan_ledger.py) harvests the whole repo, groups entries by severity, and flags anything overdue or malformed. A shortcut nobody can triage is worse than an unmarked one: it creates false confidence that it's tracked.
Your technical debt stops being folklore in someone's head. It becomes a logbook with severities and dates — and a scanner that reads it.
🧰 Five modes, one skill
| Mode | Scope | What it does |
|---|---|---|
build |
persistent, default | Everything above, on every response, until stood down |
review |
current diff, one-shot | Hunts over-engineering and convention drift. Lists findings, applies nothing |
audit |
whole repo, one-shot | Same taxonomy, full tree: dependencies duplicating stdlib, single-implementation interfaces, delegate-only wrappers, dead config — ranked biggest first |
logbook |
whole repo, one-shot | Runs the watch-log scanner and reports open shortcuts by severity, overdue entries first |
post-report |
this repo, one-shot | The actual, live state: open logbook entries, detected conventions, recent findings |
/guardsman # build mode, standard tier
/guardsman build sensitive # this ticket touches token refresh
/guardsman review # what can we delete from this diff?
/guardsman audit # what can we delete from this repo?
/guardsman logbook # what did we promise to come back to?
/guardsman post-report # where do we actually stand?
Say stand down, stop guardsman, or normal mode to take him off duty.
🧾 Honest by design: no fake numbers, ever
Here's a promise you won't find in most tool READMEs:
Guardsman will never tell you it "saved you 12,000 lines." There is no unbuilt baseline version of your codebase to diff against, so no tool — including this one — can honestly produce that number. post-report shows only what is directly countable, computed live, on your repo, right now. If nothing has been computed yet, it says so and offers to run the scan — instead of presenting a confident figure that corresponds to nothing.
A tool that invents numbers about your codebase has no business guarding it. The honesty rule isn't a limitation. It's the product.
📊 Benchmarks
Coming — and coming honestly. A reproducible protocol lives in benchmarks/: a real open-source repo, twelve feature tickets, multiple arms, scored on the git diff each one leaves behind — lines changed, guards kept, checks actually executed. Yes, the headline metric is guards kept. It's in the name.
Guardsman's no-invented-numbers rule applies to Guardsman itself: no headline figure will appear here before it has been measured, and every result will ship with its method, its limits, and the scripts to reproduce it.
⭐ Star the repo to get the results when they land.
🛡️ General Orders
Some things are never simplified away, at any tier, under any instruction to "keep it minimal":
- Input validation at trust boundaries
- Error handling that prevents data loss
- Security measures
- Accessibility basics
- Anything you explicitly asked for — once you've said you want the fuller version, it gets built, no re-litigating
And two orders above all the others. Never lazy about understanding the problem: he walks the whole perimeter before taking the post — the ladder shortens the solution, never the reading. Quit the post only when properly relieved: no turn ends with the verification silently skipped; if a check genuinely can't run here, saying so explicitly is the relief.
🚀 Install
Claude Code (plugin — recommended):
/plugin marketplace add hedimanai-pro/guardsman
/plugin install guardsman@guardsman
Claude Code (project-level, manual):
git clone https://github.com/hedimanai-pro/guardsman
cp -r guardsman/plugins/guardsman/skills/guardsman .claude/skills/
Any other agent (Codex, Cursor, anything that reads an AGENTS.md or custom instructions): copy the condensed ruleset