Project Check

Project Check — Existing Project Health Scan

Dominant Variable

Discovered gaps are sorted by severity so the user knows "what to fix first" — an unsorted gap list causes information overload. A report without priority is useless.

Purpose

Scan an existing project against setup best practices across 4 dimensions: Infrastructure, Security, Quality, and Harness. Surface all gaps ordered by severity so the user knows exactly what to fix and in what order.

Dominant variable: Are 🔴 Security issues (hardcoded secrets, .env missing) displayed before all other gaps?

• Read-only skill: This skill does not modify project files. It generates a gap report only; fix recommendations are delegated to /project-init or /setup.

Discard if: Empty directory or a freshly initialized project (git init) — nothing to scan. Use /project-init directly instead.

Discard If

Empty directory or newly initialized project (git init with no code yet) — nothing to audit. Use /project-init. This skill audits code, infrastructure, security, and quality only. Need a persistent, weighted maturity score with cross-axis trend tracking instead of a one-time 4-dimension pass/fail scan — use /check-harness, not this skill.

Key Assumptions

1. Project root contains CLAUDE.md or .claude/ directory — if missing: recommend /project-init.
2. Git repository — if not a repo: skip some Infrastructure checks.

Trigger

• /project-check
• "project-check"
• "what's wrong"

Workflow

Step 0: Scale Detection

Count source files to calibrate warning thresholds:

Scan: *.py, *.ts, *.tsx, *.js, *.go, *.rs, *.java, *.kt, *.swift, *.c, *.cpp, *.h
Exclude dirs: node_modules/, .venv/, venv/, __pycache__/, vendor/, dist/, build/, .git/, .next/, target/

(Without this exclusion, dependency/build directories get swept into the file/LOC count and skew the Step 0 scale classification.)

Classify:

• script: < 10 source files or < 500 LOC → minimal structure expected, skip ROADMAP/ADR warnings
• mini: 10–50 files or 500–5,000 LOC → CLAUDE.md + tests expected
• full: > 50 files or > 5,000 LOC → full structure expected, ROADMAP + docs/decisions/ recommended

Detect project name from directory name or name field in package.json / pyproject.toml / Cargo.toml if present.

Step 1: Infrastructure Scan

