Configuration

Overview

AI Craftsman Superpowers uses a 3-level configuration hierarchy:

1. Global - ~/.claude/.craft-config.yml - applies to all projects
2. Project - .craft-config.yml in project root - overrides global, checked into git
3. Directory - .craft-rules.yml in any subdirectory - fine-grained rule overrides

Lower levels override higher levels. A project config can disable rules that the global config enables.

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

Generated by /craftsman:setup. Contains your profile, active packs, and default rules.

version: "1.0"

profile:
  name: "Your Name"
  disc_type: "DI"          # D, I, S, C, DI, DC, IS, SC combinations
  biases:
    - acceleration          # Moving fast, skipping validation
    - scope-creep           # Adding features mid-task
    - over-optimization     # Premature optimization
    - dispersion            # Context-switching

packs:
  core: true               # Always true - core rules and agents
  symfony: true            # PHP/Symfony pack
  react: false             # React/TypeScript pack
  ai: false                # AI/ML pack

stack:
  php_version: "8.4"
  symfony_version: "7.4"
  node_version: "22"
  react_version: "19"

rules:
  php:
    final_classes: true
    private_constructors: true
    no_setters: true
    strict_types: true
    no_datetime_direct: true
    no_empty_catch: true
  typescript:
    no_any: true
    readonly_default: true
    branded_types: true
    named_exports: true
    no_non_null_assertion: true
  git:
    conventional_commits: true
    no_ai_attribution: true

paths:
  domain: "src/Domain"
  application: "src/Application"
  infrastructure: "src/Infrastructure"
  presentation: "src/Presentation"

agent_hooks:
  enabled: true            # Enable semantic agents on file writes
  cost_aware: true         # Use Haiku for cost optimization

ci:
  provider: "github"       # github | gitlab | bitbucket | jenkins
  export_path: ".github/workflows/craftsman-quality-gate.yml"

Project Config (.craft-config.yml)

Override rules for a specific project. Checked into git so the whole team gets the same rules.

version: "1.0"

# Extend global config
extends: "~/.claude/.craft-config.yml"

rules:
  php:
    final_classes: true     # Override: enforce even if global disables
    no_empty_catch: false   # Override: relax this rule for this project

paths:
  domain: "packages/shared/src/Domain"   # Monorepo path override

Directory Rules (.craft-rules.yml)

Place a .craft-rules.yml in any directory for fine-grained control:

# src/Legacy/.craft-rules.yml
rules:
  php:
    final_classes: ignore   # Relax in legacy code
    strict_types: warn      # Warn instead of block

Rule Severity Values

Each rule can be set to one of three severity levels:

Value	Behavior
true or "block"	Blocks the write. Claude must fix before continuing.
"warn"	Shows a warning but allows the write. Logged to metrics.
"ignore" or false	Rule is disabled entirely.

PHP Rules Reference

Rule	Default	Description
final_classes	true	All classes must be final
private_constructors	true	Use private __construct() + static factory
no_setters	true	No setters - use behavioral methods
strict_types	true	declare(strict_types=1) in every file
no_datetime_direct	true	Inject Clock abstraction instead of new DateTime()
no_empty_catch	true	No empty catch blocks

TypeScript Rules Reference

Rule	Default	Description
no_any	true	No any - use proper types or unknown
readonly_default	true	readonly by default on all properties
branded_types	true	Branded types for domain primitives
named_exports	true	Named exports only - no default exports
no_non_null_assertion	true	No ! operator - handle null explicitly

Git Rules Reference

Rule	Default	Description
conventional_commits	true	Conventional Commits format: type(scope): description
no_ai_attribution	true	No Co-Authored-By or AI attribution in commits

Packs Configuration

Each pack adds agents, commands, and rules:

Five packs ship with the plugin: symfony, react, ai-ml, python, bash. The packs key accepts either a comma-separated string or a mapping.

Comma-separated form:

packs: "symfony,react,ai-ml,python,bash"

Mapping form, as shipped in config/default-config.yml:

packs:
  core: true      # Always enabled: 6 core agents, 19 skills
  symfony: false  # backend-craftsman, api-craftsman, symfony-reviewer, PHP rules
  react: false    # frontend-craftsman, react-reviewer, TS/React rules

External community packs:

packs:
  core: true
  external:
    - path: "~/my-custom-pack"
    - path: "/usr/local/share/craftsman-go-pack"

Agent Hooks

Control when semantic agents run:

agent_hooks:
  enabled: true          # Master switch
  cost_aware: true       # Use Haiku for all agent hooks
  triggers:
    pre_write: true      # Run DDD Verifier before writes
    post_write: true     # Run Architecture Analyzer after writes
    session_end: true    # Run Final Reviewer on session stop