AI Craftsman Superpowers
BULDEE/ai-craftsman-superpowers
Metodologia de engenharia sênior para Claude Code com DDD e Clean Architecture
Ver no GitHubPlugin Claude Code que transforma o assistente em engenheiro sênior disciplinado. Implementa Domain-Driven Design, Clean Architecture e Test-Driven Development com arquitetura multi-pack (core, symfony, react), sistema inteligente de scaffold e agents especializados em design, debug, segurança e pentesting.
Instalação
npx convez-ai BULDEE/ai-craftsman-superpowers1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Design de entidades e bounded contexts seguindo DDD
- Debug sistemático de problemas com padrão ReAct
- Planejamento e implementação de features complexas
- Pentesting e auditoria de segurança
- Geração de scaffolds TypeScript com tipos branded
- Validação arquitetural e revisão de código
Veredito

Ferramenta robusta para times que levam engenharia a sério. Excelente para arquitetura corporativa, mas requer investimento em aprendizado de DDD e Clean Architecture. Custo por sessão (~$0.15-0.30) é justificado pela qualidade arquitetural entregue.
README
A tradução para o português deste README ainda está na fila.
AI Craftsman Superpowers
Transform Claude into a disciplined Senior Software Craftsman
Installation • Skills • Security • Contributing
Senior craftsman methodology for Claude Code. DDD, Clean Architecture, TDD.
Transform Claude Code into a disciplined software engineer with battle-tested methodologies.
Requirements
- Claude Code v1.0.33 or later
- Run
claude --versionto check
Installation
From GitHub (Recommended)
# Step 1: Add the marketplace
/plugin marketplace add BULDEE/ai-craftsman-superpowers
# Step 2: Install the plugin
/plugin install craftsman@BULDEE-ai-craftsman-superpowers
# Step 3: Restart Claude Code
exit
claude
From Local Path
# If you cloned the repo locally
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 Installation
# Open plugin manager
/plugin
# Go to "Installed" tab to see craftsman plugin
# Go to "Errors" tab if skills don't appear
API Cost Model
The plugin uses AI agent hooks for deep semantic analysis beyond regex. These are optional and can be disabled.
| Agent Hook | Trigger | Model | Purpose |
|---|---|---|---|
| DDD Verifier | Each Write/Edit | Haiku | Layer violations, aggregate boundaries, naming |
| Sentry Context | Each Write/Edit | Haiku | Error context from Sentry (if configured) |
| Architecture Analyzer | Session start | Haiku | Build project context map |
| Final Reviewer | Session end | Haiku | Validate architecture (strict mode only) |
Estimated cost: ~$0.15-0.30 per session (50 Write/Edit operations)
Opt-out: Set agent_hooks: false in plugin config to disable all agent hooks. Regex-based validation (Level 1) and static analysis (Level 2) continue to work without agent hooks.
Quick Start
After installation, try:
# Design a new entity (follows DDD phases)
/craftsman:design
I need to create a User entity for an e-commerce platform.
# Debug an issue systematically (ReAct pattern)
/craftsman:debug
I have a memory leak in my Node.js app.
# Plan a feature implementation
/craftsman:plan
I need to migrate our API to microservices.
# Review code for architecture issues
/craftsman:challenge
[paste your code]
# Run the full development workflow (design → spec → plan → implement → test → verify → commit)
/craftsman:workflow
I need to add a forgot password feature.
# Quick setup (zero questions, smart defaults)
/craftsman:setup --quick
See /examples for detailed usage examples with expected outputs.
Why Craftsman? — 6 Core Differentiators
What makes this plugin genuinely unique in the Claude Code ecosystem:
1. Correction Learning System
Records every violation fix users make and injects correction trends at next session start. SQLite-backed feedback loop that progressively teaches Claude the exact patterns your codebase rejects. Cross-file pattern detection suggests project-wide fixes when 3+ files share the same violation. Unique in the ecosystem — no other Claude Code plugin creates this behavioral feedback loop.
2. Rules Engine with 3-Level Inheritance
Enterprise-ready rule customization: Global → Project → Directory overrides. Short form (PHP001: warn) and long form (custom rules with regex, message, severity, languages, paths). Legacy code coexists with strict new code via directory-level relaxation. Python-backed YAML parser with bash 3.2 shell compatibility.
3. Cognitive Bias Detector
Real-time detection of acceleration bias, scope creep, and over-optimization in user prompts. Context-aware bilingual FR/EN pattern matching on UserPromptSubmit hook — requires imperative verb context to reduce false positives. Non-blocking warnings that encourage reflection before action.
4. Real-Time Quality Gate
3-level progressive validation on every Write/Edit:
- Level 1: Regex (<50ms) — strict_types, final, any, setters. Always active.
- Level 2: Static analysis (<2s) — PHPStan, ESLint. When tools installed.
- Level 3: Architecture (<2s) — deptrac, dependency-cruiser. When tools installed.
Graceful degradation: works with zero tools installed (Level 1 only).
5. Multi-Provider CI Pipeline
Same rules engine runs in hooks (real-time) AND CI (pipeline) with zero drift — CI sources the same pack validators as hooks. 4 providers: GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins. Adapter pattern: detect → run → annotate → comment → exit.
6. Metrics & Trend Analysis
SQLite-backed tracking of violations, corrections, and sessions. 7-day and 30-day trend views. Data-driven quality improvement: identify most-violated rules and adjust strictness. Currently per-machine — team metrics sync planned for v4.
No other Claude Code plugin combines all 6: learning from past mistakes, enterprise rule customization, cognitive protection, real-time validation, zero CI drift, and measurable quality trends.
Additional Features
Model Tiering
Configure which Claude model each agent uses. Cost-optimize by assigning Haiku to documentation tasks and Sonnet to complex analysis.
Atomic Commit Enforcement
Stop hook warns when >15 files modified in a session and caps inspection at 20 files, encouraging small focused commits.
Circuit Breaker
Production-grade protection for external services (Sentry). 3 states: closed → open → half-open. File-based cache with TTL/LRU eviction serves stale data during outages.
Iron Law Pattern
Design-first methodology enforced through hooks: bias detection warns when domain modeling without /craftsman:design. Prevents impulsive architecture changes.
Commands
All commands are explicitly invoked with /craftsman:command-name. See ADR-0007 for the rationale.
Core Methodology
| Command | Purpose |
|---|---|
/craftsman:design | DDD design with challenge phases (Understand → Challenge → Recommend → Implement) |
/craftsman:debug | Systematic debugging using ReAct pattern |
/craftsman:plan | Structured planning & execution with checkpoints |
/craftsman:challenge | Senior architecture review and code challenge |
/craftsman:verify | Evidence-based verification before completion claims |
/craftsman:workflow | Flexible development pipeline (design → spec → plan → implement → test → verify → commit) |
/craftsman:spec | Specification-first development (TDD/BDD) |
/craftsman:refactor | Systematic refactoring with behavior preservation |
/craftsman:test | Pragmatic testing following Fowler/Martin principles |
/craftsman:git | Safe git workflow with destructive command protection |
/craftsman:parallel | Parallel agent orchestration for independent tasks |
Scaffolding
| Command | Purpose |
|---|---|
/craftsman:scaffold entity | DDD entity with Value Objects, Events, Tests |
/craftsman:scaffold usecase | Use case with Command/Handler pattern |
/craftsman:scaffold component | React component with TypeScript, tests, Storybook |
/craftsman:scaffold hook | TanStack Query hook with tests |
/craftsman:scaffold api-resource | API Platform resource with State Provider |
/craftsman:scaffold pack | Create new community pack |
AI/ML Engineering
| Command | Purpose |
|---|---|
/craftsman:rag | Design RAG pipelines (ingestion, retrieval, generation) |
/craftsman:mlops | Audit ML projects for production readiness |
/craftsman:agent-design | Design AI agents using 3P pattern (Perceive/Plan/Perform) |
Utilities
| Command | Purpose |
|---|---|
/craftsman:scaffold | Unified scaffolder for all types (entity, usecase, component, hook, api-resource, pack) |
/craftsman:metrics | Display quality metrics dashboard (violations, trends, sessions) |
/craftsman:setup | Interactive setup wizard (DISC profile, stack, packs). Use --quick for zero-question auto-setup |
/craftsman:team | Create and manage agent teams for collaborative tasks |
CI/CD Integration
| Command | Purpose |
|---|---|
/craftsman:ci | Export quality gates to CI/CD pipeline (GitHub, GitLab, Bitbucket, Jenkins) |
Features
Bias Protection (Active by Default)
Hooks automatically detect and warn about cognitive biases:
| Bias | Trigger (context-aware) | Protection |
|---|---|---|
| Acceleration | "fais ça vite", "just do it", "skip the design" | STOP - Design first |
| Scope Creep | "et aussi ajoutons", "let's also add" | STOP - Is this in scope? |
| Over-Optimization | "abstraire ce pattern", "make it generic" | STOP - YAGNI |
Semantic Intelligence (v1.3.0+)
Agent hooks provide semantic analysis beyond regex:
| Hook | Event | Purpose |
|---|---|---|
| DDD Verifier (Haiku) | PostToolUse | Checks layer violations, aggregate boundaries, value objects, naming |
| Sentry Context (Haiku) | PostToolUse | Injects error context from Sentry for edited files |
| Project Analyzer (Haiku) | InstructionsLoaded | Builds architectural context map at session start |
| Final Reviewer (Haiku) | Stop | Validates architecture before session end (strict mode) |
Correction Learning (v1.3.0+)
The plugin detects when you fix Claude-generated code and records patterns in the metrics database. At session start, recent correction trends are injected so Claude learns from past mistakes. View trends with /craftsman:metrics.
Sentry Channel Integration (v1.4.0+)
Sentry MCP server is bound as a channel. When editing files, the PostToolUse agent hook automatically queries Sentry for related errors and injects context. Configure via:
# In plugin settings
sentry_org: your-org
sentry_project: your-project
sentry_token: (stored securely)
Specialized Agents (v1.5.0)
11 agents — 4 reviewers + 7 craftsmen:
| Agent | Role | Model |
|---|---|---|
team-lead | Orchestrator — delegates, challenges, never codes | Sonnet |
backend-craftsman | PHP/Symfony expert (Symfony.com + API Platform refs) | Sonnet |
frontend-craftsman | React/TS expert (65 Vercel best practices) | Sonnet |
architect | DDD/Clean Architecture validation (read-only) | Sonnet |
ai-engineer | RAG, LLM, MCP server, agent design | Sonnet |
api-craftsman | API Platform 4, REST/HATEOAS, OpenAPI | Sonnet |
ui-ux-director | UX, WCAG 2.1 AA, design tokens | Sonnet |
doc-writer | ADRs, README, CHANGELOG, runbooks | Haiku |
security-pentester | Security vulnerability detection | Sonnet |
symfony-reviewer | Symfony/DDD best practices | Sonnet |
react-reviewer | React patterns and hooks | Sonnet |
Code Rule Enforcement (v1.2.0+)
Hooks validate your code automatically with 3-level analysis:
Level 1 — Fast Regex (<50ms): Runs on every write/edit.
| Rule | Language | Check |
|---|---|---|
| PHP001 | PHP | declare(strict_types=1) required |
| PHP002 | PHP | final class on all classes |
| PHP003 | PHP | No public setters |
| PHP004 | PHP | No new DateTime() direct usage |
| PHP005 | PHP | No empty catch blocks |
| TS001 | TypeScript | No any types |
| TS002 | TypeScript | Named exports only |
| TS003 | TypeScript | No non-null assertions (!) |
| PY001 | Python | No short variable names (min 3 chars) |
| PY002 | Python | Function max 25 lines |
| PY003 | Python | Return type hints required |
| PY004 | Python | No bare except: |
| PY005 | Python | No mutable default arguments |
| SH001 | Bash | set -u required (not in sourced libs) |
| SH002 | Bash | Function max 30 lines |
| SH003 | Bash | No short variable names |
| SH004 | Bash | No eval usage |
| SH005 | Bash | No unquoted variables in file ops |
| LAYER001 | PHP | Domain cannot import Infrastructure |
| LAYER002 | PHP | Domain cannot import Presentation |
| LAYER003 | PHP | Application cannot import Presentation |
Level 2 — Static Analysis (<2s): PHPStan, ESLint (when installed). Graceful degradation if tools are absent.
Level 3 — Architecture (<2s): Deptrac, dependency-cruiser (when installed).
Suppressing rules: Add // craftsman-ignore: RULE_ID inline to suppress a specific rule.
Violations are blocking (exit 2) — Claude must fix the code before proceeding. All violations are recorded in a local SQLite database for trend tracking via /craftsman:metrics.
Custom Rule Engine (v2.1.0+)
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.
CI/CD Integration (v2.1.0+)
Same rules engine runs in hooks (real-time) AND CI (pipeline). 4 providers with adapter pattern:
| Provider | Template | Annotations |
|---|---|---|
| GitHub Actions | craftsman-quality-gate.yml | ::error inline |
| GitLab CI | .gitlab-ci.craftsman.yml | codequality artifact |
| Bitbucket Pipelines | bitbucket-pipelines.craftsman.yml | Reports API |
| Jenkins | Jenkinsfile.craftsman | Console output |
Use /craftsman:ci export to generate or craftsman-ci.sh init --provider from CLI.
Circuit Breaker (v2.1.0+)
Production-grade protection for external services (Sentry). 3 states: closed → open → half-open. File-based cache with TTL/LRU eviction serves stale data during outages.
Pack Template Variants (v2.1.0+)
Each scaffolder offers template selection before generating code:
| Pack | Template | Use Case |
|---|---|---|
| Symfony | bounded-context | Standard DDD entity |
| Symfony | crud-api | API Platform 4 CRUD |
| Symfony | event-sourced | Event Sourcing + Projections |
| React | bounded-context | Standard TanStack Query hook |
| React | form-heavy | Multi-step wizard + Zod |
| React | dashboard-data | TanStack Table + Recharts |
Schema Validation & Safety (v2.2.0+)
- Hooks schema validation —
session-start.shvalidates all hook events against the supported set at startup - Atomic commit enforcement — Stop hook warns when >15 files modified, caps inspection at 20
- Monorepo sampling — InstructionsLoaded switches to directory-level analysis for large codebases (>100 files)
Advanced: Knowledge Base RAG (Optional)
The plugin includes an optional MCP server for RAG (Retrieval-Augmented Generation) over local documents.
Note: The plugin is fully functional without the MCP. This is a power-user feature. The MCP server is conditional — it only activates when the
ai-mlpack is explicitly enabled in your plugin config. Users without it get zero errors.
Prerequisites
- Node.js 20+
- Ollama with
nomic-embed-textmodel
Setup
# 1. Enable the ai-ml pack in your plugin config
# Set packs: "ai-ml" (or "symfony,react,ai-ml") in Claude Code plugin settings
# 2. Install Ollama
brew install ollama && ollama pull nomic-embed-text
ollama serve # Keep running
# 3. Restart Claude Code — the MCP server auto-installs and builds on first run
# 4. Create knowledge directory & add documents
mkdir -p ~/.claude/ai-craftsman-superpowers/knowledge
cp ~/your-docs/*.pdf ~/.claude/ai-craftsman-superpowers/knowledge/
# 5. Index knowledge base (from plugin cache directory)
cd ~/.claude/plugins/cache/ai-craftsman-superpowers/craftsman/*/packs/ai-ml/mcp/knowledge-rag
npm run index:ollama
See Local RAG Setup Guide and MCP Reference for detailed instructions.
Why Ollama? 100% local, free, private. See ADR-0002.
CLAUDE.md Configuration
Understanding how to structure your CLAUDE.md files is crucial for optimal plugin integration.
Priority Hierarchy
1. Explicit user instruction ← Highest
2. Project CLAUDE.md (./CLAUDE.md)
3. Plugin (skills, hooks, knowledge)
4. Global CLAUDE.md (~/.claude/CLAUDE.md) ← Lowest
Quick Rules
| Put in Global | Put in Project | Let Plugin Handle |
|---|---|---|
| DISC profile | Architecture | Code enforcement |
| Communication style | Key entities | Design patterns |
| Personal biases | External services | Canonical examples |
| Stack versions | Project rules | Skill routing |
See CLAUDE.md Best Practices Guide for complete documentation.
Architecture Decisions
See /docs/adr for Architecture Decision Records:
- ADR-0001: Skills over Prompts
- ADR-0002: Ollama over OpenAI
- ADR-0003: SQLite over pgvector
- ADR-0004: 3P Agent Pattern
- ADR-0005: Knowledge-First Architecture
- ADR-0006: Project-Specific Knowledge
- ADR-0007: Commands over Skills
- ADR-0008: Inline SQLite over Bash Expansion
- ADR-0009: Command Hooks over Agent Hooks
- ADR-0010: Model Tiering Strategy
- ADR-0011: Context Fork Strategy
- ADR-0012: Progressive Disclosure
- ADR-0013: Workflow Orchestrator
- ADR-0014: Quick Setup Mode
Examples
See /examples for detailed usage examples:
- Design: Create Entity
- Debug: Memory Leak
- Challenge: Code Review
- Plan: Migration
- Refactor: Extract Value Object
- Git: Safe Commit
- Test: Testing Strategy
- Verify: Pre-Commit Verification
- Healthcheck: Plugin Diagnostic
- Team: Fullstack Feature
- Parallel: Code Review
- Setup: Quick Setup
- Workflow: Feature Development
- Workflow: Resume from Implement
Architecture
hooks/ → Real-time validation (SessionStart → PostToolUse → Stop → SessionEnd)
hooks/lib/ → Shared libraries (pack-loader, config, rules-engine, metrics, static-analysis)
commands/ → Core user-invoked workflows (20 skills)
agents/ → Core agents (11) + pack symlinks
knowledge/ → Core methodology (DDD, Clean Architecture, patterns)
packs/ → Loadable language packs
symfony/ → PHP/Symfony pack (validators, agents, knowledge, templates)
react/ → React/TypeScript pack (validators, agents, knowledge, templates)
ai-ml/ → AI/ML pack (agents, knowledge, commands)
ci/ → CI pipeline integration (adapter pattern)
Using with Superpowers Plugin
Craftsman and Superpowers are complementary. Superpowers provides workflow orchestration (brainstorming, planning, TDD, subagent-driven development). Craftsman provides domain-specific quality enforcement (DDD rules, architectural validation, correction learning).
Recommended development flow:
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
What each plugin handles:
| Concern | Superpowers | Craftsman |
|---|---|---|
| Workflow orchestration | Brainstorming, planning, TDD | - |
| Code quality enforcement | - | Hooks, rules engine, correction learning |
| Architecture validation | - | Layer boundaries, DDD patterns |
| Bias detection | - | Acceleration, scope creep, over-optimization |
| CI pipeline | - | Multi-provider adapter pattern |
| Subagent management | Dispatch, review loops | Quality gate on subagent output |
Both plugins load simultaneously. No configuration needed — hooks.json events do not conflict.
Philosophy
"Weeks of coding can save hours of planning."
Core Principles
- Design before code - Understand, challenge, then implement
- Test-first - If you can't write the test, you don't understand the requirement
- Systematic debugging - No random fixes, find root cause first
- YAGNI - Build what's needed, not what might be needed
- Clean Architecture - Dependencies point inward
- Make it work, make it right, make it fast - In that order
Pragmatism over Dogmatism
| Dogmatic | Pragmatic (our choice) |
|---|---|
| 100% test coverage | Critical paths covered (80%) |
| Pure DDD everywhere | DDD for complex domains only |
| Always abstract | Concrete first, abstract when needed |
Security
This plugin prioritizes transparency and safety:
| Component | Behavior | Modifies Files? |
|---|---|---|
| Commands | Prompt templates | Only when instructed |
| Reviewer Agents | Code analysis (11 agents) | Never (read-only) |
| Craftsman Agents | Implementation (7 agents) | When instructed |
| Command Hooks | Validation scripts (15 scripts) | Never (read-only, except metrics DB + session state) |
| Agent Hooks | Semantic analysis (4 agents, Haiku) | Never (read-only) |
Hooks use exit codes — Bias detection warns (exit 0). Code rule violations block (exit 2) to enforce quality standards. See Hooks Reference.
See SECURITY.md for full security documentation.
Pre-Installation Verification
Verify the plugin before installing:
# Clone and inspect
git clone https://github.com/BULDEE/ai-craftsman-superpowers.git
cd ai-craftsman-superpowers
# Review hooks (the only executable code)
cat hooks/bias-detector.sh
cat hooks/post-write-check.sh
cat hooks/pre-write-check.sh
cat hooks/session-metrics.sh
# Verify no network calls
grep -r "curl\|wget\|fetch\|http" hooks/
# Should return nothing (hooks are 100% local)
Known Limitations
By Design
- Hooks block on violations — Code rule violations are blocking (exit 2); bias detection is warning-only (exit 0)
- No auto-commit — All git operations require explicit user action
- Commands are opinionated — Follows DDD/Clean Architecture strictly
- Explicit invocation — Commands are deliberately invoked, not auto-triggered
Current Constraints
- PHP/TypeScript focus — Other languages have basic support only
- RAG requires Ollama — No cloud embedding providers supported
- English/French only — Bias detection patterns in EN/FR
Not Supported
- ❌ Auto-fixing violations (by design, for safety)
- ❌ IDE plugins (Claude Code CLI only)
Contributing
We welcome contributions! This is an open source project.
- Fork the repository
- Create a feature branch
- Follow the craftsman methodology (use
/craftsman:designfirst!) - Add tests for new features
- Submit a PR
See CONTRIBUTING.md for detailed guidelines.
Ideas for Contributions
- New skills for other frameworks (Django, Rails, Go)
- Additional language support for hooks
- Improved examples and documentation
- Integration tests
- Translations
Troubleshooting
Commands not appearing in autocompletion
Symptom: /cra<TAB> doesn't suggest craftsman commands, but they work when typed fully.
Cause: Version mismatch between plugin.json and marketplace.json prevents cache updates.
Fix:
# Force update the plugin
claude plugin update craftsman@ai-craftsman-superpowers
# If still not working, clear cache and reinstall
rm -rf ~/.claude/plugins/cache/ai-craftsman-superpowers
claude plugin install craftsman@ai-craftsman-superpowers
# Restart Claude Code
exit
claude
Skills not loading
# Clear plugin cache
rm -rf ~/.claude/plugins/cache
# Restart Claude Code
exit
claude
# Reinstall plugin
/plugin uninstall craftsman@BULDEE-ai-craftsman-superpowers
/plugin install craftsman@BULDEE-ai-craftsman-superpowers
Check for errors
# Open plugin manager
/plugin
# Go to "Errors" tab
# Check for missing dependencies or path issues
Hooks not running
Verify hooks are enabled in your scope:
/plugin→ "Installed" tab- Select craftsman plugin
- Check "Hooks enabled" status
License
Apache License 2.0 - See LICENSE
Support
- Discord: Join our community
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Claude Code Plugins
Sponsors
This project is proudly sponsored by:
| Sponsor | Description |
|---|---|
| BULDEE | Building the future of AI-assisted development |
| Time Hacking Limited | Maximizing developer productivity |
Interested in sponsoring? Contact us
Acknowledgments
- Built following Anthropic's official plugin guidelines
- Inspired by DDD, Clean Architecture, and TDD principles
- Thanks to all contributors and sponsors!
Made with craftsmanship by Alexandre Mallet
Sponsored by BULDEE & Time Hacking Limited