Doctor Skill

Note: All ~/.claude/... paths in this guide respect CLAUDE_CONFIG_DIR when that environment variable is set.

Task: Run Installation Diagnostics

You are the PEP Doctor - diagnose and fix installation issues.

Step 1: Check Plugin Version

# Get installed version
INSTALLED=$(ls ~/.claude/plugins/cache/pep/pepcode/ 2>/dev/null | sort -V | tail -1)
echo "Installed: $INSTALLED"

# Get latest from npm
LATEST=$(npm view pepcode version 2>/dev/null)
echo "Latest: $LATEST"

Diagnosis:

• If no version installed: CRITICAL - plugin not installed
• If INSTALLED != LATEST: WARN - outdated plugin
• If multiple versions exist: WARN - stale cache

Step 2: Check for Legacy Hooks in settings.json

Read ~/.claude/settings.json and check if there's a "hooks" key with entries like:

• bash $HOME/.claude/hooks/keyword-detector.sh
• bash $HOME/.claude/hooks/persistent-mode.sh
• bash $HOME/.claude/hooks/session-start.sh

Diagnosis:

• If found: CRITICAL - legacy hooks causing duplicates

Step 3: Check for Legacy Bash Hook Scripts

ls -la ~/.claude/hooks/*.sh 2>/dev/null

Diagnosis:

• If keyword-detector.sh, persistent-mode.sh, session-start.sh, or stop-continuation.sh exist: WARN - legacy scripts (can cause confusion)

Step 4: Check CLAUDE.md

# Check if CLAUDE.md exists
ls -la ~/.claude/CLAUDE.md 2>/dev/null

# Check for PEP marker
grep -q "pepcode Multi-Agent System" ~/.claude/CLAUDE.md 2>/dev/null && echo "Has PEP config" || echo "Missing PEP config"

Diagnosis:

• If missing: CRITICAL - CLAUDE.md not configured
• If missing PEP marker: WARN - outdated CLAUDE.md

Step 5: Check for Stale Plugin Cache

# Count versions in cache
ls ~/.claude/plugins/cache/pep/pepcode/ 2>/dev/null | wc -l

Diagnosis:

• If > 1 version: WARN - multiple cached versions (cleanup recommended)

Step 6: Check for Legacy Curl-Installed Content

Check for legacy agents, commands, and skills installed via curl (before plugin system):

# Check for legacy agents directory
ls -la ~/.claude/agents/ 2>/dev/null

# Check for legacy commands directory
ls -la ~/.claude/commands/ 2>/dev/null

# Check for legacy skills directory
ls -la ~/.claude/skills/ 2>/dev/null

Diagnosis:

• If ~/.claude/agents/ exists with pepcode-related files: WARN - legacy agents (now provided by plugin)
• If ~/.claude/commands/ exists with pepcode-related files: WARN - legacy commands (now provided by plugin)
• If ~/.claude/skills/ exists with pepcode-related files: WARN - legacy skills (now provided by plugin)

Look for files like:

• architect.md, researcher.md, explore.md, executor.md, etc. in agents/
• ultrawork.md, deepsearch.md, etc. in commands/
• Any pepcode-related .md files in skills/

---

Report Format

After running all checks, output a report:

## PEP Doctor Report

### Summary
[HEALTHY / ISSUES FOUND]

### Checks

| Check | Status | Details |
|-------|--------|---------|
| Plugin Version | OK/WARN/CRITICAL | ... |
| Legacy Hooks (settings.json) | OK/CRITICAL | ... |
| Legacy Scripts (~/.claude/hooks/) | OK/WARN | ... |
| CLAUDE.md | OK/WARN/CRITICAL | ... |
| Plugin Cache | OK/WARN | ... |
| Legacy Agents (~/.claude/agents/) | OK/WARN | ... |
| Legacy Commands (~/.claude/commands/) | OK/WARN | ... |
| Legacy Skills (~/.claude/skills/) | OK/WARN | ... |

### Issues Found
1. [Issue description]
2. [Issue description]

### Recommended Fixes
[List fixes based on issues]

---

Auto-Fix (if user confirms)

If issues found, ask user: "Would you like me to fix these issues automatically?"

If yes, apply fixes:

Fix: Legacy Hooks in settings.json

Remove the "hooks" section from ~/.claude/settings.json (keep other settings intact)

Fix: Legacy Bash Scripts

rm -f ~/.claude/hooks/keyword-detector.sh
rm -f ~/.claude/hooks/persistent-mode.sh
rm -f ~/.claude/hooks/session-start.sh
rm -f ~/.claude/hooks/stop-continuation.sh

Fix: Outdated Plugin

rm -rf ~/.claude/plugins/cache/pepcode
echo "Plugin cache cleared. Restart Claude Code to fetch latest version."

Fix: Stale Cache (multiple versions)

# Keep only latest version
cd ~/.claude/plugins/cache/pep/pepcode/
ls | sort -V | head -n -1 | xargs rm -rf

Fix: Missing/Outdated CLAUDE.md

Copy from local plugin installation:

# Find pepcode plugin docs/CLAUDE.md
PEP_SOURCE=""
if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/docs/CLAUDE.md" ]; then
  PEP_SOURCE="$CLAUDE_PLUGIN_ROOT/docs/CLAUDE.md"
else
  CACHE_DIR="$HOME/.claude/plugins/cache/pep/pepcode"
  if [ -d "$CACHE_DIR" ]; then
    LATEST=$(ls -1 "$CACHE_DIR" | sort -V | tail -1)
    [ -n "$LATEST" ] && [ -f "$CACHE_DIR/$LATEST/docs/CLAUDE.md" ] && PEP_SOURCE="$CACHE_DIR/$LATEST/docs/CLAUDE.md"
  fi
fi

if [ -n "$PEP_SOURCE" ]; then
  cp "$PEP_SOURCE" "$HOME/.claude/CLAUDE.md"
  echo "CLAUDE.md restored from local plugin"
else
  echo "ERROR: Could not find local docs/CLAUDE.md. Run: claude /install-plugin pepcode"
fi

Fix: Legacy Curl-Installed Content

Remove legacy agents, commands, and skills directories (now provided by plugin):

# Backup first (optional - ask user)
# mv ~/.claude/agents ~/.claude/agents.bak
# mv ~/.claude/commands ~/.claude/commands.bak
# mv ~/.claude/skills ~/.claude/skills.bak

# Or remove directly
rm -rf ~/.claude/agents
rm -rf ~/.claude/commands
rm -rf ~/.claude/skills

Note: Only remove if these contain pepcode-related files. If user has custom agents/commands/skills, warn them and ask before removing.

---

Post-Fix

After applying fixes, inform user:

Fixes applied. Restart Claude Code for changes to take effect.