health

/pwdev-code:health — Project Health Diagnostics

Role

Utility agent that runs a comprehensive assessment of project health: code, tests, dependencies, security, documentation, and framework workspace (.planning/).

When called with --deps, runs a focused dependency audit instead of the full health check.

Input

$ARGUMENTS: Optional flags.

• --deps → run only the dependency audit (STEP 2.5 + STEP 2.6)
• empty → run full health check

Procedure

STEP 0 — Language

Follow ${CLAUDE_PLUGIN_ROOT}/references/language.md (resolve lang from .planning/config.json; ask only if unset).

STEP 0.1 — Framework Workspace Validation

Validates the PROJECT's pwdev-code workspace (the plugin itself is validated with claude plugin validate, not here).

echo "=== WORKSPACE VALIDATION ==="
ERRORS=0

# .planning/ workspace
[ -d ".planning" ] || { echo "❌ Missing: .planning/ (run /pwdev-code:init)"; ERRORS=$((ERRORS+1)); }
[ -f ".planning/state.md" ] && echo "✅ Found: .planning/state.md" || echo "⚠️ Missing: .planning/state.md"

# config.json required fields
if [ -f ".planning/config.json" ]; then
  echo "✅ Found: .planning/config.json"
  for field in lang model_profile audit version; do
    grep -q "\"$field\"" .planning/config.json || echo "⚠️ Missing field in config.json: $field"
  done
else
  echo "❌ Missing: .planning/config.json (run /pwdev-code:init)"
  ERRORS=$((ERRORS+1))
fi

# Project skills (optional)
if [ -d ".claude/skills" ]; then
  for skill_dir in .claude/skills/*/; do
    [ -d "$skill_dir" ] || continue
    skill_name=$(basename "$skill_dir")
    if [ -f "$skill_dir/SKILL.md" ]; then
      echo "✅ Skill: $skill_name"
    else
      echo "❌ Skill: $skill_name (missing SKILL.md)"
      ERRORS=$((ERRORS+1))
    fi
  done
fi

# CLAUDE.md must exist
[ -f "CLAUDE.md" ] && echo "✅ Found: CLAUDE.md" || echo "⚠️ Missing: CLAUDE.md"

# .mcp.json at root (optional)
[ -f ".mcp.json" ] && echo "✅ Found: .mcp.json" || echo "ℹ️ Optional: .mcp.json not found"

# Memory index consistency (if memory exists)
if [ -f ".planning/memory/MEMORY.md" ]; then
  grep -o '(memory/[^)]*)' .planning/memory/MEMORY.md | tr -d '()' | while read -r m; do
    [ -f ".planning/$m" ] || echo "⚠️ Memory index points to missing file: $m"
  done
  for f in .planning/memory/*.md; do
    [ "$(basename "$f")" = "MEMORY.md" ] && continue
    if grep -q "status: active" "$f" 2>/dev/null; then
      grep -q "$(basename "$f")" .planning/memory/MEMORY.md || echo "⚠️ Active memory not indexed: $(basename "$f")"
    fi
  done
fi

# Audit DB integrity (when enabled)
if grep -q '"audit"[[:space:]]*:[[:space:]]*true' .planning/config.json 2>/dev/null; then
  if [ -f ".planning/pwdev-audit.db" ] && command -v sqlite3 >/dev/null 2>&1; then
    sqlite3 .planning/pwdev-audit.db "PRAGMA integrity_check;" 2>/dev/null | head -1
  else
    echo "⚠️ Audit enabled but DB or sqlite3 missing"
  fi
fi

echo "=== STRUCTURE ERRORS: $ERRORS ==="