For CLAUDE.md: count Hard Rules entries (lines starting with - under ## Hard Rules). Report the count.

Step 2: Security Scan

Grep these patterns across all source files (case-insensitive). Exclude: *.example, .env.example, files in tests/, __tests__/, spec/, and dependency/build directories (node_modules/, .venv/, venv/, __pycache__/, vendor/, dist/, build/, .git/, .next/, target/ — same list as Step 0):

API_KEY\s*=\s*["'][^$({]      → hardcoded API key
sk-[A-Za-z0-9]{20,}           → OpenAI key (sk-...)
sk-ant-[A-Za-z0-9\-]{20,}     → Anthropic key (sk-ant-api03-...)
ghp_[A-Za-z0-9]{36}           → GitHub PAT
password\s*=\s*["'][^$({]     → hardcoded password
secret\s*=\s*["'][^$({]       → hardcoded secret
token\s*=\s*["'][^$({]        → hardcoded token

Each match → 🔴 with file:line reference. Read the matched line before judging: a placeholder value (your_key_here, xxx, changeme, <...>) is ℹ info, not 🔴. Never print the found value — report file:line and the pattern name only.

Additional checks — .env protection (skip entirely if not a git repo, per Key Assumption 2):

A string match for .env inside .gitignore is not proof of protection — the pattern can be malformed (wrong path, typo, wrong glob syntax) and never actually match, or the file can already be tracked in git, in which case .gitignore has no effect on it at all. Verify both:

1. git check-ignore -v .env — confirms the pattern actually matches the file. No output / non-zero exit → the listed pattern doesn't cover .env → 🔴 ".env present in .gitignore text but the pattern doesn't actually match (git check-ignore reports it as not ignored)". If the command is denied or fails (e.g. the target is outside the worktree), report "⚠️ cannot verify — string presence only" instead of a red finding.
2. git ls-files --error-unmatch .env (exit 0 means tracked) — if .env is already tracked, → 🔴 ".env is already tracked in git — .gitignore cannot retroactively untrack it. Needs git rm --cached .env (manual step; this skill does not run it)".

• .env missing from .gitignore entirely (no string match) → 🔴 as before.
• .env.local, .env.*.local in .gitignore → ⚠ if missing (TypeScript/Next.js projects). Apply the same git check-ignore -v verification when a matching line is present.

Step 3: Quality Scan

Apply the same exclusion list as Step 0 (node_modules/, .venv/, __pycache__/, vendor/, dist/, build/, .git/, etc.) to every file count and grep below.

Test coverage proxy:

Count test files (test_*.py, *_test.py, *.test.ts, *.spec.ts, *_test.go, *Test.java, *Spec.kt) vs source files.

Debug remnants (grep non-test files):

console\.log|print\(f?["']|debugger;|pprint\(

→ ⚠ if > 5 matches

Open work markers (grep all files):

TODO|FIXME|HACK|XXX

→ ⚠ if > 10 total count

Step 4: Harness Scan

Profile detection (run first — determines whether orchestrator/agent-team absence is a gap at all):

Check whether the project shows any sign of agent-routing adoption:

• .claude/agents/*.md (project-level) — any files present?
• ~/.claude/agents/*.md (global) — any files present?
• CLAUDE.md or project rules mention agent routing (e.g., "orchestrator", "Tier 1/2/3", "subagent-dev", "brainstorming → writing-plans")?

If none of the above are present, infer Minimal profile — per the setup skill's own Q2 ("Minimal: rules + memory only. No agent routing" is a first-class, intentional choice, not a defect). Under Minimal profile, orchestrator/agent-team absence is a configuration choice, not a gap — do not score it as ⚠.

If any of the above are present, the project has adopted Standard/Orchestrated routing at least partially — a missing orchestrator or key agents at that point is a real gap (routing infrastructure exists without the piece that coordinates it), and stays ⚠.

Check Claude Code infrastructure:

Count total agent files across both locations. Report global vs project-level split. Report which key agents are installed (orchestrator, code-reviewer, verification, brainstorming, security-reviewer). If Minimal profile was inferred, report "0 agents — consistent with Minimal setup profile (rules + memory only)" instead of counting it toward gaps.

If CLAUDE.md has inline Hard Rules AND ~/.claude/rules/project rules exists → ⚠ "Hard Rules duplication: directly in CLAUDE.md AND project rules file present. Recommend consolidating to project rules with reference link in CLAUDE.md."

Step 5: Build Report

Sort all findings by severity within each section: 🔴 → ✗ → ⚠ → ✓

Score calculation:

Start: 10
-2 per 🔴
-1 per ✗
-0.5 per ⚠ (round to nearest 0.5)
Floor: 0

Output:

Project Health Check: [project-name]
Scale: [script / mini / full] ([N] source files)

Security:           ← always first, even if all pass
  🔴/✓/⚠ items

Infrastructure:
  ✓/✗/⚠ items

Quality:
  ✓/✗/⚠ items

Harness:
  ✓/✗/⚠ items

Score: [N]/10
Gaps: [N] total (🔴 [N], ✗ [N], ⚠ [N])

Step 6: Recommendations

Always end with next steps:

• 🔴 Security → "🔴 First: Remove secrets at [file:line] and move to .env (manual edit required)"
• Infrastructure ✗ → "→ Use /project-init — if CLAUDE.md exists, choose Update mode"
• Harness rules ✗/⚠ (rules, agents, hooks) → "→ Use /setup to configure Claude Code infrastructure"
• Harness agents ✗/⚠ (no agents, no orchestrator) AND agent-routing infra already exists elsewhere (Step 4 profile detection = not Minimal) → "→ Use /setup to install agent team (orchestrator + reviewer + implementer)"
• No agents anywhere AND no orchestrator, Minimal profile inferred (Step 4) → do not recommend an agent team as a fix; instead: "ℹ No agent-routing layer detected — consistent with a Minimal setup (rules + memory only). No action needed if intentional; run /setup Update mode if you want review agents or orchestration."
• Orchestrator Light only (orchestrator.md exists but lacks drift detection) → "→ Use /setup Update mode to enable Full orchestrator (with drift detection)"
• Quality only → "→ Recommend adding tests"
• Score ≥ 8 → "✓ Already well configured. Optionally address ⚠ items."

Recommended loop (new users):

/project-check → discover gaps
  → /project-init  (CLAUDE.md + ROADMAP + .gitignore)
  → /setup  (rules + hooks + memory)
  → /setup     (orchestrator + agent team)
  → /project-check (re-scan → verify score improvement)