Configuration

Overview

AI Craftsman Superpowers uses a 3-level configuration hierarchy:

1. Global - ~/.claude/.craft-config.yml - this machine, every project
2. Project - .craft-config.yml in the project root - overrides global, checked into git
3. Directory - .craft-rules.yml in any subdirectory - rule overrides only

Lower levels override higher levels. A few keys are the machine owner’s alone and are read from the global file only (see Machine-only keys): a repository you clone can tune what the gate checks, never whether it runs.

The format is described by the plugin’s schemas/craft-config.schema.json and read by hooks/lib/config.sh. No file at all is a valid configuration: the plugin then runs with stack: fullstack and a strictness it derives from the repository.

Project Config (.craft-config.yml)

/craftsman:setup writes this file. It describes the repository, not the machine:

# .craft-config.yml, format v4
v: 4
stack: symfony        # symfony | react | fullstack | other
strictness: strict    # strict | moderate | relaxed
guided: false         # true: every refusal also explains its doctrine

Key	Values	Meaning
v	4	Format marker. A file without it predates v4, and /craftsman:setup offers to migrate it
stack	symfony, react, fullstack, other	One word on the line. It labels the setup and selects doctrine and hints; it switches no shipped pack’s rule on or off
strictness	strict, moderate, relaxed	Omitted, the plugin derives it: strict for a repository under 20 commits or with a committed baseline, moderate otherwise. See Rules Engine
guided	true, false	Gate exigency is unchanged; each block also explains its doctrine in plain language
rules	rule ID to block, warn or ignore, or a custom rule	Severity overrides, see below
context_budget	session_start_max_chars, max_learned_skills	Caps on what session start injects
sentry_org, sentry_project	strings	Optional Sentry context

Check what the plugin actually reads, with the validator the healthcheck uses:

bash -c 'source "$(craftsman-path hooks/lib/config.sh)"; config_validate .craft-config.yml && echo "stack=$(config_stack) strictness=$(config_strictness)"'

Rule Overrides

Short form, by rule ID:

rules:
  PHP002: warn     # final classes reported, not refused
  TS001: ignore    # no-any check disabled

Long form, a custom regex rule:

rules:
  CUSTOM001:
    pattern: "dd\\("
    message: "No dd() in production code"
    severity: block
    languages: [php]

The values are block, warn and ignore, nothing else. The rule IDs are listed in the Rules Engine reference.

Directory Rules (.craft-rules.yml)

Place a .craft-rules.yml in any directory for a part of the tree that needs different rules:

# src/Legacy/.craft-rules.yml
rules:
  PHP001: warn     # warn instead of block
  PHP002: ignore   # legacy classes are not final

Global Config (~/.claude/.craft-config.yml)

/craftsman:setup merges your personal profile here, once per machine, and keeps every other key:

# ~/.claude/.craft-config.yml
v: 4
profile:
  name: "Your Name"
  disc_type: "DI"      # D, I, S, C, DI, DC, IS, SC
  biases:
    - acceleration
    - scope_creep
    - over_optimization
    - dispersion

Machine-only keys

These keys are read from the global file only. A project file that sets them is ignored, because each one decides whether code from the repository runs or whether the gates run at all:

Key	Meaning
trust_project_tools: true	Let Level 2 static analysis run the project’s own tools (vendor/bin, node_modules/.bin) and the configs they auto-discover. Running them is running the repository’s code
packs: with external:	Load packs from outside the plugin; a pack is sourced as code
hooks: with disabled:	Turn individual hooks off, as an inline list
hooks: with agent_hooks: false	Turn the agent hooks off, for a host without plugin options

# ~/.claude/.craft-config.yml
trust_project_tools: true
packs:
  external:
    - path: "~/my-custom-pack"
hooks:
  disabled: [git-bypass-guard]
  agent_hooks: false

hooks: disabled: takes hook IDs. From 4.14.0, git-bypass-guard refuses a git command the agent runs with --no-verify, git commit -n, core.hooksPath, HUSKY=0, SKIP= or LEFTHOOK=0, or a git stash in the same command as a commit. Disabling it is the machine owner’s call, here; running the command yourself is the other way.

Packs

Seven packs ship with the plugin: symfony, react, python, go, rust, bash, ai-ml. There is nothing to switch on: every shipped pack loads on every project and judges the file types it owns. The packs key only matters for an external pack, in the global file, as above.

Agent Hooks

The agent hooks are a headless review, Haiku on Claude Code: a DDD verifier after each Write or Edit, and a final architecture review at Stop. They are on by default, at roughly $0.15-0.30 per session of 50 writes.

To turn them off:

• On Claude Code, set the plugin option agent_hooks to false (it reaches the hooks as CLAUDE_PLUGIN_OPTION_AGENT_HOOKS).
• On any host, write hooks: then agent_hooks: false in your global ~/.claude/.craft-config.yml.

A top-level agent_hooks: line in a .craft-config.yml is not read. With the agent hooks off, every other level (regex, LSP, static analysis, architecture, the ratchet) keeps running.