name: project-health-check description: Run a comprehensive project health check covering dependencies, configuration, security, testing, and build integrity. Outputs a graded report card with actionable recommendations.

Project Health Check

Run a full diagnostic on the current project and produce a graded health report.

Steps

1. Detect Project Type

Identify the project ecosystem by checking for:

ls package.json pyproject.toml Cargo.toml go.mod pom.xml Gemfile

This skill focuses primarily on Node.js/TypeScript projects but adapts the checks as needed. Read package.json (or equivalent) to understand the project.

2. Run All Checks

Execute each check below. Record the result as PASS, WARN, or FAIL with details.

Check 1: Package Configuration

Read package.json and verify:

Run npm outdated 2>/dev/null || true and check for outdated dependencies:

• PASS: All up to date or only minor updates
• WARN: Major version updates available
• FAIL: Dependencies with known vulnerabilities

Run npm audit --json 2>/dev/null || true if available:

• PASS: No vulnerabilities
• WARN: Low/moderate vulnerabilities
• FAIL: High/critical vulnerabilities

Check 2: Environment Configuration

ls -la .env .env.example .env.local .env.development .env.production 2>/dev/null

If both .env and .env.example exist, compare their keys (not values):

grep -oP '^[A-Z_]+=?' .env | sort
grep -oP '^[A-Z_]+=?' .env.example | sort

Check for secrets accidentally committed:

git log --all --diff-filter=A -- '*.env' '.env.*' 2>/dev/null
grep -rn "sk-\|sk_live\|AKIA\|-----BEGIN.*KEY" src/ lib/ app/ --include="*.ts" --include="*.js" --include="*.json" 2>/dev/null

Check 3: Essential Files

Check for the presence and quality of standard project files:

Check 4: Code Quality & Linting

If a linter is configured, run it:

npx eslint . --max-warnings=0 2>/dev/null || npm run lint 2>/dev/null

• PASS: No errors or warnings
• WARN: Warnings only
• FAIL: Errors present

Check TypeScript compilation (if applicable):

npx tsc --noEmit 2>/dev/null

• PASS: No type errors
• WARN: -
• FAIL: Type errors found

Check 5: Testing

Detect the test framework and check coverage:

ls jest.config* vitest.config* .mocharc* karma.conf* 2>/dev/null
find . -name "*.test.*" -o -name "*.spec.*" | head -20

Run tests if configured (with a timeout):

timeout 120 npm test 2>&1 || true

If coverage is available:

npx vitest run --coverage 2>/dev/null || npx jest --coverage 2>/dev/null || true

Check 6: Build Verification

If a build script exists, try it:

timeout 120 npm run build 2>&1 || true

• PASS: Build succeeds with no warnings
• WARN: Build succeeds with warnings
• FAIL: Build fails

Check that build output exists and is gitignored:

ls dist/ build/ out/ .next/ 2>/dev/null
grep -q "dist\|build\|out\|\.next" .gitignore 2>/dev/null

Check 7: Security Baseline

Check 8: Documentation Quality

3. Generate the Health Report

Output the report in this format:

# Project Health Report

**Project**: <name from package.json>
**Version**: <version>
**Date**: <current date>
**Runtime**: Node.js <detected version>

## Report Card

| # | Check                    | Status | Details |
|---|--------------------------|--------|---------|
| 1 | Package Configuration    | PASS   | All fields present, deps up to date |
| 2 | Environment Config       | WARN   | .env.example missing 2 keys |
| 3 | Essential Files          | PASS   | All standard files present |
| 4 | Code Quality & Linting   | FAIL   | 3 ESLint errors found |
| 5 | Testing                  | WARN   | 62% coverage (target: 80%) |
| 6 | Build                    | PASS   | Builds successfully |
| 7 | Security                 | PASS   | No vulnerabilities found |
| 8 | Documentation            | WARN   | Missing API documentation |

## Overall Grade: B+

Grading scale:
- A+: All PASS
- A:  All PASS, 1 WARN
- B+: All PASS/WARN, no FAIL, <=3 WARN
- B:  All PASS/WARN, no FAIL
- C:  1 FAIL
- D:  2 FAIL
- F:  3+ FAIL

## Critical Issues (Fix Now)

1. **[FAIL] Code Quality**: 3 ESLint errors in src/utils/parser.ts
   - Fix: Run `npx eslint src/utils/parser.ts --fix`

## Recommendations (Improve Later)

1. **[WARN] Environment**: Add missing keys to .env.example: `REDIS_URL`, `LOG_LEVEL`
2. **[WARN] Testing**: Increase coverage from 62% to 80%. Untested files:
   - src/services/payment.service.ts (0%)
   - src/utils/crypto.ts (0%)
3. **[WARN] Documentation**: Add API docs using JSDoc or OpenAPI spec

## What's Good

- Clean dependency audit
- TypeScript strict mode enabled
- CI pipeline configured
- Build output properly gitignored

4. Offer Quick Fixes

After the report, offer to automatically fix what can be fixed:

I can automatically fix the following issues:

1. Create .env.example from current .env (keys only)
2. Run npx eslint --fix to auto-fix lint errors
3. Add missing entries to .gitignore
4. Add missing package.json fields

Want me to fix any of these? (all / pick numbers / skip)

Apply requested fixes, then re-run the affected checks to confirm they now pass.

Edge Cases

• Monorepo: If workspaces is detected in package.json or lerna.json / pnpm-workspace.yaml exists, run checks on each workspace package and aggregate results.
• No package.json: Report as FAIL for check 1 and adapt remaining checks. Ask the user what type of project this is.
• CI environment: Skip interactive prompts and output the report as plain text.
• Very large projects: Set timeouts on test and build commands. If they exceed 2 minutes, report as "SKIPPED (timeout)" rather than failing.