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

Pick your host. Each block is complete: after it, the gate refuses bad writes.

Claude Code

Requires Claude Code v2.1.218 or later (claude --version).

/plugin marketplace add BULDEE/ai-craftsman-superpowers
/plugin install craftsman@ai-craftsman-superpowers
# restart Claude Code, then:
/craftsman:setup --quick

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.

Codex

codex plugin marketplace add BULDEE/ai-craftsman-superpowers
codex plugin add craftsman@ai-craftsman-superpowers
codex    # then /hooks: review and trust the craftsman handlers

Installing does not trust the hooks: until you review them in /hooks, they load and do not run. See the Codex quickstart for details and limits.

Grok

git clone https://github.com/BULDEE/ai-craftsman-superpowers ~/src/ai-craftsman-superpowers
bash ~/src/ai-craftsman-superpowers/bin/craftsman-grok-install

Grok runs none of a plugin’s bundled hooks on a fresh process, so the installer also writes the global gate ~/.grok/hooks/craftsman.json. Run it again to upgrade. See the Grok quickstart for details and limits.

Hermes

git clone https://github.com/BULDEE/ai-craftsman-superpowers ~/.hermes/plugins/craftsman
hermes plugins enable craftsman

The gate applies at the conclusion: the agent cannot conclude a coding turn that leaves critical violations. See the Hermes quickstart for details.

Verify the Install

/craftsman:healthcheck

On Grok, run from a shell instead:

bash <plugin-root>/bin/craftsman-healthcheck --report

Every row that is not ok names the command that fixes it.

Configure Your Stack

On Claude Code, run the interactive setup wizard:

/craftsman:setup --quick

The wizard will detect your stack and generate ~/.claude/.craft-config.yml. It reads your repository (no network calls) and picks defaults. On Codex, Grok, or Hermes, see the respective quickstart guides.

Your First Session

No session-start command needed: the plugin loads your config, packs and rules automatically. Just start coding and watch the gate work.

When you write or edit a file, the hooks judge it before it reaches disk. If a rule that blocks is violated, the write is refused:

🚫 BLOCKED by AI Craftsman - 2 violation(s) detected before write:
  ✗ LAYER001: Domain imports Infrastructure - DDD layer violation
  ✗ PHP001: Missing declare(strict_types=1)
Fix these before writing.
Or silence one case of LAYER001, PHP001: // craftsman-ignore: <RULE_ID> (wrong: why the rule is wrong here) or (debt: why the code stays)

The marker is offered only to the rules that honour one. SEC001 to SEC003 never do: the refusal says “No marker silences …: fix the code.” instead.

On any host, inspect what loaded:

/craftsman:healthcheck  # Claude Code, Codex, Grok
bash <plugin-root>/bin/craftsman-healthcheck --report  # Any host, from shell

Core Mechanisms

Six mechanisms run behind every write, on every host:

  1. Rules Engine with 3-Level Inheritance: Global, project, and directory-level config. Files never break rules the directory permits.
  2. Real-Time Quality Gate: Regex before the write lands (always on), then LSP semantics where a language server is installed, then static analysis and architecture (opt-in per machine). The regex cost is measured on every release by the plugin’s latency benchmark.
  3. Correction Learning: A fix that recurs 3 times across 3 files surfaces as a candidate instinct you approve, then becomes a project skill.
  4. Cognitive Bias Detector: Real-time detection of acceleration bias, scope creep, over-optimization in your prompts (on Claude Code).
  5. Structural Ratchet: A committed baseline holds each file’s structural high-water mark (worst-function complexity, longest function, suppression count). A file you touch may improve or stay equal, never regress. Untouched legacy is never punished.
  6. Multi-CI Zero Drift: Same rules in hooks and CI. GitHub, GitLab, Bitbucket, Jenkins all get native annotations. No divergence.

What’s Next