health

/health — Project Health Audit

Orchestrates a cross-cutting audit across all project dimensions. Designed to run periodically via the native /loop bundled skill.

Architecture — hybrid orchestrator:

• Native checks (no dedicated sub-skill exists for these): endpoints, versions, docs
• Pure delegation (sub-skill owns the logic): security → /security-verify scan, quality → /quality-check, library → /library, releases → /release verify tags, ci → /ci-setup audit, website → /website-health

Quick Start

/health                    # auto-detect project, show summary
/health full               # comprehensive audit across all dimensions
/health endpoints          # check routes vs docs
/health versions           # version string consistency
/health docs               # CLAUDE.md + README staleness + license check
/health roadmap            # bidirectional sync: ROADMAP.md ↔ GitHub Issues ↔ CHANGELOG
/health license            # check LICENSE file; advisor mode if missing
/health security           # delegate to /security-verify scan
/health quality            # delegate to /quality-check + tests + coverage
/health techdebt           # delegate to /techdebt (duplicates, dead code, TODOs, oversized functions)
/health deps               # delegate to /deps scan (outdated deps, CVEs, decision coverage)
/health hygiene            # filesystem lint: gitignore gaps, orphans, structure drift, root clutter
/health library            # delegate to /library scan + sync + drift + new
/health releases           # delegate to /release verify tags
/health ci                 # delegate to /ci-setup audit (Forgejo workflow drift, conditional)
/health agents             # review unreviewed agent-created issues (ai-suggested label)
/health agents triage      # interactive triage: dismiss, promote, or skip each signal
/health docker             # delegate to /docker-audit (if Dockerfile* or compose.yaml detected)
/health website            # delegate to /website-health (if website project detected)
/health branches           # stale branch audit — local, GitHub, Forgejo
/health issues             # open GitHub BACKLOG issues for findings

Loop Integration

/loop 1h /health full      # hourly comprehensive audit
/loop 1d /health security  # daily security check
/loop 1d /health library   # daily library drift check

Uses the native Claude Code /loop bundled skill (CronCreate under the hood). Tasks are session-scoped and auto-expire after 3 days.

---

Subcommand: /health (summary)

Auto-detect project type and print a one-line status per dimension.

Steps:

1. Detect project type: check for pyproject.toml (Python), package.json (Node), Cargo.toml (Rust), MCP server markers (server.py, mcp.json)
2. Run each dimension sequentially (each sub-check runs to completion; delegated checks like security/library may take 30-300s)
3. Print consolidated summary with overall gate

Output:

## Health Summary — <project-name> — <date>

Endpoints  [PASS]  14 routes, all documented
Versions   [WARN]  pyproject.toml (0.3.1) ≠ README badge (0.3.0)
Docs       [PASS]  CLAUDE.md current, README current
Security   [PASS]  No critical/high findings
Quality    [PASS]  0 lint errors, 45/45 tests, 87% coverage
Tech Debt  [PASS]  0 critical findings
Hygiene    [WARN]  .coverage not in .gitignore; 2 unexpected top-level dirs
Releases   [PASS]  3 tags, all match CHANGELOG + GH/FJ releases + artifacts (pypi: 3/3)
Agents     [WARN]  12 unreviewed signals across 3 repos — run /health agents triage
Branches   [WARN]  3 local merged, 1 remote stale on Forgejo (if git repo)
Docker     [WARN]  Non-root USER missing in Dockerfile (if Docker files detected)
Website    [PASS]  7/7 dimensions pass (if website project detected)

Overall: WARN — 3 FIX-NOW (apply immediately) · 2 TRACK (open issues)

---

Subcommand: /health endpoints

Compare implemented routes vs what is documented in README or API docs.

Detection patterns:

