Four Hosts, One Engine
Claude Code, Codex and Grok judge the write before disk. Hermes refuses the conclusion instead, because an autonomous agent has nobody to break the loop. What each host does not do is measured and published.
For the person who signs off on the merge · v4.12.3 · Apache 2.0
Nothing reaches your disk unchecked.
Your agent writes faster than you can review it. A prompt asks for your architecture rules and forgets them by the tenth file. This refuses the write instead, and the same rules run in your agent, in your pipeline, and in the criteria your reviewer reads.
One engine, four hostsClaude CodeCodexGrokHermes
craftsman:pre-write · src/Domain/UserService.php
⚙ craftsman:pre-write: 4 levels
✗ PHP001 Class must be declared final
✗ SEC001 Credential in source
✗ LAYER001 Domain imports infrastructure
✗ 3 violations: write refused
✓ fix applied · 3/3 passed
✓ File written to disk.The drift
Your agent is powerful. Long sessions are not.
01
Ask twice, get two patterns
No memory of yesterday’s decision. Today final class, tomorrow mutable state.
02
No architectural guardrails
It writes code that works and quietly dissolves your layer boundaries.
03
Debt nobody decided to take on
The last hour of a session is never as good as the first. Six months of that, and your codebase carries a design nobody chose and you signed off on all of it.
Where this sits
A prompt asks. This enforces.
BMAD, spec-kit and Superpowers decide what to build and in what order. They are good at it, and this plugin does not replace any of them. It answers the question they leave open: what happens when the model writes something the architecture cannot carry.
| Axis | Methodology plugins | Craftsman |
|---|---|---|
| What it is | A method. Prompts, templates, a workflow | A control. Hooks that run whether or not the model cooperates |
| How it acts | It asks the model to comply | It refuses the write before the file exists |
| When the context fills | Compliance decays with attention | Unchanged. It is bash and Python, not a paragraph |
| Where it reaches | The session it was invoked in | The session, your CI, and a baseline committed to git |
| Where it runs | The one agent it was written for | Claude Code, Codex, Grok and Hermes, one engine, host limits published |
| What it knows | Software delivery, generally | SOLID, hexagonal, DDD, and taming inherited code |
Run both. The plugin detects Superpowers at session start and arms its gates on its workflows. Plan with the method you already trust, and let this one hold the line while the plan gets written.
The quality gate
Four levels. The cheapest one always runs.
A pre-write hook runs before the edit reaches your disk. What a regex can decide never reaches a model, so the expensive checks rarely run.
LEVEL 1always on
Regex
Forbidden patterns, naming, secrets. SEC001 catches a committed key before the file exists. Its cost is measured on every release, not promised.
LEVEL 1.5if installed
Semantics
LSP-backed, live, and only when the language server is already on your machine. The plugin orchestrates your tooling, it does not replace it.
LEVEL 2opt-in
Static analysis
PHPStan, ESLint, deptrac. Running a project’s analysers runs its code, so you allow it in your own global config. A repository can never grant it to itself.
LEVEL 3on demand
Architecture
Layer boundaries and DDD invariants. LAYER001 refuses a domain that imports infrastructure.
The same rules run in CI
One rule set, two runtimes. What the hook refuses locally, the pipeline refuses on the branch, so nobody negotiates with the gate by pushing.
- GitHub
- GitLab
- Bitbucket
- Jenkins
Inherited code
It will not turn your repository red on day one.
A quality gate that fails four hundred files the moment it is installed gets uninstalled the same afternoon. This one measures each file against its own recorded mark. Debt you inherited is not a violation. It becomes one the day somebody makes it worse.
And when you do decide to go in, there is a method for it, with an agent that works in its own git worktree so a rescue in progress never leaks into your branch.
/craftsman:legacy audit
Find where it actually hurts
Hotspots ranked by churn times complexity, from your existing tooling rather than a second opinion invented on the spot. Plus a contra section: what looks alarming and is fine.
/craftsman:legacy cover
Net first, then touch it
Characterization tests pin the behaviour that exists, bugs included, before a line changes. Golden master, scrubbers, printers.
/craftsman:legacy untangle
Cut a seam, not the code
Break the hard dependency that makes the class untestable. Subclass and override, wrap and sprout. Behaviour does not move.
/craftsman:legacy migrate
Grow the new around the old
Strangler fig, branch by abstraction, anti-corruption layer. The old component retires when the new one carries the load, not before.
“The safety net comes before the refactor. No net, no change.”
Iron law 4, /craftsman:legacy
Receipts
We publish the bugs we found in ourselves.
A tool that enforces standards has to be held to them. v4.2.0 was an audit release. Every finding was reproduced before it was fixed, and each carries a test that fails when the fix is removed.
Level 2 and 3 could not run and said they were clean. Every analyser was capped at 2 seconds, below the cold start of all of them, and || true flattened the timeout into success.
CI reported a pass on a pipeline that inspected nothing. The default scan path was src/, so a Laravel app/ matched nothing and the run exited 0 with files_scanned: 0.
The test suite trained the learning loop on its own fixtures. 3704 of 15588 violations sat on a path this repository does not have.
The recurring shape is one defect wearing different clothes: a control that reports success when it did not run.
Correction learning
It learns from your corrections. You approve what it learns.
When you override the gate or rewrite what the agent produced, that correction is recorded and weighted. A fix that recurs becomes a candidate, and a candidate becomes a rule only when you say so.
No embeddings. No vector index. No external service. Knowledge is plain Markdown with YAML frontmatter, versioned in git, resolved through a deterministic rule-to-concept lookup, so the same input always yields the same rule.
ADR-0020 · promotion is human-gated
- the loop
- 01You correct the outputdiff captured on save
- 02Stored and weightedsqlite, on your machine
- 03Promoted to a candidate3 occurrences across 3 files
- 04You approve it/craftsman:metrics · never automatic
- 05Codified as a project skillwith provenance: rule, count, date
What is recorded
Measured locally. Nothing leaves the machine.
Every gate run is an event in a local SQLite database. The schema is deliberately boring, which is exactly what makes it short to audit.
violations · corrections · sessionslocal schema
rule id
LAYER001
severity
block · warn · ignore
path pattern
src/Domain/**/*.php
outcome
blocked · warned · fixed
timestamp
UTC
project hash
sha-256 of the repo root
never recorded
- source code
- file contents
- diffs
- commit messages
- branch names
- absolute paths
- tokens or cost
No telemetry, no analytics, no phone-home. With agent_hooks: falseand no Sentry configured, the plugin makes zero network calls.
This website is a separate thing, and it does count its visitors: traffic measurement only, after you agree, with the advertising permissions refused in code. It has no channel to your editor and cannot see any of the above.How we handle data.
Agent fleet
Twelve agents, priced by the job.
The same twelve missions ship to every host. On Claude Code, mechanical work runs on the cheapest model that can do it, so you never pay Opus rates to format a commit message; on Codex, Grok and Hermes the host's own model runs them.
Core · always available
team-leadopusOrchestration. Holds no Write or Edit
architectopusDDD and layer boundaries. Holds no Write or Edit
doc-writerhaikuADRs, README, changelog
security-pentestersonnetOWASP Top 10, auth, injection
legacy-surgeonopusInherited code, in its own git worktree
ui-ux-directorsonnetDesign system and WCAG 2.1 AA
Pack · when their pack is enabled
backend-craftsmansonnetSymfony, Doctrine, Messenger
api-craftsmansonnetAPI Platform, REST, OpenAPI
symfony-reviewersonnetReviews PHP. Holds Edit
frontend-craftsmansonnetReact 19, TypeScript, Tailwind
react-reviewersonnetReviews components. Holds Edit
ai-engineersonnetRAG, embeddings, MLOps
Opus goes to the three whose job is judgment across files, not application within one: orchestration, layer boundaries, and inherited code. Everything mechanical drops to Haiku. About $0.15 to $0.30 per session, and the core gate needs no API key. Read each agent’s frontmatter rather than its role name: two that sound like reviewers hold Edit.
The mechanisms
Everything the gate is made of.
Ten of them. You need to understand two: the ratchet, which is why your codebase cannot get worse, and correction learning, which is why you stop repeating yourself. The other eight run without being asked, on whichever agent you use.
Structural Ratchet
A committed baseline holds each file’s structural high-water mark. A file you touch may improve or stay equal, never regress. Untouched legacy is never punished.
Correction Learning
A fix that recurs three times across three files becomes a candidate you approve.
Evidence Gate
“Done” requires proof. A failing test run revokes a verification that already exists.
Multi-CI Zero Drift
One rule set, four providers, identical to the hooks.
Hostile-Repo Threat Model
Opening a repository is not consenting to run it. A project file can never grant itself permission.
Rules Engine
15 core rules plus everything your pack adds, inherited global to project to directory. Legacy coexists with strict new code.
Adversarial Design Panel
Three contradictors attack a design before any code exists. Every objection lands in a retained or dismissed table.
Iron Law Pattern
Every scaffold loads the canonical example before it writes a line.
Cognitive Bias Detector
Catches acceleration, scope creep and over-optimisation in your prompts, not the model’s.
Packs
Your stack’s rules, not generic ones.
A pack is a manifest, a rule set, and optional agents./craftsman:setup reads your repository and enables the ones that match.
- symfony
- react
- python
- go
- rust
- bash
- ai-ml
A new language is a new pack.yml. No line of the engine changes.
pack.yml
name: symfony
languages:
- id: php
extensions: [php]
protected_configs: [phpstan.neon, deptrac.yaml]
static_analysis: [static-analysis/phpstan.sh]
supersedes:
- vendor/bin/deptrac=LAYER001,LAYER002
rules:
owned:
- id: PHP002
text: "every class is final"
default_severity: blockInstall
Armed in a minute, on the agent you already run.
Two commands on each host, then /craftsman:setup --quick reads your repository and arms the packs that match.
Claude Code
/plugin marketplace add BULDEE/ai-craftsman-superpowers /plugin install craftsman@ai-craftsman-superpowersWrite and Edit judged before disk
Claude Code guide →Codex
codex plugin marketplace add BULDEE/ai-craftsman-superpowers codex plugin add craftsman@ai-craftsman-superpowersapply_patch judged before disk, once you trust the handlers in /hooks
Codex guide →Grok
git clone https://github.com/BULDEE/ai-craftsman-superpowers bash ai-craftsman-superpowers/bin/craftsman-grok-installwrite and search_replace judged before disk, through a global gate
Grok guide →Hermes
git clone https://github.com/BULDEE/ai-craftsman-superpowers ~/.hermes/plugins/craftsman hermes plugins enable craftsmanConclusion refused while a critical violation remains
Hermes guide →
python3 3.9+, bash, grep, jq and sqlite3 on every host; Claude Code 2.1.218 or later. GNU coreutils is not required: the plugin runs on a stock macOS.
Free & open source
No seats. No keys. Apache 2.0.
The core gate runs entirely on your machine and costs nothing. Agent hooks are optional and cost cents per session. Two commands, one restart, and the next write is checked.
Install it now