Troubleshooting

Start With the Healthcheck

Before investigating any issue, ask the install what it sees:

/craftsman:healthcheck                                   # Claude Code, Codex (on Grok: /healthcheck)
bash <plugin-root>/bin/craftsman-healthcheck --report    # any host, from a shell

Every row that is not ok names the command that fixes it, a configuration the plugin cannot read included.

---

Common Issues

Plugin not loading

Symptom: Hooks don’t run, no validation output.

Check:

/plugin
# "Installed" tab: the craftsman plugin should appear
# "Errors" tab: check here if skills do not appear

Fix:

claude plugin update craftsman@ai-craftsman-superpowers   # Force update

# If still not working, clear the cache and reinstall
rm -rf ~/.claude/plugins/cache/ai-craftsman-superpowers
claude plugin install craftsman@ai-craftsman-superpowers

# Restart Claude Code
exit
claude

---

No config file

Symptom: the session line or the healthcheck shows stack=fullstack and a strictness you did not choose.

Cause: there is no .craft-config.yml. That is a valid state: the plugin runs with stack: fullstack and derives the strictness from the repository (strict under 20 commits or with a baseline, moderate otherwise).

Fix: Run the setup wizard, which writes the project file:

/craftsman:setup --quick

Or create a minimal one by hand:

# .craft-config.yml
v: 4
stack: symfony

---

Rules not applying to my files

Symptom: PHP/TypeScript rules aren’t triggering.

Checks:

1. There is no pack to enable: every shipped pack judges its own file types on every project, whatever stack says.
2. Check for a .craft-rules.yml in the directory that disables the rule, and for a rules: override in .craft-config.yml:

   find . -name ".craft-rules.yml" -exec cat {} \;

3. Check the strictness: under moderate only LAYER* and SEC* block, every other rule warns.
4. Verify the file extension is one a pack declares:
   • PHP: .php
   • TypeScript: .ts, .tsx; JavaScript: .js, .jsx, .mjs, .cjs
   • Python: .py; Go: .go; Rust: .rs; Bash: .sh, .bash

---

Level 2 validation skipped (PHPStan/ESLint not running)

Symptom: Only Level 1 (regex) runs, no static analysis.

Check: Are the tools installed?

which phpstan  # Should return a path
which eslint   # Should return a path

Fix: Install the tools:

# PHPStan
composer global require phpstan/phpstan

# ESLint
npm install -g eslint

---

Hooks blocking valid code

Symptom: Your code is correct but a hook blocks it.

Options:

1. Marker (in the file, with the reason):

   // craftsman-ignore: PHP002 (debt: a third-party library extends this adapter)
   class LegacyAdapter implements ThirdPartyInterface {}

   SEC001, SEC002 and SEC003 honour no marker.

2. Directory override (whole directory):

   # src/Legacy/.craft-rules.yml
   rules:
     PHP002: ignore

3. Project override (whole project):

   # .craft-config.yml
   rules:
     PHP002: warn

---

Agent hooks making sessions expensive

Symptom: Unexpected API costs from agent hooks.

Check: Use Claude Code’s own command to see your actual spend:

/usage

Fix: Disable agent hooks entirely (validation-only mode). On Claude Code, set the plugin option agent_hooks to false; on any host, in your global ~/.claude/.craft-config.yml:

hooks:
  agent_hooks: false

A top-level agent_hooks: line is not read. All validation (Level 1 regex, Level 2 static analysis, Level 3 architecture) keeps running. Only the model-based review hooks stop.

---

SQLite metrics database locked

Symptom: Error: database is locked in hook output.

Cause: Multiple concurrent processes accessing the same database session.

Fix: Each host and session maintains separate database stores, so try restarting your session:

exit
claude  # or codex, grok, etc.

If the lock persists, find and close the process holding the lock:

METRICS_DB=$(bash "$(craftsman-path bin/craftsman-runtime)" metrics)
fuser -k "$METRICS_DB" 2>/dev/null || true

---

External pack not loading

Symptom: a pack you wrote outside the plugin never reports anything.

Checks:

1. It is declared in your global ~/.claude/.craft-config.yml. A project file cannot declare an external pack: the pack is sourced as code.

   packs:
     external:
       - path: "~/my-pack"  # absolute or ~ path

2. Its pack.yml has a languages: block naming its extensions. Without one the pack loads and no file is ever dispatched to it.
3. It passes the plugin’s pack validator:

   ls ~/my-pack/pack.yml
   bash <plugin-root>/scripts/validate-pack.sh ~/my-pack/

Restart the session after a change: packs are loaded at SessionStart.

---

FAQ

Q: Can I use the plugin without internet access?

Yes. All validation (Levels 1-3) runs locally. Agent hooks require model API access; turn them off with the plugin option agent_hooks: false, or hooks: then agent_hooks: false in your global config.

---

Q: Does the plugin work with monorepos?

Yes. Place .craft-config.yml at the monorepo root to apply rules globally. Use directory-level .craft-rules.yml files in each package for package-specific overrides.

---

Q: Can multiple team members use different configs?

Yes. The ~/.claude/.craft-config.yml is personal (not committed). The project .craft-config.yml is shared (committed). Team members can have different profiles in their global config while sharing the same project rules.

---

Q: How do I add Craftsman to an existing project without breaking CI?

Take a baseline first, then choose the strictness:

bash <plugin-root>/bin/craftsman-ci baseline   # what the repository already carries

# .craft-config.yml
v: 4
strictness: moderate   # LAYER* and SEC* block, everything else warns

Inherited findings recorded in the baseline report without blocking, and new debt is still refused. /craftsman:setup runs the baseline step for you. Move to strictness: strict once the baseline is committed.

---

Q: The correction rate in metrics is very low - is something wrong?

A low correction rate (below 40%) usually means:

1. Rules are triggering on code you intentionally write that way (consider "warn" severity)
2. Claude is fixing violations in a different session (corrections are session-scoped)
3. The SQLite file is being reset between sessions

---

Q: Can I export metrics to a team dashboard?

# Export to JSON
sqlite3 -json "$(bash "$(craftsman-path bin/craftsman-runtime)" metrics)" \
  "SELECT * FROM violations ORDER BY timestamp DESC LIMIT 100" \
  > metrics-export.json

Then push to your preferred analytics tool.

---

Q: How do I update the plugin?

claude plugin update craftsman@ai-craftsman-superpowers

Then restart Claude Code (exit, then claude): the new version’s configuration is loaded on SessionStart.