Stack	Pattern
FastAPI	@router.(get|post|put|delete|patch), @app.(get|post|...)
Click CLI	@click.command, @cli.command, @<group>.command
MCP	@mcp.tool, @server.tool, @server.list_tools
Express/Next.js	app.(get|post|...), router.(get|...), pages/api/** glob

Steps:

1. Grep codebase for route/command decorators → build implemented set
2. Parse README "API Reference", "Commands", or "Endpoints" section → build documented set
3. Diff: implemented ∩ documented = OK; implemented \ documented = undocumented; documented \ implemented = dead docs

Gate:

• PASS: all implemented routes documented
• WARN: undocumented routes exist (non-security-critical)
• FAIL: undocumented route with auth/data-mutation pattern (POST/PUT/DELETE without docs)

---

Subcommand: /health versions

Cross-check all version strings across manifest files and README.

Version file detection (reuses /release changelog Step 6 patterns):

File	Path
Python	pyproject.toml → [project] version or [tool.poetry] version
Node	package.json → .version
Rust	Cargo.toml → [package] version
Legacy Python	setup.cfg → version =
README badge	shields.io/badge/version-X.Y.Z or similar

Steps:

1. Find all version files via glob
2. Extract version string from each
3. Compare — flag any that differ
4. Output version matrix table

Gate:

• PASS: all versions match
• WARN: README badge differs (cosmetic)
• FAIL: any two production manifests disagree (pyproject.toml, package.json, Cargo.toml, setup.cfg — README badge excluded from FAIL since it's cosmetic) Note: normalize ranges (^1.2 → 1.2.x) before comparing; VCS/path deps are flagged as WARN with a note to pin

---

Subcommand: /health docs

Check required documentation exists at the root, is in the right location, and is not stale. Also audits user-facing docs via /docs audit (dual mode: Starlight for apps, markdown for libs/services).

Delegates to:

• /docs audit — user-facing docs (dual mode auto-detected from repo):
  • App mode (app-*): site/ present? Starlight pages stale? links rotti? language parity IT↔EN?
• /documentation-updater — checklist completeness (only when all required files exist)
• /registry stale 30 — stale act-status skills (>30 days); plan/do/check with null dates are excluded (not yet in validation phase)

Step 0 — Existence check

Required root-level docs and their init path when missing:

File	Severity if missing	Init suggestion
CLAUDE.md	FAIL	/claude-md-management:claude-md-improver
README.md	FAIL	/documentation-updater
LICENSE	WARN	/health license (advisor mode)
ROADMAP.md	WARN	/documentation-updater (architecture docs)
TECH-STACK.md	WARN	/documentation-updater (configuration docs)

For each missing file: report the finding, state the severity, and offer the init command.

LICENSE note: If LICENSE is missing, note it as WARN and print: "Run /health license to get an interactive advisor that will recommend the right license based on your project type."

Step 1 — Location check

Search for required docs in non-root locations and flag misplaced copies:

for f in CLAUDE.md README.md ROADMAP.md TECH-STACK.md; do
  # Check root
  root_present=$([ -f "$f" ] && echo "yes" || echo "no")
  # Find any copies elsewhere (exclude .git, node_modules, .venv)
  elsewhere=$(find . -name "$f" \
    -not -path "./.git/*" \
    -not -path "./node_modules/*" \
    -not -path "./.venv/*" \
    -not -path "./.archive/*" \
    -not -maxdepth 1 2>/dev/null)
  # If found in subdir but not at root → WARN: propose move
  # If found in subdir AND at root → INFO: note the duplicate
done

Report as WARN with the path and suggest: "Move to project root and update any links."

Step 2 — Staleness check

Only runs for files confirmed present at root. Uses Unix timestamps to avoid sign-flip bug when file is absent.

# Last CLAUDE.md/README change vs last code change — use Unix timestamps for arithmetic
DOC_TS=$(git log -1 --format="%ct" -- CLAUDE.md README.md ROADMAP.md TECH-STACK.md 2>/dev/null || echo 0)
CODE_TS=$(git log -1 --format="%ct" -- src/ app/ lib/ 2>/dev/null || echo 0)
DIFF_DAYS=$(( (CODE_TS - DOC_TS) / 86400 ))
# Positive DIFF_DAYS = code newer than docs (stale)
# Only evaluate if DOC_TS > 0 (files exist in git history)

Gate:

• PASS: all required files present at root AND DIFF_DAYS < 7
• WARN: ROADMAP.md or TECH-STACK.md missing OR any misplaced doc OR DIFF_DAYS ≥ 14
• FAIL: CLAUDE.md or README.md missing OR DIFF_DAYS ≥ 28 OR registry has >5 stale act-status skills (exclude plan/do/check with null last_manual_test — expected pre-validation)

Step 2.5 — Instruction file structure check

Runs after staleness check. Checks CLAUDE.md, AGENTS.md, or both (whichever are present).

a) Line count

for f in CLAUDE.md AGENTS.md; do
  [ -f "$f" ] && wc -l < "$f" || echo 0
done

• PASS: ≤150 lines each
• WARN: 151–250 lin

---

Content truncated.