Repo Audit Skill
Perform a comprehensive audit of the host repository against the ecosystem baseline. Emits a structured Markdown checklist report and a JSON sidecar for trend tracking.
Invocation
There are no arguments — ignore $ARGUMENTS; anything passed is discarded.
Do NOT skip any category (except Clank when not detected). Do NOT auto-fix findings — report only.
Purpose
Answer the question: "Does this repo match the ecosystem baseline?" — a compliance-focused, checkable question with a fixed 9-category checklist. Distinct from /discovery (broad quality probes) and /harness-audit (plugin installation health).
Phase 1: Read Session Config
Read the project's ## Session Config section in CLAUDE.md (or AGENTS.md for Codex CLI). Store resolved values as $CONFIG.
Command resolution follows skills/quality-gates/SKILL.md priority order:
.orchestrator/policy/quality-gates.json — canonical policy file (if present).- Session Config
test-command / typecheck-command / lint-command — fallback.
- Hardcoded defaults:
npm test, npm run typecheck, npm run lint.
If any command is set to the literal string skip, skip that check entirely and mark it skipped.
Phase 2: Clank Detection
Check for Clank integration markers:
ls .clank/ 2>/dev/null || ls clank.config.* 2>/dev/null || ls clank.config.json 2>/dev/null
Set $CLANK_DETECTED=true if any marker exists, false otherwise.
Also check Session Config for ecosystem: baseline — if set, treat Clank checks as required rather than optional.
Phase 3: Run 9 Audit Categories
Run all checks in parallel where possible. For each check use the status symbols:
✓ — passes✗ — fails (action required)⚠ — warning (review recommended)skipped — intentionally skipped
Category 1: Configuration
| Check | Method |
|---|
CLAUDE.md exists (at most 80 non-exempt lines; runtime ## Session Config block exempt) | node "$PLUGIN_ROOT/scripts/lib/claude-md-budget-lint.mjs" --file CLAUDE.md |
.claude/rules/ has path-scoped rules | ls .claude/rules/*.md 2>/dev/null |
.claude/settings.json exists | ls .claude/settings.json |
.mcp.json exists with servers | ls .mcp.json |
.gitignore covers .env*, node_modules, build artifacts | `grep -E '.env* |
Category 2: Code Quality
Commands resolved from Session Config per Phase 1.
| Check | Method |
|---|
ESLint v9 flat config (eslint.config.mjs) | ls eslint.config.mjs 2>/dev/null |
Prettier config (.prettierrc or prettier.config.*) | ls .prettierrc* prettier.config.* 2>/dev/null |
TypeScript strict mode ("strict": true in tsconfig.json) | grep '"strict": true' tsconfig.json |
| 0 TypeScript errors | Run {typecheck-command} 2>&1 — pass if exit code 0 |
No console.log in production code (excluding tests) | `grep -r 'console.log' --include='.ts' --include='.mts' --exclude-dir=tests --exclude-dir=node_modules . 2>/dev/null |
| Lint passes | Run {lint-command} 2>&1 — pass if exit code 0 |
Category 3: Git Hygiene
| Check | Method |
|---|
| Husky + lint-staged configured | ls .husky/ 2>/dev/null && grep 'lint-staged' package.json |
| commitlint (Conventional Commits) | `ls commitlint.config.* 2>/dev/null |
| Gitleaks pre-commit or CI | `ls .gitleaks.toml 2>/dev/null |
| No secrets in git history | `git log --all -p 2>/dev/null |
Category 4: CI/CD
| Check | Method |
|---|
CI config exists (.gitlab-ci.yml or .github/workflows/) | ls .gitlab-ci.yml 2>/dev/null || ls .github/workflows/*.yml 2>/dev/null |
| Stages include validate → security → test → deploy | Read CI config, check for these stage names |
| Typecheck in CI | `grep -E 'tsgo |
| Tests in CI | `grep -E 'vitest |
| Dependency audit in CI | `grep -E 'audit |
Category 5: Testing
| Check | Method |
|---|
Vitest configured (vitest.config.ts or vitest.config.mjs) | ls vitest.config.* 2>/dev/null |
| Test coverage configured | grep 'coverage' vitest.config.* 2>/dev/null |
| E2E tests (Playwright) for frontend repos | ls playwright.config.* 2>/dev/null — only required if next.config.* or nuxt.config.* exists |
Test scripts in package.json | grep '"test"' package.json 2>/dev/null |
| Tests pass | Run {test-command} 2>&1 — pass if exit code 0 |
Category 6: Security
| Check | Method |
|---|
Auth-at-boundary pattern (requireAuth) | grep -r 'requireAuth' --include='*.ts' src/ 2>/dev/null || echo "N/A (no src/)" |
| Zod validation on inputs | grep -r 'z\.object|z\.string|z\.parse|safeParse' --include='*.ts' src/ 2>/dev/null || echo "N/A" |
| No hardcoded secrets (scan for API key patterns) | grep -r 'sk-|api_key\s*=\s*"' --include='*.ts' --include='*.mts' --exclude-dir=node_modules . 2>/dev/null — warn if found |
No PAT/token in settings-allowlist entries (.claude/settings.json, .claude/settings.local.json — on-disk, incl. untracked) | grep -nEo 'glpat-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,}|sk-ant-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}' .claude/settings.json .claude/settings.local.json 2>/dev/null | grep -vE 'AKIAIOSFODNN7EXAMPLE|-PLACEHOLDER' — fail if any match (hard — unlike the sk- heuristic above, these 5 prefixes are high-signal; see SEC-025 in .claude/rules/security.md). This check is required because check-owner-leakage.mjs scans git ls-files only — settings.local.json is gitignored/untracked by convention and structurally invisible to it. |
.env* files not tracked | `git ls-files |
.env.example documents all secrets | ls .env.example 2>/dev/null |
Note: RLS, rate limiting, and CORS checks are ⚠ review items — they require human judgment and cannot be fully automated. Flag them as ⚠ manual-review-recommended.
Category 7: Documentation
| Check | Method |
|---|
README.md exists | ls README.md 2>/dev/null |
.env.example exists with documented vars | ls .env.example 2>/dev/null |
Architecture documented in CLAUDE.md | grep -i 'architecture|structure|stack' CLAUDE.md 2>/dev/null |
Category 8: Clank Integration (Optional)
If $CLANK_DETECTED=false AND ecosystem: baseline is NOT set in Session Config:
### 8. Clank Integration
Status: skipped — Clank not detected (.clank/ and clank.config.* absent; ecosystem: baseline not set)
Do not mark any Clank check as ✗. Absence of Clank is not a failure outside the baseline ecosystem.
If $CLANK_DETECTED=true OR ecosystem: baseline is set:
| Check | Method |
|---|
GET /health endpoint exists (for services) | grep -r '/health' --include='*.ts' src/ 2>/dev/null |
| CI pipeline sends webhooks to Event Bus | grep -E 'webhook|event.bus|clank' .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null |
| Sentry configured (for user-facing apps) | grep -r 'Sentry' --include='*.ts' --include='*.mts' --exclude-dir=node_modules . 2>/dev/null |
| Conventional Commits enforced (commitlint) | `ls commitlint.config.* 2>/dev/null |
Category 9: MCP Configuration
Scope: Audits only the repo-local .mcp.json file — does NOT cover the user-machine MCPJungle gateway or globally-imported MCP servers.
| Check | Method |
|---|
.mcp.json exists | ls .mcp.json 2>/dev/null |
| MCP servers match project type | Read .mcp.json, verify server list is appropriate (e.g., shadcn only for frontend repos, no stale servers) |
| No stale or unused MCP entries | Cross-reference .mcp.json servers against project stack markers |
MCP server health probe (optional — requires mcporter) | For each server declared in repo-local .mcp.json: if command -v mcporter is present, run mcporter list --json and read the per-server status field — ok → ✓ pass; auth → ⚠ warn (remediation: mcporter auth <server>); offline/error → ✗ fail. If mcporter is absent → mark this check skipped with note "enable with npm install -g mcporter". mcporter is never a hard dependency; the repo audit proceeds without it. |
Phase 4: Emit Report
4.1 Markdown Report (stdout)
Emit a structured report in this format:
# Repo Audit Report — <repo-name>
Generated: <ISO timestamp>
Session Config commands: test=`<test-command>` typecheck=`<typecheck-command>` lint=`<lint-command>`
## Summary
| Category | Pass | Fail | Warn | Skipped |
|---|---|---|---|---|
| 1. Configuration | N | N | N | N |
| 2. Code Quality | N | N | N | N |
| 3. Git Hygiene | N | N | N | N |
| 4. CI/CD | N | N | N | N |
| 5. Testing | N | N | N | N |
| 6. Security | N | N | N | N |
| 7. Documentation | N | N | N | N |
| 8. Clank Integration | N | N | N | N |
| 9. MCP Configuration | N | N | N | N |
| **Total** | N | N | N | N |
**Overall:** ✓ PASS / ✗ FAIL / ⚠ WARN
## Detailed Results
### 1. Configuration
- ✓ CLAUDE.md exists (72 non-exempt lines — within the 80-line budget)
- ✗ `.claude/settings.json` missing — create with permissions and hooks
- ⚠ `.mcp.json` missing — add MCP servers appropriate for your stack
...
### 2. Code Quality
...
### 8. Clank Integration
skipped — Clank not detected (.clank/ and clank.config.* absent; ecosystem: baseline not set in Session Config)
### 9. MCP Configuration
- ✓ `.mcp.json` exists
- ✓ Servers match project type
- ⚠ MCP server health probe: `github` → ok; `shadcn` → auth (run `mcporter auth shadcn`)
## Critical Findings
<List only ✗ items — actionable, with fix guidance>
## Action Items
<Numbered list of recommended fixes, ordered by priority>
4.2 JSON Sidecar
Write to .orchestrator/metrics/repo-audit-<unix-timestamp>.json:
{
"schema_version": 1,
"generated_at": "<ISO timestamp>",
"repo": "<basename of cwd>",
"commands": {
"test": "<resolved test-command>",
"typecheck": "<resolved typecheck-command>",
"lint": "<resolved lint-command>"
},
"clank_detected": false,
"ecosystem_baseline": false,
"categories": {
"configuration": { "pass": 4, "fail": 1, "warn": 0, "skipped": 0, "checks": [] },
"code_quality": { "pass": 3, "fail": 1, "warn": 1, "skipped": 0, "checks": [] },
"git_hygiene": { "pass": 2, "fail": 1, "warn": 0, "skipped": 0, "checks": [] },
"ci_cd": { "pass": 0, "fail": 5, "warn": 0, "skipped": 0, "checks": [] },
"testing": { "pass": 4, "fail": 0, "warn": 0, "skipped": 1, "checks": [] },
"security": { "pass": 3, "fail": 1, "warn": 2, "skipped": 0, "checks": [] },
"documentation": { "pass": 2, "fail": 0, "warn": 1, "skipped": 0, "checks": [] },
"clank_integration": { "pass": 0, "fail": 0, "warn": 0, "skipped": 4, "checks": [] },
"mcp_configuration": { "pass": 1, "fail": 0, "warn": 2, "skipped": 0, "checks": [] }
},
"summary": {
"total_pass": 0,
"total_fail": 0,
"total_warn": 0,
"total_skipped": 0,
"overall": "pass|fail|warn"
}
}
Each checks array entry:
{ "id": "config.claude-md-exists", "status": "pass|fail|warn|skipped", "detail": "human-readable result" }
MCP server health entries additionally include an optional remediation field (representative examples):
{ "id": "mcp.server-health-github", "status": "pass", "detail": "mcporter: status=ok", "remediation": null }
{ "id": "mcp.server-health-shadcn", "status": "warn", "detail": "mcporter: status=auth", "remediation": "mcporter auth shadcn" }
{ "id": "mcp.server-health-probe", "status": "skipped", "detail": "mcporter not installed — enable with npm install -g mcporter", "remediation": "npm install -g mcporter" }
Create .orchestrator/metrics/ if it does not exist:
mkdir -p .orchestrator/metrics
Write using node -e or direct file write — do not require any external dependency.
Overall Status Logic
✗ FAIL — any check has status fail⚠ WARN — no fails, but at least one warn✓ PASS — all checks are pass or skipped
Success Criteria
- All 9 categories checked with pass/fail/warn/skipped status
- Clank section correctly detected and marked
skipped when absent
- Commands resolved from Session Config (not hardcoded
pnpm)
- JSON sidecar written to
.orchestrator/metrics/repo-audit-<timestamp>.json
- No false positives — verify findings before reporting
- Critical security findings flagged prominently in "Critical Findings" section