AI Craftsman Superpowers

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.

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]

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. Bilingual FR/EN pattern matching on UserPromptSubmit hook. Non-blocking warnings that encourage reflection before action. Currently regex-based — semantic analysis planned for v3.

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 v3.

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

Scaffolding

AI/ML Engineering

Utilities

CI/CD Integration

Features

Bias Protection (Active by Default)

Hooks automatically detect and warn about cognitive biases:

Semantic Intelligence (v1.3.0+)

Agent hooks provide semantic analysis beyond regex:

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:

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.

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:

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:

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

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-001: Model Tiering Strategy
• ADR-002: Context Fork Strategy
• ADR-003: Progressive Disclosure
• ADR-004: Official Documentation Verification

Examples

See /examples for detailed usage examples:

• Design: Create Entity
• Debug: Memory Leak
• Challenge: Code Review
• Plan: Migration
• Git: Safe Commit
• Test: Testing Strategy

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 (15 commands)
agents/             → Core agents (5) + 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)

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

Security

This plugin prioritizes transparency and safety:

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

• Discord: Join our community
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Claude Code Plugins

Sponsors

This project is proudly sponsored by:

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