convez.ai
SkillDesenvolvimento WebAvançado
BULDEE

AI Craftsman Superpowers

BULDEE/ai-craftsman-superpowers

Metodologia de engenharia sênior para Claude Code com DDD e Clean Architecture

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin 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-superpowers

1 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

Estrelas
35
Forks
5
Acompanhando
1
Saúde
87%
Último commit
há 2 dias
Versão
v4.17.0
Issues abertas
5
Contribuidores
2

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

License Claude Code Version Commands Agents PRs Welcome

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 --version to 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 HookTriggerModelPurpose
DDD VerifierEach Write/EditHaikuLayer violations, aggregate boundaries, naming
Sentry ContextEach Write/EditHaikuError context from Sentry (if configured)
Architecture AnalyzerSession startHaikuBuild project context map
Final ReviewerSession endHaikuValidate 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

CommandPurpose
/craftsman:designDDD design with challenge phases (Understand → Challenge → Recommend → Implement)
/craftsman:debugSystematic debugging using ReAct pattern
/craftsman:planStructured planning & execution with checkpoints
/craftsman:challengeSenior architecture review and code challenge
/craftsman:verifyEvidence-based verification before completion claims
/craftsman:workflowFlexible development pipeline (design → spec → plan → implement → test → verify → commit)
/craftsman:specSpecification-first development (TDD/BDD)
/craftsman:refactorSystematic refactoring with behavior preservation
/craftsman:testPragmatic testing following Fowler/Martin principles
/craftsman:gitSafe git workflow with destructive command protection
/craftsman:parallelParallel agent orchestration for independent tasks

Scaffolding

CommandPurpose
/craftsman:scaffold entityDDD entity with Value Objects, Events, Tests
/craftsman:scaffold usecaseUse case with Command/Handler pattern
/craftsman:scaffold componentReact component with TypeScript, tests, Storybook
/craftsman:scaffold hookTanStack Query hook with tests
/craftsman:scaffold api-resourceAPI Platform resource with State Provider
/craftsman:scaffold packCreate new community pack

AI/ML Engineering

CommandPurpose
/craftsman:ragDesign RAG pipelines (ingestion, retrieval, generation)
/craftsman:mlopsAudit ML projects for production readiness
/craftsman:agent-designDesign AI agents using 3P pattern (Perceive/Plan/Perform)

Utilities

CommandPurpose
/craftsman:scaffoldUnified scaffolder for all types (entity, usecase, component, hook, api-resource, pack)
/craftsman:metricsDisplay quality metrics dashboard (violations, trends, sessions)
/craftsman:setupInteractive setup wizard (DISC profile, stack, packs). Use --quick for zero-question auto-setup
/craftsman:teamCreate and manage agent teams for collaborative tasks

CI/CD Integration

CommandPurpose
/craftsman:ciExport quality gates to CI/CD pipeline (GitHub, GitLab, Bitbucket, Jenkins)

Features

Bias Protection (Active by Default)

Hooks automatically detect and warn about cognitive biases:

