From forge
Audits codebase for technical debt across architectural, structural, operational, and hygiene vectors; produces prioritized audit doc for /pipeline remediation.
npx claudepluginhub hatmanstack/claude-forge --plugin forgeThis skill is limited to using the following tools:
You coordinate a technical debt audit of a codebase. The auditor runs as a separate agent with its own context window.
Coordinates parallel agent audits for codebase health, evaluation (12-pillar scoring), technical debt, and documentation drift, producing intake docs for /pipeline.
Conducts full codebase health audit across architecture, security, code quality, dependencies, test coverage. Produces scored report with letter grades and prioritized remediation. Use for existing codebases or before releases.
Scans codebase for technical debt across six categories: code, architecture, tests, dependencies, docs, and infrastructure. Prioritizes findings and generates remediation plans with effort estimates.
Share bugs, ideas, or general feedback.
You coordinate a technical debt audit of a codebase. The auditor runs as a separate agent with its own context window.
$ARGUMENTS is optional context — the repo path, specific concerns, or scope constraints. If empty, audit the current working directory.
Ask scoping questions one at a time, preferring multiple choice. Wait for each answer before asking the next.
The health audit scans for technical debt across 4 vectors: architectural, structural, operational, and code hygiene. Findings are prioritized by severity (CRITICAL > HIGH > MEDIUM > LOW). The pipeline remediates until all CRITICAL and HIGH findings are resolved.
Question 1 — Known pain points give the auditor a starting hypothesis instead of scanning cold:
Are there parts of the codebase you already know are problematic?
Things that keep breaking, areas you dread touching, modules that slow down every PR.
A) Yes (tell me which areas and what's wrong)
B) No — scan everything with fresh eyes
Question 2 — Goal determines which debt vectors the auditor emphasizes:
What's the primary goal for this audit?
A) General health check — scan all 4 vectors equally
B) Production hardening — emphasize operational debt (error handling, timeouts, resource leaks, observability)
C) Onboarding prep — emphasize structural and hygiene debt (naming, dead code, documentation, test coverage)
D) Pre-release cleanup — focus on CRITICAL/HIGH items only, skip MEDIUM/LOW
Question 3 — Deployment target changes what "operational debt" means. A Lambda function has different concerns than a long-running container:
What's the deployment target?
A) Serverless (Lambda, Cloud Functions) — cold starts, execution limits, stateless constraints
B) Containers (ECS, Kubernetes, Docker) — resource management, health checks, graceful shutdown
C) Static hosting / SPA — build pipeline, CDN, client-side concerns
D) Monolith / traditional server — process management, connection pooling, memory leaks
E) Multiple (tell me which)
F) Not deployed yet / unsure
Question 4 — Scope and constraints in one question:
What should the health auditor cover, and is anything off-limits?
A) Full repo, no constraints
B) Full repo, but skip specific areas (tell me which — e.g., "don't touch the legacy auth module")
C) Specific directories only (tell me which)
Question 5 — Existing tooling helps the fortifier (hardening phase) know what guardrails already exist so it doesn't duplicate work:
What development tooling is already in place?
A) Full setup — linters, CI pipeline, pre-commit hooks, type checking
B) Partial (tell me what you have — e.g., "ESLint but no CI")
C) None — no linting, CI, or hooks configured
Generate the directory name: YYYY-MM-DD-health-slug
health-ragstack, health-api)docs/plans/YYYY-MM-DD-health-slug/Create the directory.
You (the orchestrator) must read the role prompt file and embed its contents in the agent's prompt. Agents cannot access skill directory files.
skills/pipeline/health-auditor.md — store contents as AUDITOR_PROMPT<role_prompt>
[Contents of health-auditor.md]
</role_prompt>
<task>
Audit the codebase in the current working directory.
Goal: [from Step 1]
Scope: [from Step 1]
Existing tooling: [from Step 1]
Constraints: [from Step 1]
</task>
Verify the auditor's output contains AUDIT_COMPLETE. If missing, the agent may have been truncated — report to the user and do NOT write health-audit.md with partial data.
If signal present, Write docs/plans/YYYY-MM-DD-health-slug/health-audit.md:
---
type: repo-health
date: YYYY-MM-DD
goal: [from Step 1]
---
# Codebase Health Audit: [repo name]
## Configuration
- **Goal:** [from Step 1]
- **Scope:** [from Step 1]
- **Existing Tooling:** [from Step 1]
- **Constraints:** [from Step 1]
## Summary
- Overall health: [CRITICAL | POOR | FAIR | GOOD | EXCELLENT]
- Total findings: X critical, Y high, Z medium, W low
## Tech Debt Ledger
[Full auditor output — prioritized findings with file:line locations]
## Quick Wins
[Low effort, high impact items from the auditor]
## Automated Scan Results
[Tool output summaries from knip/vulture, npm audit/pip-audit, etc.]
Append an entry to .claude/skill-runs.json in the repo root. If the file does not exist, create it with an empty array first.
{
"skill": "repo-health",
"date": "YYYY-MM-DD",
"plan": "YYYY-MM-DD-health-slug"
}
Audit complete: docs/plans/YYYY-MM-DD-health-slug/health-audit.md
Findings: X critical, Y high, Z medium, W low
Quick wins identified: N
To remediate, run:
/pipeline YYYY-MM-DD-health-slug
/pipeline after all remediation is complete.