Audit Skill

Audit Skill

Audit the existing .claude/ setup — find gaps, outdated info, missing primitives, and fix them.

Prerequisites

• CLAUDE.md must exist (if it does not, suggest running /forge:setup instead)
• .claude/ folder should exist for a meaningful audit

Execution Flow

Run these 6 phases in order.

---

Phase 1: Pre-Check

1. Verify CLAUDE.md exists. If not: "No CLAUDE.md found. Run /forge:setup to generate one, or /forge:audit is not applicable." — abort.
2. Verify .claude/ folder exists. If not: warn that audit will be limited to CLAUDE.md only.
3. Read the current CLAUDE.md fully into memory.
4. Read all files in .claude/ recursively (primitives, agents, skills, prompts).
5. Prepare for comparison.

---

Phase 2: Deep Scan

Perform a thorough comparison between what CLAUDE.md/.claude/ claims and what the codebase actually contains.

Version Check:

• Read package.json dependencies — compare versions against what CLAUDE.md states
• Read *.csproj — compare .NET version, NuGet packages
• Check if Tailwind v3 vs v4 is correctly identified
• Check if Next.js/Remix/Vite version matches

Primitive Accuracy:

• For each primitive in .claude/primitives/:
  • Does the rule still apply? (e.g., if TAILWIND_FIRST is listed but project switched to CSS modules)
  • Are there code patterns that violate the primitive? (informational, not blocking)
• Are there technologies in use that have NO corresponding primitive?

Agent Relevance:

• For each agent in .claude/agents/:
  • Is the agent's stack still correct? (e.g., sql-agent references MSSQL but project uses PostgreSQL)
  • Are model references up to date?
• Are there roles that should have agents but don't?

Skill Coverage:

• For each skill in .claude/skills/:
  • Is the technology still in use?
  • Is the skill content still accurate?
• Are there technologies in use with no corresponding skill?

Structural Check:

• Does CLAUDE.md have all expected sections? (Tech Stack, Design System, Folder Structure, Agents, Rules)
• Are folder paths in CLAUDE.md still accurate?
• Are environment variables documented?
• Is the design system section complete?

Plan Freshness (if plans/ exists):

• Are plan statuses up to date?
• Are there completed features still marked as TODO?

---

Phase 3: Report

Generate a traffic-light report. Group findings by severity:

## Audit Report

### 🔴 Critical (must fix)
- **Next.js version mismatch** — CLAUDE.md says 15.x, package.json has 16.0.0
- **Missing primitive** — Project uses Biome but no BIOME_LINTING primitive exists
- **Dead agent** — sql-agent references MSSQL but no database dependency found

### 🟡 Warning (should fix)
- **Outdated design tokens** — CLAUDE.md lists --color-primary: #ea580c but app.css has #f97316
- **Missing skill** — firebase-auth is in dependencies but no Firebase Auth skill exists
- **Stale plan** — plans/v1/03-content/PLAN.md is marked TODO but Sanity schemas exist

### 🟢 OK
- TypeScript strict mode — correctly documented
- Tailwind v4 — correctly identified
- Git rules — match actual branch naming
- Frontend agents — up to date
- 12 of 15 primitives accurate

### Summary
| Category | 🔴 | 🟡 | 🟢 |
|----------|-----|-----|-----|
| Versions | 1 | 0 | 3 |
| Primitives | 1 | 0 | 5 |
| Agents | 1 | 0 | 2 |
| Skills | 0 | 1 | 3 |
| Structure | 0 | 1 | 4 |
| **Total** | **3** | **2** | **17** |

---

Phase 4: Fix

Ask the user how to proceed:

Found 3 critical issues and 2 warnings.

How would you like to proceed?
1. **Fix all** — automatically fix all critical and warning issues
2. **Fix critical only** — fix 🔴 issues, skip 🟡
3. **Selective** — let me choose which to fix
4. **Report only** — don't fix anything, just save the report

For each fix:

1. Show what will change (before → after)
2. Apply the change
3. Mark as fixed in the report

Fix types:

• Version update — update version numbers in CLAUDE.md
• Add primitive — create new .claude/primitives/{NAME}.md using reference templates
• Remove primitive — delete the file (with user confirmation)
• Update agent — modify the agent definition
• Add skill — create new .claude/skills/{name}/SKILL.md
• Update structure — fix folder paths, add missing sections to CLAUDE.md
• Update tokens — refresh design system section from actual CSS
• Update plan status — mark features as DONE based on codebase evidence

---

Phase 5: Plugin Check

Check if recommended companion plugins are installed:

1. Look for market-lens commands — if project would benefit but not installed, suggest it
2. Look for cross-lens commands — if project is complex enough, suggest it

Use recommendations from ${CLAUDE_PLUGIN_ROOT}/references/plugins.md.

## Plugin Recommendations

- market-lens — NOT installed. Recommended for your project type (Portfolio).
  Install: `/plugin marketplace add shavidze/market-lens`
  
- cross-lens — NOT installed. Useful for complex feature planning.
  Install: `/plugin marketplace add shavidze/cross-lens`

---

Phase 6: Summary

Print a final summary with before/after stats:

## Audit Complete

### Before
- 🔴 3 critical issues
- 🟡 2 warnings
- 🟢 17 items OK

### After
- 🔴 0 critical issues (3 fixed)
- 🟡 0 warnings (2 fixed)
- 🟢 22 items OK

### Changes Made
- Updated Next.js version in CLAUDE.md (15.x → 16.0.0)
- Created .claude/primitives/BIOME_LINTING.md
- Removed .claude/agents/sql-agent.md (no database detected)
- Updated design token --color-primary (#ea580c → #f97316)
- Created .claude/skills/firebase-auth/SKILL.md

Run `/forge:audit` again after major changes to keep your ecosystem fresh.

Error Handling

• If CLAUDE.md is corrupted or unparseable, offer to regenerate with /forge:setup
• If .claude/ folder has unexpected structure, audit what exists and note anomalies
• If fix fails (permission error, file locked), skip and report
• Never delete files without explicit user confirmation
• Always show before/after for destructive changes