Skip to content

Troubleshooting

Common issues and how to fix them.

Installation issues

"Plugin not found" or commands don't work

The plugin symlink may be missing or broken:

# Check the symlink
ls -la ~/.claude/plugins/company-claude-toolkit

# Re-run setup
cd ~/.claude/plugins/company-claude-toolkit
./scripts/setup.sh --full

"CLAUDE.md not configured"

The global rules file is missing:

cp ~/.claude/plugins/company-claude-toolkit/configs/user-global/CLAUDE.md ~/.claude/CLAUDE.md

Skills or commands not available

Symlinks may be missing:

# Check what's installed
ls ~/.claude/skills/

# Re-install symlinks
./scripts/setup.sh --full

Hook scripts not running

Scripts may not be executable:

chmod +x ~/.claude/plugins/company-claude-toolkit/plugins/core-standards/scripts/*.sh

Workflow issues

Orchestrator takes too long

Orchestrators coordinate multiple agents in parallel. If it's slow:

  • Reduce scope: /review --scope src/api/ instead of the entire codebase
  • Use specific agents directly instead of the orchestrator for focused tasks

Too many review findings

If overwhelmed by results from /review:

  • Focus on Critical and High severity first
  • Fix those, then re-run the review
  • Lower-severity items are optional improvements

Secret scanner blocks a legitimate write

If the secret scanner gives a false positive:

  • Check for patterns that look like credentials but aren't
  • Use environment variables instead of string literals
  • If truly a false positive, the scanner warns but shouldn't block advisory-only patterns

Configuration issues

Setup differs from golden copy

# See what's different
./scripts/setup.sh --diff

# Re-apply from golden copy
./scripts/setup.sh --full

Backup before making changes

./scripts/setup.sh --backup

This snapshots your current ~/.claude/ configuration.

Getting help

  • Run /0-start to see the workflow overview
  • Check the Reference for component details
  • Review ./scripts/setup.sh --verify output for specific failures