@mclawnet/agent 0.5.9 → 0.6.2

package/skills/codebase-health/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: codebase-health
+description: Evaluate codebase quality across multiple dimensions including type safety, lint cleanliness, test coverage, dead code, and dependency hygiene. Use when performing health checks, quality audits, tracking code quality trends, or assessing technical debt.
+disable-model-invocation: true
+---
+
+# Codebase Health
+
+Comprehensive codebase quality assessment across eight dimensions, producing a composite health score with actionable improvement recommendations.
+
+## Overview
+
+Code quality is not one metric — it is a composite of type safety, lint cleanliness, test coverage, dead code, dependency health, documentation, complexity, and security posture. This skill runs available project tools, scores each dimension, and produces a clear dashboard so teams can track quality over time and prioritize improvements.
+
+**Core principle**: Wrap, don't replace. Run the project's own tools and score their output. Never substitute analysis for what the tool reports.
+
+## When to Use
+
+- Periodic health checks (weekly, before releases)
+- Evaluating technical debt before a refactoring effort
+- Assessing code quality on a new project or repo
+- Tracking quality trends over multiple sprints
+- Comparing quality across modules or packages in a monorepo
+- Pre-merge quality gates
+
+## When NOT to Use
+
+- **Fixing issues** — this skill diagnoses only; use implementation skills to fix
+- **Code review of a specific PR** — use the `code-review` skill
+- **Performance profiling** — use the `performance-analysis` skill
+
+## Health Dimensions
+
+### 1. Type Safety (Weight: 20%)
+
+Does the code leverage the type system to prevent bugs at compile time?
+
+**What to check:**
+- Type checker passes cleanly (e.g., `tsc --noEmit`, `mypy`, `go vet`)
+- Strict mode enabled where available (`strict: true` in tsconfig)
+- No `any` escape hatches in TypeScript, no `# type: ignore` in Python
+- Generic types used instead of casting
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | Clean (zero errors), strict mode on |
+| 7 | < 10 errors or non-strict mode |
+| 4 | < 50 errors |
+| 0 | >= 50 errors or no type checking |
+
+### 2. Lint Cleanliness (Weight: 15%)
+
+Is the code consistent and free of common mistakes?
+
+**What to check:**
+- Linter passes cleanly (ESLint, Biome, Ruff, clippy)
+- Formatter applied consistently (Prettier, Black, gofmt)
+- No lint rule suppressions without comments explaining why
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | Clean (zero warnings) |
+| 7 | < 5 warnings |
+| 4 | < 20 warnings |
+| 0 | >= 20 warnings |
+
+### 3. Test Coverage (Weight: 25%)
+
+Are the important code paths protected by tests?
+
+**What to check:**
+- Test runner passes (`npm test`, `pytest`, `cargo test`)
+- Line coverage percentage
+- Branch coverage percentage
+- All new code has corresponding tests
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | All pass, line coverage > 80% |
+| 7 | All pass, line coverage > 60% |
+| 4 | Some failures, or coverage < 60% |
+| 0 | Test suite broken or coverage < 30% |
+
+### 4. Dead Code (Weight: 10%)
+
+Is there unused code cluttering the codebase?
+
+**What to check:**
+- Unused exports, functions, types (knip, ts-prune)
+- Unreachable code branches
+- Commented-out code blocks
+- Unused dependencies in package.json / requirements.txt
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | Clean (no unused exports or dependencies) |
+| 7 | < 5 unused exports |
+| 4 | < 20 unused exports |
+| 0 | >= 20 unused or many unused dependencies |
+
+### 5. Dependency Health (Weight: 10%)
+
+Are dependencies up to date and free of known vulnerabilities?
+
+**What to check:**
+- `npm audit` / `pip-audit` / `cargo audit` for security advisories
+- Outdated dependencies (`npm outdated`)
+- Pinned versions vs floating ranges
+- License compatibility
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | No vulnerabilities, all deps current |
+| 7 | No critical vulns, < 5 outdated |
+| 4 | Critical vulns present but patchable |
+| 0 | Unpatched critical vulns or abandoned deps |
+
+### 6. Documentation (Weight: 5%)
+
+Is the project understandable to newcomers?
+
+**What to check:**
+- README exists and is current
+- API documentation or JSDoc/docstrings on public interfaces
+- Architecture decision records (ADRs) for key decisions
+- Setup instructions that actually work
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | Comprehensive docs, setup works first try |
+| 7 | README + basic docs, most things documented |
+| 4 | README only, some gaps |
+| 0 | No docs or docs are outdated/wrong |
+
+### 7. Complexity (Weight: 10%)
+
+Is the code maintainable or tangled?
+
+**What to check:**
+- Cyclomatic complexity per function (target: < 10)
+- File size (target: < 300 lines per file)
+- Function length (target: < 50 lines per function)
+- Nesting depth (target: < 4 levels)
+- Module coupling (how many dependencies each module has)
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | All functions < 10 complexity, clean structure |
+| 7 | Few functions > 10 complexity |
+| 4 | Many complex functions, deep nesting |
+| 0 | God classes, 1000+ line files, spaghetti |
+
+### 8. Security Posture (Weight: 5%)
+
+Is the code following security best practices?
+
+**What to check:**
+- No hardcoded secrets (use git-secrets, gitleaks, or trufflehog)
+- Input validation on user-facing endpoints
+- Authentication/authorization checks in place
+- HTTPS enforced, CORS configured properly
+- Dependencies scanned for CVEs
+
+**Scoring:**
+| Score | Criteria |
+|-------|----------|
+| 10 | No findings, security tools configured |
+| 7 | Minor findings, no credential leaks |
+| 4 | Significant findings, some credential exposure risk |
+| 0 | Hardcoded secrets or critical security gaps |
+
+## Health Check Process
+
+### Step 1: Detect Available Tools
+
+Auto-detect what's available in the project:
+
+```bash
+# Type checker
+[ -f tsconfig.json ] && echo "typecheck: tsc --noEmit"
+[ -f mypy.ini ] || [ -f pyproject.toml ] && echo "typecheck: mypy ."
+
+# Linter
+[ -f biome.json ] && echo "lint: biome check ."
+ls eslint.config.* .eslintrc.* 2>/dev/null && echo "lint: eslint ."
+[ -f pyproject.toml ] && grep -q "ruff" pyproject.toml && echo "lint: ruff check ."
+
+# Tests
+[ -f package.json ] && grep -q '"test"' package.json && echo "test: npm test"
+[ -f pyproject.toml ] && grep -q "pytest" pyproject.toml && echo "test: pytest"
+
+# Dead code
+command -v knip >/dev/null && echo "deadcode: knip"
+
+# Security
+command -v gitleaks >/dev/null && echo "security: gitleaks detect"
+[ -f package.json ] && echo "audit: npm audit"
+```
+
+### Step 2: Run Each Tool
+
+Run each detected tool, capturing:
+- Exit code (pass/fail)
+- Output summary (error/warning counts)
+- Duration
+
+### Step 3: Score and Present
+
+Calculate weighted composite score:
+
+```
+composite = Σ (dimension_score × weight)
+```
+
+If a dimension is not measurable (tool unavailable), redistribute its weight proportionally.
+
+### Step 4: Present Dashboard
+
+```
+CODEBASE HEALTH DASHBOARD
+===========================
+Project: my-project
+Branch:  main
+Date:    2026-04-01
+
+Dimension         Score    Status       Details
+---------------   -----    ---------    -------------------------
+Type Safety       10/10    CLEAN        0 errors, strict mode
+Lint              8/10     WARNING      3 warnings
+Test Coverage     9/10     GOOD         92% line coverage
+Dead Code         7/10     WARNING      4 unused exports
+Dependencies      10/10    CLEAN        No vulnerabilities
+Documentation     7/10     WARNING      Missing API docs
+Complexity        8/10     GOOD         2 functions > 10 complexity
+Security          10/10    CLEAN        No findings
+
+COMPOSITE SCORE: 8.7 / 10
+
+Status labels: CLEAN (10) | GOOD (8-9) | WARNING (6-7) | NEEDS WORK (4-5) | CRITICAL (0-3)
+```
+
+### Step 5: Recommendations
+
+Prioritize by `weight × (10 - score)`:
+
+```
+RECOMMENDATIONS (by impact)
+============================
+1. [HIGH]  Address 3 lint warnings (Lint: 8/10, weight 15%)
+2. [MED]   Remove 4 unused exports (Dead Code: 7/10, weight 10%)
+3. [MED]   Add API documentation (Docs: 7/10, weight 5%)
+4. [LOW]   Reduce complexity in 2 functions (Complexity: 8/10, weight 10%)
+```
+
+## Trend Tracking
+
+Run health checks regularly and track changes:
+
+```
+HEALTH TREND (last 5 runs)
+===========================
+Date          Score   Change   Highlight
+----------    -----   ------   -------------------------
+2026-03-15    7.2     —        Baseline
+2026-03-22    7.8     +0.6     Fixed type errors
+2026-03-29    8.3     +0.5     Added test coverage
+2026-04-01    8.7     +0.4     Removed dead code
+```
+
+**Interpreting trends:**
+- Steady improvement → team is addressing debt
+- Plateau → time to tackle the next dimension
+- Decline → new code is outpacing quality standards
+- Volatile → inconsistent practices, need better CI gates