BiasTrigger (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:

HookEventPurpose
DDD Verifier (Haiku)PostToolUseChecks layer violations, aggregate boundaries, value objects, naming
Sentry Context (Haiku)PostToolUseInjects error context from Sentry for edited files
Project Analyzer (Haiku)InstructionsLoadedBuilds architectural context map at session start
Final Reviewer (Haiku)StopValidates 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:

AgentRoleModel
team-leadOrchestrator — delegates, challenges, never codesSonnet
backend-craftsmanPHP/Symfony expert (Symfony.com + API Platform refs)Sonnet
frontend-craftsmanReact/TS expert (65 Vercel best practices)Sonnet
architectDDD/Clean Architecture validation (read-only)Sonnet
ai-engineerRAG, LLM, MCP server, agent designSonnet
api-craftsmanAPI Platform 4, REST/HATEOAS, OpenAPISonnet
ui-ux-directorUX, WCAG 2.1 AA, design tokensSonnet
doc-writerADRs, README, CHANGELOG, runbooksHaiku
security-pentesterSecurity vulnerability detectionSonnet
symfony-reviewerSymfony/DDD best practicesSonnet
react-reviewerReact patterns and hooksSonnet

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.

RuleLanguageCheck
PHP001PHPdeclare(strict_types=1) required
PHP002PHPfinal class on all classes
PHP003PHPNo public setters
PHP004PHPNo new DateTime() direct usage
PHP005PHPNo empty catch blocks
TS001TypeScriptNo any types
TS002TypeScriptNamed exports only
TS003TypeScriptNo non-null assertions (!)
PY001PythonNo short variable names (min 3 chars)
PY002PythonFunction max 25 lines
PY003PythonReturn type hints required
PY004PythonNo bare except:
PY005PythonNo mutable default arguments
SH001Bashset -u required (not in sourced libs)
SH002BashFunction max 30 lines
SH003BashNo short variable names
SH004BashNo eval usage
SH005BashNo unquoted variables in file ops
LAYER001PHPDomain cannot import Infrastructure
LAYER002PHPDomain cannot import Presentation
LAYER003PHPApplication 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:

ProviderTemplateAnnotations
GitHub Actionscraftsman-quality-gate.yml::error inline
GitLab CI.gitlab-ci.craftsman.ymlcodequality artifact
Bitbucket Pipelinesbitbucket-pipelines.craftsman.ymlReports API
JenkinsJenkinsfile.craftsmanConsole 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:

PackTemplateUse Case
Symfonybounded-contextStandard DDD entity
Symfonycrud-apiAPI Platform 4 CRUD
Symfonyevent-sourcedEvent Sourcing + Projections
Reactbounded-contextStandard TanStack Query hook
Reactform-heavyMulti-step wizard + Zod
Reactdashboard-dataTanStack Table + Recharts

Schema Validation & Safety (v2.2.0+)

  • Hooks schema validation — session-start.sh validates 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-ml pack is explicitly enabled in your plugin config. Users without it get zero errors.

Prerequisites

  • Node.js 20+
  • Ollama with nomic-embed-text model

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 GlobalPut in ProjectLet Plugin Handle
DISC profileArchitectureCode enforcement
Communication styleKey entitiesDesign patterns
Personal biasesExternal servicesCanonical examples
Stack versionsProject rulesSkill routing

See CLAUDE.md Best Practices Guide for complete documentation.

Architecture Decisions

See /docs/adr for Architecture Decision Records:

Examples

See /examples for detailed usage examples:

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:

ConcernSuperpowersCraftsman
Workflow orchestrationBrainstorming, 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 managementDispatch, review loopsQuality 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

  1. Design before code - Understand, challenge, then implement
  2. Test-first - If you can't write the test, you don't understand the requirement
  3. Systematic debugging - No random fixes, find root cause first
  4. YAGNI - Build what's needed, not what might be needed
  5. Clean Architecture - Dependencies point inward
  6. Make it work, make it right, make it fast - In that order

Pragmatism over Dogmatism

DogmaticPragmatic (our choice)
100% test coverageCritical paths covered (80%)
Pure DDD everywhereDDD for complex domains only
Always abstractConcrete first, abstract when needed

Security

This plugin prioritizes transparency and safety:

ComponentBehaviorModifies Files?
CommandsPrompt templatesOnly when instructed
Reviewer AgentsCode analysis (11 agents)Never (read-only)
Craftsman AgentsImplementation (7 agents)When instructed
Command HooksValidation scripts (15 scripts)Never (read-only, except metrics DB + session state)
Agent HooksSemantic 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.

  1. Fork the repository
  2. Create a feature branch
  3. Follow the craftsman methodology (use /craftsman:design first!)
  4. Add tests for new features
  5. 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:

  1. /plugin → "Installed" tab
  2. Select craftsman plugin
  3. Check "Hooks enabled" status

License

Apache License 2.0 - See LICENSE

Support

Sponsors

This project is proudly sponsored by:

SponsorDescription
BULDEEBuilding the future of AI-assisted development
Time Hacking LimitedMaximizing developer productivity

Interested in sponsoring? Contact us

Acknowledgments


Made with craftsmanship by Alexandre Mallet

Sponsored by BULDEE & Time Hacking Limited

Ver o original no GitHub

Bom para

Relacionados