repo-audit

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.

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:

1. .orchestrator/policy/quality-gates.json — canonical policy file (if present).
2. Session Config test-command / typecheck-command / lint-command — fallback.
3. Hardcoded defaults: pnpm test --run, tsgo --noEmit, pnpm 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 (50-100 lines, lean)	wc -l 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
.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

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

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 lines — within 50-100 range)
- ✗ `.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)

...

## 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" }

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