{
  "markdown": "<div align=\"center\">\n\n<a href=\"https://ai-craftsman.dev\">\n  <img src=\"https://raw.githubusercontent.com/BULDEE/ai-craftsman-superpowers/main/.github/assets/github-banner.png\" alt=\"AI Craftsman Superpowers - a prompt asks, this enforces\" width=\"100%\">\n</a>\n\n🇬🇧 **English** | [🇫🇷 Français](README.fr.md)\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-%E2%89%A52.1.218-blueviolet?logo=claude)](https://code.claude.com)\n[![Version](https://img.shields.io/github/v/release/BULDEE/ai-craftsman-superpowers?label=version)](CHANGELOG.md)\n[![CI](https://img.shields.io/github/actions/workflow/status/BULDEE/ai-craftsman-superpowers/ci.yml?label=CI)](.github/workflows/ci.yml)\n\n**Claude writes the code. Your architecture rules decide what lands.**\n\nFor teams running Claude Code on a codebase where a layer violation costs more\nthan the feature does.\n\n[Website](https://ai-craftsman.dev) •\n[Install](#install) •\n[Commands](#commands) •\n[Docs](https://ai-craftsman.dev/docs) •\n[Contributing](#contributing)\n\n</div>\n\n---\n\n## A prompt asks. This enforces.\n\nYou can write \"always use final classes\" in your `CLAUDE.md`. Claude will\nfollow it, until the context fills up, or the task gets long, or the tenth file\nof a refactor. Instructions decay. That is not a discipline problem, it is an\narchitecture problem: nothing in the loop is checking.\n\nCraftsman puts the check in the loop. The same rules run as hooks on every\nWrite, as a gate in your CI, and as the criteria a reviewer agent reads. Layer\nviolations and missing `strict_types` are refused before the write lands,\neverything else is handed straight back to Claude as a finding it has to answer\nfor, and the same rule fails your pipeline if it reaches a pull request.\n\n## See it refuse\n\nClaude tries to write an entity that imports from the infrastructure layer. The\nfile never reaches your disk:\n\n<img src=\"https://raw.githubusercontent.com/BULDEE/ai-craftsman-superpowers/main/.github/assets/craftsman-demo.gif\" alt=\"The pre-write hook refusing a domain entity that imports infrastructure, then passing the corrected file\" width=\"100%\">\n\n<details>\n<summary>The same run as text</summary>\n\n```console\n$ ./check.sh User.before.php.txt /srv/app/src/Domain/User/User.php\n\n🚫 BLOCKED by AI Craftsman - 2 violation(s) detected before write:\n  ✗ LAYER001: Domain imports Infrastructure - DDD layer violation\n  ✗ PHP001: Missing declare(strict_types=1) in class file\nFix these before writing. Use // craftsman-ignore: <RULE_ID> to suppress.\nexit=2\n```\n\nNot a mockup: the recording pipes two fixtures through `hooks/pre-write-check.sh`\nand shows whatever it returns. Exit code 2 is the refusal.\n\n</details>\n\nClaude reads the same two lines you do, corrects the import, and writes again.\nThe correction is recorded; if that same rule keeps coming back across files, it\nis offered to you as a candidate instinct in `/craftsman:metrics`. And if the\nviolation ever reaches a pull request instead, the identical rule fails the\npipeline: one engine, one verdict, no drift between your editor and your CI.\n\n## Against what you already have\n\nYour real alternative is not another plugin. It is the `CLAUDE.md` you already\nwrote, and the linters you already run.\n\n| | CLAUDE.md alone | Linter and CI | Craftsman |\n|---|---|---|---|\n| Still holds at file 300 of a refactor | no | yes | yes |\n| Claude sees the violation *before* writing | no | no | yes |\n| Same verdict on your machine and in the pipeline | n/a | partial | yes |\n| Stops Claude from repeating the same mistake | no | no | yes |\n| Blocks a design decision made without a design pass | no | no | yes |\n\n## What it actually does\n\n**It blocks.** One rules engine, enforced identically in hooks and CI. No drift\nbetween what your editor allows and what your pipeline rejects. GitHub, GitLab\nBitbucket and Jenkins all get native annotations.\n\n**It learns.** Every violation you fix is recorded locally. A fix that recurs\n3+ times across 3+ files is promoted to a candidate instinct you approve in\n`/craftsman:metrics`, and it becomes a project skill with provenance. Detection\nis automatic, codification stays human-gated.\n\n**It proves.** \"Done\" requires evidence. A task cannot be marked complete\nwithout a verification record, and a failing test run revokes one that already\nexists.\n\nAnd it runs each job on the cheapest model that can do it: formatting a commit\non Haiku at low effort, an architecture review on Opus at high. You never pay\nOpus rates to write a commit message.\n\n<details>\n<summary><b>Seven more mechanisms</b>: the rules engine, the structural ratchet, the adversarial design panel, bias detection, and three others</summary>\n\n<br>\n\n1. **Rules Engine with 3-Level Inheritance** - Global → Project → Directory overrides. Short form (`PHP001: warn`) or long form (custom regex rules). Legacy code coexists with strict new code via directory-level relaxation.\n2. **Structural Ratchet** - a committed baseline records each file's structural high-water mark (complexity, size, longest function, import fan-out, suppression count). A file you touch may improve or stay equal, never regress: the mark tightens automatically on a green pass and only loosens through a documented, counted suppression. Untouched legacy is never punished for debt it already had.\n3. **Adversarial Design Panel** - three contradictors (YAGNI, invariants and boundaries, feasibility) attack a design during `/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.\n4. **Cognitive Bias Detector** - real-time detection of acceleration bias, scope creep, and over-optimization in your prompts. Two-stage language cascade: curated English patterns warn you directly, and every other language sits at one same tier behind it, carrying recall lexicons (CJK, Cyrillic and Thai included) that hand the call to the model already reading your prompt, which surfaces or silently drops it with the whole session as context. No second model and no network call. Language tags are BCP 47, so `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.\n5. **Real-Time Quality Gate** - progressive validation on every Write/Edit: regex (<50ms, always on) → LSP semantics (live, via the official LSP plugin for your language) → static analysis and architecture (PHPStan/ESLint/deptrac, opt-in per machine because running a project's analysers runs its code, see [SECURITY.md](SECURITY.md)). Degrades gracefully with zero tools installed.\n6. **Metrics & Trend Analysis** - SQLite-backed tracking of violations, corrections, and sessions, with 7-day/30-day trend views to identify your most-violated rules.\n7. **Security Rules** - SEC001-003 (hardcoded secrets, dynamic eval, SQL by concatenation) verified in hooks and CI, with their doctrine routed to Claude on block. Setup observes the repository and asks at most four plain-language questions.\n\n</details>\n\n## Install\n\n> [!WARNING]\n> Only install this plugin from the official sources below. Do not trust forks,\n> mirrors, or \"improved\" copies distributed elsewhere. Verification steps:\n> [SECURITY.md](SECURITY.md#pre-installation-verification).\n\n```bash\n# 1. Add the marketplace\n/plugin marketplace add BULDEE/ai-craftsman-superpowers\n\n# 2. Install the plugin\n/plugin install craftsman@ai-craftsman-superpowers\n\n# 3. Restart Claude Code, then configure\nexit\nclaude\n/craftsman:setup --quick\n```\n\n**Running [Hermes](https://hermes-agent.nousresearch.com) agents instead of (or next to) Claude Code?** The same repository is a native Hermes plugin:\n\n```bash\ngit clone https://github.com/BULDEE/ai-craftsman-superpowers ~/.hermes/plugins/craftsman\nhermes plugins enable craftsman\n```\n\nYour 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](docs/guides/hermes-quickstart.md); a full blocked-fixed-learned turn: [examples/hermes-agent](examples/hermes-agent/01-blocked-turn.md); design and threat model: [adapters/hermes/README.md](adapters/hermes/README.md).\n\nThat is the whole setup. `--quick` reads your repository and picks defaults; run\n`/craftsman:setup` without it to answer four plain-language questions instead.\n\n<details>\n<summary>Requirements, local install, and verifying it worked</summary>\n\n<br>\n\n**Requirements**\n\n- Claude Code v2.1.218 or later (`claude --version`). Older versions: install the frozen 3.9.x line.\n- `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.\n- `bash`, `grep`, `jq`, `sqlite3`. GNU coreutils is not required: the plugin runs on a stock macOS.\n\n**Install from a local clone**\n\n```bash\ngit clone https://github.com/BULDEE/ai-craftsman-superpowers.git /path/to/ai-craftsman-superpowers\n/plugin marketplace add /path/to/ai-craftsman-superpowers\n/plugin install craftsman@ai-craftsman-superpowers\n```\n\n**Verify**\n\n```bash\n/plugin\n# \"Installed\" tab → craftsman plugin should appear\n# \"Errors\" tab → check here if skills don't appear\n```\n\n</details>\n\n## Quick Start\n\n```bash\n# The full development cycle: design → spec → plan → implement → test → verify → commit\n/craftsman:workflow\nI need to add a forgot password feature.\n```\n\nEvery hook is already running by then. Individual entry points when you do not\nwant the whole cycle: `/craftsman:design` (DDD modeling), `/craftsman:debug`\n(systematic investigation), `/craftsman:challenge` (architecture review),\n`/craftsman:verify` (evidence before you call it done).\n\nNew to the methodology? The [Beginner Guide](docs/guides/beginner.md) walks\nthrough DDD concepts with worked examples, and [`/examples`](examples/) shows\neach command with its expected output.\n\n## Commands\n\nAll commands are explicitly invoked, never auto-triggered. Full reference:\n[COMMANDS-QUICK-REF.md](COMMANDS-QUICK-REF.md).\n\n| Category | Commands |\n|----------|----------|\n| Core methodology | `design`, `debug`, `plan`, `challenge`, `verify`, `workflow`, `spec`, `refactor`, `legacy`, `test`, `git`, `parallel` |\n| Scaffolding | `scaffold entity/usecase/component/hook/api-resource/pack` |\n| AI/ML engineering | `rag`, `mlops`, `agent-design` |\n| Utilities | `metrics`, `setup`, `team`, `healthcheck` |\n| CI/CD | `ci` |\n\nScaffolders offer a template variant before generating code (`bounded-context`\nvs `event-sourced` for entities, for instance). Agents that back these commands:\n`team-lead`, `architect` (no Write/Edit), `doc-writer`, `security-pentester`,\n`legacy-surgeon`, `ui-ux-director`, plus pack-specific reviewers for Symfony,\nReact and AI/ML. Full roster: [Agents Reference](docs/reference/agents.md).\n\n## Rules Engine\n\nOverride any rule per-project or per-directory with 3-level config inheritance:\n\n```\n~/.claude/.craft-config.yml          ← Global defaults\n  └─ {project}/.craft-config.yml     ← Project overrides\n      └─ {dir}/.craft-rules.yml      ← Directory overrides\n```\n\nShort form: `PHP001: warn` / `TS001: ignore`. Long form: custom rules with\nregex, severity, languages. Suppress a single occurrence inline with\n`// craftsman-ignore: RULE_ID`.\n\n## CI/CD Integration\n\nCI sources the same pack validators and the same rules engine as the hooks, so a\nrule cannot mean one thing on your machine and another in the pipeline. Export a\npipeline with `/craftsman:ci export`.\n\n| Provider | Template | Adapter |\n|----------|----------|---------|\n| GitHub Actions | `craftsman-quality-gate.yml` | Native: inline annotations and a PR comment |\n| GitLab CI | `.gitlab-ci.craftsman.yml` | Native: code-quality report and an MR note |\n| Bitbucket Pipelines | `bitbucket-pipelines.craftsman.yml` | Native: build report |\n| Jenkins | `Jenkinsfile.craftsman` | Native: a Checkstyle report read by Warnings Next Generation |\n\n## Cost and Privacy\n\nEverything above works with **zero API cost** beyond your normal Claude Code\nusage: regex validation, the rules engine, bias detection, CI export and metrics\nare local. One optional layer adds semantic analysis through Haiku agent hooks\nat roughly $0.15-0.30 per session of 50 Write/Edit operations. Turn it off with\n`agent_hooks: false` and everything else keeps working.\n\n**No telemetry, no analytics, no phone-home.** Metrics never leave your machine.\nEdited file content only reaches the Anthropic API when `agent_hooks: true`.\nCommand hooks write only to the local metrics DB and session state.\n\nA cloned repository is untrusted input, so the two capabilities that would\nexecute repository-supplied code (`trust_project_tools` and external pack paths)\nare off until **you** enable them in your own global config, and a project file\ncan never grant them. `tests/core/test-hostile-repo.sh` reproduces each attack\nthis model covers and asserts it fails. Full breakdown: [SECURITY.md](SECURITY.md).\n\n## Known Limitations\n\n**By design:** code rule violations block, bias detection only warns; no\nauto-commit; commands are explicitly invoked, never auto-triggered; methodology\nis opinionated (DDD/Clean Architecture).\n\n**Current constraints:** PHP, TypeScript, Python, Go and Rust get full rule\ncoverage, other languages basic support only;\nother language to the model to adjudicate in context; metrics are\nper-machine, not shared across a team; auto-fixing violations and IDE plugins\nare not supported by design.\n\nMore detail in the [FAQ](FAQ.md).\n\n## Going Deeper\n\n| | |\n|---|---|\n| [What's new in v4](https://github.com/BULDEE/ai-craftsman-superpowers/releases/latest) | 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](MIGRATION.md). |\n| [Architecture decisions](docs/adr/) | 28 ADRs covering every major design choice. Start with [ADR-0016](docs/adr/0016-v4-clean-break-native-first.md) and [ADR-0005](docs/adr/0005-knowledge-first-architecture.md). |\n| [Knowledge bundle](knowledge/) | The methodology ships as an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) bundle: plain Markdown, versioned in git, readable by Obsidian or any OKF consumer. Zero embeddings, zero index, zero external service. |\n| [Hermes quickstart](docs/guides/hermes-quickstart.md) | 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](examples/hermes-agent/demo.sh). |\n| [For non-developers](docs/guides/for-non-developers.md) | 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. |\n| [CLAUDE.md guidance](docs/guides/claude-md-best-practices.md) | What belongs in your global file, your project file, and what the plugin should own instead. |\n| [Hooks reference](docs/reference/hooks.md) | Every hook, exit code and rule ID, including the Circuit Breaker and the Iron Law Pattern. |\n| [Troubleshooting](TROUBLESHOOTING.md) | When a skill does not appear, a hook does not fire, or a rule fires too often. |\n\n## Using with the Superpowers Plugin\n\nCraftsman and [Superpowers](https://github.com/anthropics/claude-code-plugins/tree/main/superpowers)\nload simultaneously with no conflicts. Superpowers orchestrates the workflow\n(brainstorming, planning, TDD, subagent-driven development); Craftsman enforces\nquality inside it.\n\n<details>\n<summary>The combined loop, step by step</summary>\n\n```\n1. /superpowers:brainstorming     → Design the solution collaboratively\n2. /superpowers:writing-plans     → Create implementation plan\n3. /superpowers:subagent-driven-development → Execute with fresh subagents\n   ├── Craftsman hooks fire on every Write/Edit (real-time quality gate)\n   ├── /craftsman:design           → DDD modeling when domain entities appear\n   └── /craftsman:challenge        → Architecture review at milestones\n4. /craftsman:verify              → Evidence-based verification before commit\n5. /superpowers:finishing-a-development-branch → PR and merge\n```\n\n</details>\n\n## Philosophy\n\n> \"Weeks of coding can save hours of planning.\"\n\nDesign before code. Test-first. Systematic debugging over random fixes. YAGNI.\nClean Architecture, dependencies point inward. Make it work, make it right, make\nit fast, in that order.\n\nPragmatism over dogmatism: 80% coverage on critical paths beats 100% everywhere;\nDDD for complex domains, not every domain; concrete first, abstract when\nactually needed.\n\n## Contributing\n\nContributions welcome. Fork, branch, follow the methodology (`/craftsman:design`\nfirst), add tests, open a PR. Details in [CONTRIBUTING.md](CONTRIBUTING.md).\n\nLooking for a place to start? The [good first issues](https://github.com/BULDEE/ai-craftsman-superpowers/labels/good%20first%20issue)\nare real work, not busywork: new language packs, rule coverage, examples,\ntranslations.\n\n## Contributors\n\n<table>\n  <tr>\n    <td align=\"center\" width=\"180\">\n      <a href=\"https://github.com/woprrr\"><img src=\"https://github.com/woprrr.png\" width=\"72\" alt=\"\" style=\"border-radius:50%\"><br><b>Alexandre Mallet</b></a><br>\n      <sub>Author and maintainer</sub><br>\n      <sub><a href=\"https://buldee.com\">BULDEE</a></sub>\n    </td>\n    <td align=\"center\" width=\"180\">\n      <a href=\"https://github.com/Lucr4m\"><img src=\"https://github.com/Lucr4m.png\" width=\"72\" alt=\"\" style=\"border-radius:50%\"><br><b>Marc Lucas</b></a><br>\n      <sub>Hooks architecture and config resolution</sub><br>\n      <sub>CEO, <a href=\"https://www.malucasfire.dev\">M.A. LucasFireDev</a></sub>\n    </td>\n  </tr>\n</table>\n\n[**Marc Lucas**](https://github.com/Lucr4m) ([LinkedIn](https://www.linkedin.com/in/marc-lucas-75a012120/)), CEO of [M.A. LucasFireDev](https://www.malucasfire.dev), 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.\n\nYour name belongs here too.\n\n## Sponsors\n\n| Sponsor | Description |\n|---------|-------------|\n| **[BULDEE](https://buldee.com)** | Building the future of AI-assisted development |\n| **[M.A. LucasFireDev](https://www.malucasfire.dev)** | PHP/Symfony consultancy, sponsoring the plugin with engineering time |\n\nInterested in sponsoring? [Contact us](https://github.com/BULDEE/ai-craftsman-superpowers/discussions)\n\n## Support\n\n[Discord](https://discord.gg/eBpgHAGu) •\n[Issues](https://github.com/BULDEE/ai-craftsman-superpowers/issues) •\n[Discussions](https://github.com/BULDEE/ai-craftsman-superpowers/discussions) •\n[Changelog](CHANGELOG.md)\n\nApache License 2.0, see [LICENSE](LICENSE).\n\n---\n\n<div align=\"center\">\n\n**If Craftsman refused a write you would have merged, star the repository.**\n<br>\nIt is the only metric this project collects.\n\n<br>\n\nForged by [Alexandre Mallet](https://github.com/woprrr) · Sponsored by [BULDEE](https://buldee.com) & [M.A. LucasFireDev](https://www.malucasfire.dev)\n\n[ai-craftsman.dev](https://ai-craftsman.dev)\n\n</div>\n",
  "bytes": 19640,
  "sha": "b5cfc5a9d09fa37a83388ec0b44ecf8ddf97a311b16dd325827175ea0468ef25",
  "repo_slug": "buldee/ai-craftsman-superpowers",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_buldee_ai_craftsman_superpowers_ai_craft_b8f98cb1/readme"
}