Guardsman: No Diff Ships Unchallenged

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.
The insight most tools miss

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.

Quickstart Claude Code
# 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.

A logbook entry Example
# 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.

Switching modes Claude Code
/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.
The honesty rule is the product

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.

Worked example Add retry logic to the payment client
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.

Building with Claude Code?

Point it at your review queue first. Issues and war stories welcome.

Star on GitHub

Contact

Got a system to build?

If you're building a RAG pipeline, an AI agent workflow, or an MCP integration and want to compare notes, swap ideas, or just avoid the mistakes I've already made — reach out.

Or get the Playbook in your inbox — one email when a new lesson ships, and nothing else.

No noise, no spam. Unsubscribe anytime.