💂 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 from adapters/AGENTS.md into your project's instruction file. Tiers, ladder, and challenge floors travel everywhere; the scripts and cheat sheets stay with the full skill.
Zero configuration: the convention detector reads your repo's actual config on first contact — no setup file to maintain.
What a session looks like
You: add retry logic to the payment client
Guardsman: tier: sensitive — this touches the charge path.
# 9 lines using the retry helper that already exists in http/util.py
→ skipped: configurable backoff, add when a second caller needs it (entered in the logbook).
verified: test_gives_up_after_3_and_surfaces_error written and run — failure path covered, concurrent-retry case not covered, flagged.
Nine lines. Reusing your own helper. Challenged on the path where it can hurt you. Honest about what's not covered. That's the whole product.
FAQ
Won't all this challenging slow my agent down?
Trivial tier has a fast path: one targeted grep, one manual run, done. The full challenge only engages where the blast radius justifies it. That's the entire point of tiers — rigor where it pays, speed where it doesn't.
What if I disagree with a tier?
Downgrade it explicitly and Guardsman complies. He just refuses to guess the downgrade from the code looking easy.
Which stacks?
Dedicated stdlib/native cheat sheets for Python and JavaScript/TypeScript, plus a language-independent method for everything else — it's a procedure, not a lookup table.
Does it change my agent's personality?
No. Guardsman governs what gets built and how it's verified, not conversational tone. Pair it with a style skill if you also want terse prose.
Author
On the watch: Hedi Manai — AI & backend engineer building reliability tooling for AI agents (see also ToolOps, middleware for agent tool-calling).
GitHub · LinkedIn · X
Credits
Guardsman stands on the shoulders of the minimal-code movement in agent skills — the YAGNI ladders and stdlib-first reflexes that taught agents to write less. It adds the step that movement left out: the challenge.
License
MIT.
The shortest path to done is the right path — once you actually know what "done" has to hold up against.
Put a Guardsman on the post. 💂
