You've seen the guardsman. Bearskin down over his eyes, boots planted, unmoved by the tourists trying to make him flinch — 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.
1. The post
Guardsman is an AI coding skill with a single, stubborn job: no diff ships unchallenged. Before writing anything it reads your repository's standing orders — the real conventions already in the tree — sizes the change in front of it by how much could break, and refuses to call non-trivial work done until the check behind it has actually run.
"He challenges whatever approaches, friend or stranger, five lines or five hundred: prove you belong here. Nothing passes without the countersign."
That framing is deliberate. Most coding assistants optimise for producing an answer; Guardsman optimises for producing an answer you can trust without re-reading every line. It stands between your agent and your codebase the way a guard stands at a post — the application code never has to know the scrutiny is happening, but nothing gets through without it.
2. The two failure modes
Coding agents fail in two directions, and most advice only addresses one of them. Guardsman is built to stop both at the post.
| Failure mode | What it looks like | How Guardsman stops it |
|---|---|---|
| #1 — The over-build | A small ask turns into a new dependency, a wrapper, a config layer, and a debate about edge cases nobody has. You now maintain a project where a few lines would do. | The build order ladder: skip what isn't needed, reuse what exists, reach for stdlib and the platform before new code. |
| #2 — The confident small diff | Minimal, elegant, five lines — written after reading half the flow, tested never, marching onto a path that handles money, auth, or user data. It compiles. It demos. It detonates in week three. | Risk tiers by blast radius plus the challenge: the dangerous path gets a real test on its failure case, run this turn. |
The insight most tools miss
"Write less code" advice fixes failure mode #1 and quietly makes #2 more likely — a confident, tiny, untested diff is exactly what a lax guard waves through. Code size is not risk. Blast radius is risk.
3. Install
Guardsman is open source under the MIT license. It needs zero configuration: the convention detector reads your repo's actual config on first contact — there is no setup file to maintain.
/plugin marketplace add hedimanai-pro/guardsman
/plugin install guardsman@guardsmangit clone https://github.com/hedimanai-pro/guardsman
cp -r guardsman/plugins/guardsman/skills/guardsman .claude/skills/Any other agent
For Codex, Cursor, or anything that reads an AGENTS.md or custom
instructions file, copy the condensed ruleset from adapters/AGENTS.md into your project's
instruction file. The tiers, the build ladder, and the challenge floors travel everywhere; the scripts
and language cheat sheets stay with the full skill.
4. The three duties
Every task, Guardsman performs the same three duties before it considers the work finished.
The output format matches the discipline: code first, then at most three lines — what was skipped and when to add it, how it was verified, and the tier. No essays, no feature tours.
5. 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. So the tier is set by blast radius, and the challenge scales with it.
| 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, or 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 keep the tiers honest: when signals disagree, the higher tier wins; and you can downgrade a tier explicitly, but the agent never infers a downgrade just because the code looks simple. A confident walk is not a countersign.
6. The build order
Once the tier is set, Guardsman climbs a strict ladder and stops at the first rung that holds. The goal is the smallest change that actually solves the problem — reached by elimination, not by guessing.
- Does this need to exist at all? Speculative need is skipped, 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.
- Does the standard library do it? Per-language cheat sheets name the usual suspects.
- Does a native platform feature cover it? A database constraint over app-level validation; CSS over JS. The platform already shipped it.
- Does an already-installed dependency solve 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 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.
Two refinements separate a guardsman from a plain minimalist. A bug fix targets the root cause, not the symptom: it greps every caller before touching a function, so one guard in the shared function beats a patch in the single caller the ticket happened to mention. And it weighs the cost of change, not just the cost of code: 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.
7. The logbook: tech debt that can't hide
TODO comments rot — nobody greps them, triages them, or remembers why they exist. Guardsman
replaces them with structured entries in a watch log: machine-readable, severity-tagged,
and dated, each one carrying both its severity and its revisit trigger.
# guardsman: retry capped at 3, no backoff config | severity:med | revisit:second-caller-appears | cost:noneA bundled scanner (scripts/scan_ledger.py) harvests the whole repo, groups entries by
severity, and flags anything overdue or malformed. Your technical debt stops being folklore in someone's
head and becomes a logbook with severities and dates — plus a scanner that reads it. A shortcut nobody can
triage is worse than an unmarked one: it creates false confidence that it's tracked.
8. Five modes, one skill
The same taxonomy runs in five scopes, from a persistent build guard to one-shot reports over a diff or the whole tree.
| 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.
9. Honest by design: no fake numbers
Here is 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.
The post-report mode 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.
The honesty rule is the product
A tool that invents numbers about your codebase has no business guarding it. Even the benchmarks are held to it: the reproducible protocol lives in the repo, and no headline figure ships before it has been measured — with its method, its limits, and the scripts to reproduce it. The headline metric is guards kept. It's in the name.
10. 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, with no re-litigating
And two orders above the rest. Never lazy about understanding the problem: Guardsman 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 in this environment, saying so explicitly is the relief.
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.
tier: sensitive.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.
Frequently Asked Questions
Won't all this challenging slow my agent down?
The 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 risk tier?
Downgrade it explicitly and Guardsman complies. It just refuses to guess the downgrade from the code looking easy — because simple-looking is exactly how a dangerous change marches past a guard that waves through anything confident.
Which languages and stacks does it support?
Dedicated standard-library and native-feature cheat sheets for Python and JavaScript/TypeScript, plus a language-independent method for everything else. It's a procedure, not a lookup table — the tiers, ladder, and challenge floors apply to any language.
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.
How is it different from "write less code" skills?
Minimal-code skills fix the over-build failure mode but quietly make the opposite one worse: the confident, tiny, untested diff on a dangerous path. Guardsman keeps the build ladder that shrinks code and adds the step that movement left out — the challenge, an actual check run before the change is called done.