Skip to content
AI CraftsmanSUPERPOWERS

Getting Started

Install AI Craftsman Superpowers and run your first quality-enforced session in under 5 minutes.

Last updated: Edit on GitHub

Requirements

Before installing, make sure you have:

Dependency Minimum version Notes
Claude Code CLI 2.1.218+ claude --version. Older versions: install the frozen 3.9.x line
Python 3.9+ The floor is what /usr/bin/python3 is on a Mac without homebrew
Bash 3.2+ macOS default works. GNU coreutils is not required
grep, jq, sqlite3 any Usually pre-installed

Optional tools

PHPStan, ESLint, and Deptrac are optional - the plugin degrades gracefully if they’re not installed. Install them to unlock Level 2 (Static Analysis) validation.

Installation

Install the plugin via the Claude Code plugin manager:

# 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
exit
claude

This registers all 13 wired hook events automatically. Check the install in /plugin: the “Installed” tab should list the craftsman plugin, and the “Errors” tab is where to look if skills do not appear.

Configure Your Stack

Run the interactive setup wizard:

/craftsman:setup

The wizard will:

  1. Ask about your DISC profile (communication style calibration)
  2. Detect your stack (Symfony, React, AI/ML)
  3. Ask which packs to enable
  4. Generate ~/.claude/.craft-config.yml

The generated config looks like this:

version: "1.0"
profile:
  name: "Your Name"
  disc_type: "DI"
  biases:
    - acceleration
    - scope-creep
packs:
  core: true
  symfony: true
  react: false
  ai: false
stack:
  php_version: "8.4"
  symfony_version: "7.4"
rules:
  php:
    final_classes: true
    strict_types: true
    no_setters: true

Your First Session

Start a session and let Craftsman enforce quality from the first write:

claude
> /craftsman:healthcheck

There is no session-start command to run: the plugin loads your config, active packs and rules automatically on SessionStart. /craftsman:healthcheck is how you inspect what it loaded and confirm the gate is armed. For token spend, use Claude Code’s own /usage.

When you write or edit a file, the hooks automatically run:

✓ [Level 1] PHP001: final class - PASS
✓ [Level 2] PHPStan level 8 - PASS
✓ [Level 3] Architecture (deptrac) - PASS
Session metrics saved.

If a rule is violated, the hook blocks the write with a clear message:

✗ [Level 1] PHP001: Class must be final
  File: src/Domain/User.php
  Fix: Add `final` keyword before `class`

The 10 Superpowers

# Superpower What it does
1 Iron Law Pattern Loads canonical example before any code generation
2 Cognitive Bias Detector Catches acceleration, scope-creep, over-optimization in real-time
3 Correction Learning A fix that recurs 3 times across 3 files becomes a candidate instinct you approve, then a project skill with provenance
4 Progressive Quality Gate Regex (under 50ms, always on), LSP semantics (if your language server is installed), static analysis and architecture (opt-in per machine)
5 Rules Engine Global, then project, then directory inheritance
6 Structural Ratchet A committed baseline holds each file’s structural high-water mark. A file you touch may improve or stay equal, never regress. Untouched legacy is never punished
7 Multi-CI Zero Drift Same rules in hooks AND CI (GitHub, GitLab, Bitbucket, Jenkins)
8 Metrics & Trends SQLite dashboard: violations, corrections, 7-day trends
9 Agent Fleet 6 core agents + 6 pack agents, model-tiered for cost optimization
10 Atomic Commits Warns above 15 files staged: craftsmen commit small

What’s Next