In one sentence
Guardsman is an AI coding skill with one stubborn job: no diff ships unchallenged. It reads your repository's real conventions, 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.
0. Quick start
In Claude Code, two commands. Other agents — Codex, Cursor, anything that
reads an AGENTS.md — are covered under Install.
> /plugin marketplace add hedimanai-pro/guardsman
> /plugin install guardsman@guardsman
Reach for it when
Your agent works on a real codebase and you would otherwise re-read every line: feature work, refactors, anything that touches money, auth or user data. On a throwaway script, the trivial tier keeps it out of your way.
It's working if
Every non-trivial change ends with a check that ran this turn, output shown; the code follows the patterns already in your repo; and the answer closes in three lines or fewer: what was skipped, how it was verified, the tier.
1. The post
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.
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.
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. Stopped by 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. Stopped by risk tiers set by blast radius, plus the challenge: the dangerous path gets a real test on its failure case, run this turn.
"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 no setup file to maintain — the convention detector reads your repository's actual config on first contact.
# Claude Code — plugin marketplace /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 AGENTS.md-compatible agent — Codex, Cursor # copy the condensed ruleset into your instruction file: git clone https://github.com/hedimanai-pro/guardsman cp guardsman/adapters/AGENTS.md .
For Codex, Cursor, or anything that reads an AGENTS.md or custom
instructions file, the condensed ruleset from adapters/AGENTS.md
travels 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.
Reads the standing orders
Before writing anything, a deterministic script detects your repo's real conventions — language, formatter, linter, the actual test command. Then it 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. Money, auth, and user data raise it.
Issues the challenge
Non-trivial logic isn't "done" when the code is written. It's done when the check behind it has actually run, this turn, with the output shown — not left as homework for future-you. Then he stands aside.
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. 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.
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 a missing harness is surfaced as a blocker, never routed around.
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.
Seven rungs, in order
- 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 — never add a new one 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:none
A 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.
/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
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.
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.
A tool that invents numbers about your codebase has no business guarding it. The headline metric is guards kept. It's in the name.
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.
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.
3
Duties every task
7
Rungs on the build ladder
5
Modes, one skill
FAQ
Frequently asked questions
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.
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.
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.
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.
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.
Building with Claude Code?
Point it at your review queue first. Issues and war stories welcome.