Are you the author? Sign in to claim
Craftsman ecosystem for AI coding agents (Claude Code, Hermes Agent, ...): blocks the write when it breaks your architec
🇬🇧 English | 🇫🇷 Français
Claude writes the code. Your architecture rules decide what lands.
For teams running Claude Code on a codebase where a layer violation costs more than the feature does.
Website • Install • Commands • Docs • Contributing
You can write "always use final classes" in your CLAUDE.md. Claude will
follow it, until the context fills up, or the task gets long, or the tenth file
of a refactor. Instructions decay. That is not a discipline problem, it is an
architecture problem: nothing in the loop is checking.
Craftsman puts the check in the loop. The same rules run as hooks on every
Write, as a gate in your CI, and as the criteria a reviewer agent reads. Layer
violations and missing strict_types are refused before the write lands,
everything else is handed straight back to Claude as a finding it has to answer
for, and the same rule fails your pipeline if it reaches a pull request.
Claude tries to write an entity that imports from the infrastructure layer. The file never reaches your disk:
$ ./check.sh User.before.php.txt /srv/app/src/Domain/User/User.php
🚫 BLOCKED by AI Craftsman - 2 violation(s) detected before write:
✗ LAYER001: Domain imports Infrastructure - DDD layer violation
✗ PHP001: Missing declare(strict_types=1) in class file
Fix these before writing. Use // craftsman-ignore: <RULE_ID> to suppress.
exit=2
Not a mockup: the recording pipes two fixtures through hooks/pre-write-check.sh
and shows whatever it returns. Exit code 2 is the refusal.
Claude reads the same two lines you do, corrects the import, and writes again.
The correction is recorded; if that same rule keeps coming back across files, it
is offered to you as a candidate instinct in /craftsman:metrics. And if the
violation ever reaches a pull request instead, the identical rule fails the
pipeline: one engine, one verdict, no drift between your editor and your CI.
Your real alternative is not another plugin. It is the CLAUDE.md you already
wrote, and the linters you already run.
| CLAUDE.md alone | Linter and CI | Craftsman | |
|---|---|---|---|
| Still holds at file 300 of a refactor | no | yes | yes |
| Claude sees the violation before writing | no | no | yes |
| Same verdict on your machine and in the pipeline | n/a | partial | yes |
| Stops Claude from repeating the same mistake | no | no | yes |
| Blocks a design decision made without a design pass | no | no | yes |
It blocks. One rules engine, enforced identically in hooks and CI. No drift between what your editor allows and what your pipeline rejects. GitHub, GitLab and Bitbucket get native annotations; Jenkins runs through a generic adapter.
It learns. Every violation you fix is recorded locally. A fix that recurs
3+ times across 3+ files is promoted to a candidate instinct you approve in
/craftsman:metrics, and it becomes a project skill with provenance. Detection
is automatic, codification stays human-gated.
It proves. "Done" requires evidence. A task cannot be marked complete without a verification record, and a failing test run revokes one that already exists.
And it runs each job on the cheapest model that can do it: formatting a commit on Haiku at low effort, an architecture review on Opus at high. You never pay Opus rates to write a commit message.
PHP001: warn) or long form (custom regex rules). Legacy code coexists with strict new code via directory-level relaxation./craftsman:design, before any code exists. Every objection lands in a retained or dismissed table: silence is not an option. Contradicting a design costs far less than contradicting the code built on it.fr-CA or zh-Hant register like any other. Adding a language is two data files and zero code. The non-English lexicons ship as recall-oriented seed lists that no native speaker has reviewed yet, which is the point of the tier: a false positive there is a note the model drops silently, never a warning you see.[!WARNING] Only install this plugin from the official sources below. Do not trust forks, mirrors, or "improved" copies distributed elsewhere. Verification steps: SECURITY.md.
# 1. Add the marketplace
/plugin marketplace add BULDEE/ai-craftsman-superpowers
# 2. Install the plugin
/plugin install craftsman@ai-craftsman-superpowers
# 3. Restart Claude Code, then configure
exit
claude
/craftsman:setup --quick
Running Hermes agents instead of (or next to) Claude Code? The same repository is a native Hermes plugin:
git clone https://github.com/BULDEE/ai-craftsman-superpowers ~/.hermes/plugins/craftsman
hermes plugins enable craftsman
Your autonomous agent gets the same gate (it cannot conclude a coding turn that leaves critical violations), the correction-learning loop, /craftsman on demand and seven situation-selectable craftsman skills. Five-minute walkthrough: Hermes quickstart; a full blocked-fixed-learned turn: examples/hermes-agent; design and threat model: adapters/hermes/README.md.
That is the whole setup. --quick reads your repository and picks defaults; run
/craftsman:setup without it to answer four plain-language questions instead.
Requirements
claude --version). Older versions: install the frozen 3.9.x line.python3 3.9 or later. That is the floor because it is what /usr/bin/python3 is on a Mac without homebrew; CI imports every hook library under 3.9 so the floor cannot silently rise.bash, grep, jq, sqlite3. GNU coreutils is not required: the plugin runs on a stock macOS.Install from a local clone
git clone https://github.com/BULDEE/ai-craftsman-superpowers.git /path/to/ai-craftsman-superpowers
/plugin marketplace add /path/to/ai-craftsman-superpowers
/plugin install craftsman@ai-craftsman-superpowers
Verify
/plugin
# "Installed" tab → craftsman plugin should appear
# "Errors" tab → check here if skills don't appear
# The full development cycle: design → spec → plan → implement → test → verify → commit
/craftsman:workflow
I need to add a forgot password feature.
Every hook is already running by then. Individual entry points when you do not
want the whole cycle: /craftsman:design (DDD modeling), /craftsman:debug
(systematic investigation), /craftsman:challenge (architecture review),
/craftsman:verify (evidence before you call it done).
New to the methodology? The Beginner Guide walks
through DDD concepts with worked examples, and /examples shows
each command with its expected output.
All commands are explicitly invoked, never auto-triggered. Full reference: COMMANDS-QUICK-REF.md.
| Category | Commands |
|---|---|
| Core methodology | design, debug, plan, challenge, verify, workflow, spec, refactor, legacy, test, git, parallel |
| Scaffolding | scaffold entity/usecase/component/hook/api-resource/pack |
| AI/ML engineering | rag, mlops, agent-design |
| Utilities | metrics, setup, team, healthcheck |
| CI/CD | ci |
Scaffolders offer a template variant before generating code (bounded-context
vs event-sourced for entities, for instance). Agents that back these commands:
team-lead, architect (no Write/Edit), doc-writer, security-pentester,
legacy-surgeon, ui-ux-director, plus pack-specific reviewers for Symfony,
React and AI/ML. Full roster: Agents Reference.
Override any rule per-project or per-directory with 3-level config inheritance:
~/.claude/.craft-config.yml ← Global defaults
└─ {project}/.craft-config.yml ← Project overrides
└─ {dir}/.craft-rules.yml ← Directory overrides
Short form: PHP001: warn / TS001: ignore. Long form: custom rules with
regex, severity, languages. Suppress a single occurrence inline with
// craftsman-ignore: RULE_ID.
CI sources the same pack validators and the same rules engine as the hooks, so a
rule cannot mean one thing on your machine and another in the pipeline. Export a
pipeline with /craftsman:ci export.
| Provider | Template | Adapter |
|---|---|---|
| GitHub Actions | craftsman-quality-gate.yml | Native: inline annotations and a PR comment |
| GitLab CI | .gitlab-ci.craftsman.yml | Native: code-quality report and an MR note |
| Bitbucket Pipelines | bitbucket-pipelines.craftsman.yml | Native: build report |
| Jenkins | Jenkinsfile.craftsman | Generic: plain log output and a markdown file |
Everything above works with zero API cost beyond your normal Claude Code
usage: regex validation, the rules engine, bias detection, CI export and metrics
are local. One optional layer adds semantic analysis through Haiku agent hooks
at roughly $0.15-0.30 per session of 50 Write/Edit operations. Turn it off with
agent_hooks: false and everything else keeps working.
No telemetry, no analytics, no phone-home. Metrics never leave your machine.
Edited file content only reaches the Anthropic API when agent_hooks: true.
Command hooks write only to the local metrics DB and session state.
A cloned repository is untrusted input, so the two capabilities that would
execute repository-supplied code (trust_project_tools and external pack paths)
are off until you enable them in your own global config, and a project file
can never grant them. tests/core/test-hostile-repo.sh reproduces each attack
this model covers and asserts it fails. Full breakdown: SECURITY.md.
By design: code rule violations block, bias detection only warns; no auto-commit; commands are explicitly invoked, never auto-triggered; methodology is opinionated (DDD/Clean Architecture).
Current constraints: PHP/TypeScript get full rule coverage, other languages basic support only; bias detection warns directly in English and leaves every other language to the model to adjudicate in context; metrics are per-machine, not shared across a team; auto-fixing violations and IDE plugins are not supported by design.
More detail in the FAQ.
| What's new in v4 | Clean break targeting Claude Code >= 2.1.218: closed learning loop, native-first skills, semantic Level 1.5, context budgets. Breaking changes in MIGRATION.md. |
| Architecture decisions | 28 ADRs covering every major design choice. Start with ADR-0016 and ADR-0005. |
| Knowledge bundle | The methodology ships as an Open Knowledge Format bundle: plain Markdown, versioned in git, readable by Obsidian or any OKF consumer. Zero embeddings, zero index, zero external service. |
| Hermes quickstart | The same plugin inside Nous Research's Hermes agents: two-command install, recommended bot profile, server deployment pattern, troubleshooting. Runnable proof in examples/hermes-agent. |
| For non-developers | What this plugin does, in plain language: the radar-in-the-loop explanation, what a refusal looks like, and the three questions worth asking your team. |
| CLAUDE.md guidance | What belongs in your global file, your project file, and what the plugin should own instead. |
| Hooks reference | Every hook, exit code and rule ID, including the Circuit Breaker and the Iron Law Pattern. |
| Troubleshooting | When a skill does not appear, a hook does not fire, or a rule fires too often. |
Craftsman and Superpowers load simultaneously with no conflicts. Superpowers orchestrates the workflow (brainstorming, planning, TDD, subagent-driven development); Craftsman enforces quality inside it.
1. /superpowers:brainstorming → Design the solution collaboratively
2. /superpowers:writing-plans → Create implementation plan
3. /superpowers:subagent-driven-development → Execute with fresh subagents
├── Craftsman hooks fire on every Write/Edit (real-time quality gate)
├── /craftsman:design → DDD modeling when domain entities appear
└── /craftsman:challenge → Architecture review at milestones
4. /craftsman:verify → Evidence-based verification before commit
5. /superpowers:finishing-a-development-branch → PR and merge
"Weeks of coding can save hours of planning."
Design before code. Test-first. Systematic debugging over random fixes. YAGNI. Clean Architecture, dependencies point inward. Make it work, make it right, make it fast, in that order.
Pragmatism over dogmatism: 80% coverage on critical paths beats 100% everywhere; DDD for complex domains, not every domain; concrete first, abstract when actually needed.
Contributions welcome. Fork, branch, follow the methodology (/craftsman:design
first), add tests, open a PR. Details in CONTRIBUTING.md.
Looking for a place to start? The good first issues are real work, not busywork: new language packs, rule coverage, examples, translations.
 Alexandre Mallet Author and maintainer BULDEE |
 Marc Lucas Hooks architecture and config resolution CEO, M.A. LucasFireDev |
Marc Lucas (LinkedIn), CEO of M.A. LucasFireDev, contributes actively to the plugin: the migration from agent hooks to gated command hooks, the global ~/.claude/.craft-config.yml fallback, hook path resolution, and the test suite that covers them. M.A. LucasFireDev is a PHP/Symfony consultancy doing code audit, maintenance and team coaching.
Your name belongs here too.
| Sponsor | Description |
|---|---|
| BULDEE | Building the future of AI-assisted development |
| M.A. LucasFireDev | PHP/Symfony consultancy, sponsoring the plugin with engineering time |
Interested in sponsoring? Contact us
Discord • Issues • Discussions • Changelog
Apache License 2.0, see LICENSE.
If Craftsman refused a write you would have merged, star the repository.
It is the only metric this project collects.
Forged by Alexandre Mallet · Sponsored by BULDEE & M.A. LucasFireDev
1000+ skills curated from Anthropic, Vercel, Stripe, and other engineering teams
Design enforcement with memory — keeps your UI consistent across a project
Detects 37 AI writing patterns and rewrites text with human rhythm across 5 voice profiles
WCAG accessibility audit — automated scanning, manual review, remediation