Unified Audit

Single entry point for all audit types. Works in any project with .claude/rules/.

Routing

Parse $ARGUMENTS:

Argument	Action
project	Run Project Audit (below)
code	Run Code Audit (below)
spec	Run Spec Audit (below)
claude-md	Run CLAUDE.md Audit (below)
all	Run project → code → spec → claude-md in sequence
(none)	Show menu

No-Argument Menu

{
  "questions": [{
    "question": "Which audit would you like to run?",
    "header": "Audit",
    "options": [
      {"label": "Project", "description": "Structure, git hygiene, CLAUDE.md presence"},
      {"label": "Code", "description": "Code quality, security, test coverage"},
      {"label": "Spec", "description": "OpenSpec proposal quality and consistency"},
      {"label": "CLAUDE.md", "description": "Restructure and optimize CLAUDE.md"},
      {"label": "All", "description": "Run all audits in sequence"}
    ],
    "multiSelect": false
  }]
}

---

Project Audit

Core principle: Discover rules → Execute checks → Report gaps → Suggest fixes

Pre-check: Rules Installed?

Before running any audit, check if .claude/rules/ exists and has rule files:

ls .claude/rules/*.md 2>/dev/null | head -1

If no rules found:

⚠️  No rules found in .claude/rules/

Run /mindcontext-core:project-init to install standard rules
(code-quality, security, test-strategy), or audit will use built-in defaults.

Continue with audit regardless — use built-in defaults if no rules exist.

Discovery

1. Scan .claude/rules/ for all .md files
2. Read each file and look for:
   • YAML frontmatter with checks: array (machine-parseable rules)
   • Thresholds, guidelines, or checklists (human-readable rules)
3. Categorize rules found:
   • Structure rules (file/dir existence, project layout)
   • Documentation rules (CLAUDE.md sections, required docs)
   • Git rules (branch naming, stale branches)
   • Code quality rules (size limits, SOLID)
   • Security rules (secrets, injection patterns)
   • Testing rules (coverage targets, pyramid)

Check Types

For rules with machine-parseable checks: arrays:

Type	Verifies
file_exists	test -f {path}
dir_exists	test -d {path}
section_exists	Markdown heading present
managed_block_exists	Start/end markers present
file_contains	Pattern found in file
git_branch_pattern	Branch names match regex
git_no_stale_branches	No merged branches lingering
git_orphan_branches	Remote branches have open PRs
file_line_count	File length in range

For human-readable rules, check compliance by scanning codebase against the thresholds/guidelines described.

Report Format

# Project Audit Report

## Rules Checked
[List of .claude/rules/ files found and checked]

## Summary
| Category | Passed | Failed | Severity |
|----------|--------|--------|----------|

## [Category] Checks
✅ Check passed
❌ Check failed
   **Rule:** [rule-file.md]
   **Fix:** [command or action]

## Recommended Actions
Priority 1 (Errors) → Priority 2 (Warnings) → Priority 3 (Info)

Remediation

After report, offer: fix all errors / fix errors+warnings / show commands only / skip.

---

Code Audit

Comprehensive code quality analysis for production readiness.

Strategy

Use sub-agents for parallel analysis:

1. Structure Agent: File sizes, dependency counts
2. Test Coverage Agent: Test files, coverage gaps
3. Security Agent: Secret patterns, injection risks
4. Code Smell Agent: SOLID violations, long methods

Rules Discovery

1. Scan .claude/rules/ for rules related to code quality, security, and testing
2. Read each relevant rule file to get thresholds and checklists
3. If no rules found, use built-in defaults:

Default thresholds (when no rules exist):

• Files > 300 lines → warning
• Methods > 30 lines → warning
• Nesting > 3 levels → warning
• Class dependencies > 5 → warning
• No hardcoded secrets (connection strings, API keys, passwords)
• Test pyramid: Unit 60-70%, Integration 20-30%, E2E 5-10%

Analysis Areas (in order)

1. Test Coverage — Check against testing rules. Flag untested critical paths.
2. Error Handling — Null risks, unhandled exceptions, missing retries/timeouts.
3. File Size & Responsibility — Check against code quality rules.
4. SOLID Violations — Single responsibility, dependency injection, etc.
5. Code Smells — Duplicates, magic numbers, dead code, complex conditionals.
6. Security — Run security rule grep patterns if available. Check for secrets, injection.
7. Performance — N+1 queries, sync-over-async, missing pagination, no caching.
8. Architecture — Circular deps, layer violations, missing abstractions.
9. Maintainability — Missing docs, naming inconsistency, TODO inventory.

Output

Save report to docs/{project-name}/AUDIT_{YYYY-MM-DD}.md:

# Code Audit Report - [Project Name]
Generated: [Date]

## Rules Applied
[List of .claude/rules/ files used, or "built-in defaults"]

## Executive Summary
- Readiness score: X/10
- Critical/High/Medium issue counts

## Critical Issues (Fix Before Production)
## Test Coverage Roadmap (Phases 1-4)
## Refactoring Candidates (Tidy First)
## Security Findings
## Technical Debt Inventory

---

Spec Audit

OpenSpec proposal quality analysis. Checks consistency, completeness, and smell detection.

Input

Requires a target proposal. Parse $ARGUMENTS by stripping the leading spec token to get the optional path.

• With path (e.g., /audit spec openspec/changes/my-feature): use that path directly
• Without path (e.g., /audit spec): scan openspec/changes/ for active (non-archived) proposals. If exactly one found, use it. If multiple, let user choose.
• From /audit all: auto-scan openspec/changes/. If none found, skip spec audit silently. If one found, use it. If multiple, use most recently modified.

Rules Discovery

Load .claude/rules/spec-quality.md for smell definitions and thresholds. If not found, use built-in defaults from the spec smells table below.

Strategy

Use 3 parallel sub-agents for analysis:

1. Consistency Agent

• Cross-check proposal.md scope ↔ tasks.md task list (missing/extra items)
• Cross-check design.md interfaces ↔ specs/*.md scenarios (type mismatches)
• Cross-check tasks.md checkboxes ↔ actual completion state (check file existence for deliverables, not beads status)
• Flag contradictions between files

2. Completeness Agent

• Every requirement in specs/*.md has Given/When/Then scenarios
• Every scenario maps to at least one task in tasks.md
• Every task in tasks.md has a backing requirement
• Edge cases covered (empty input, error paths, boundary values)

3. Quality Agent

• Ambiguous language scan ("as needed", "etc.", "appropriate", "proper")
• Duplicate scenario detection (same Given/When/Then)
• Sizing check (requirements per spec, tasks in scope, spec file count)
• Magic value detection (undefined constants, hardcoded thresholds)
• Placeholder detection ("TODO", "TBD", "implement later")

Report Format

# Spec Audit Report

## Proposal
<proposal name and path>

## Rules Applied
[spec-quality.md or built-in defaults]

## Summary
| Category | Passed | Failed | Severity |
|----------|--------|--------|----------|
| Consistency | N | N | Critical/Warning |
| Completeness | N | N | Critical/Warning |
| Quality | N | N | Warning/Info |

## Critical Issues
❌ <issue description>
   **File:** <path>
   **Rule:** <spec smell name>
   **Fix:** <actionable suggestion>

## Warnings
⚠️ <issue description>
   **Fix:** <suggestion>

## Info
<improvement opportunity>

## Recommended Actions
1. [Most critical fix first]
2. [Second priority]

---

CLAUDE.md Audit

Audit and restructure CLAUDE.md for clarity and efficiency. Three phases: automated analysis, user interview, restructuring.

Supports flags: --quick (skip interview), --full (all questions), --dry-run (preview only).

Phase 1: Audit (Sub-Agents)

Launch 4 sub-agents IN PARALLEL:

Sub-agent 1: Repository Structure

Agent tool with subagent_type='Explore'
Prompt: "Analyze repository structure. Compare actual folders vs any documented structure. Report: top-level dirs, .claude/ structure, any submodules. List only - no file contents."

Sub-agent 2: Workflows & Skills

Agent tool with subagent_type='Explore'
Prompt: "Analyze workflows and skills in this repo. Scan: .claude/ (skills, rules, commands, agents), openspec/, docs/. Report: what workflow artifacts exist, which skills are registered."

Sub-agent 3: Undocumented Patterns

Agent tool with subagent_type='Explore'
Prompt: "Find undocumented patterns. Look for: .beads/, hooks.json, MCP configs, package.json scripts, new skills or rules not mentioned in CLAUDE.md. Report: potentially undocumented items."

Sub-agent 4: Current CLAUDE.md Analysis

Agent tool with subagent_type='Explore'
Prompt: "Analyze current CLAUDE.md. Report: line count, sections, what's documented, what seems outdated or overly detailed. Check against .claude/rules/claude-md-standard.md if it exists."

After all complete, summarize:

## Audit Summary

### Structure
| Item | Status | Notes |
|------|--------|-------|

### Undocumented Items
1. ...

### CLAUDE.md Issues
- Line count: X (target: 60-200)
- Overly detailed sections: ...
- Missing: ...
- Outdated references: ...

Present summary to user before proceeding.

Phase 2: Interview (One Question at a Time)

Skip if --quick flag is set.

Ask ONE question, wait for response, then ask next:

A: Project Focus — Active development / Maintenance / Learning B: Workflow Verification — Based on findings, confirm detected workflows C: Sub-Agent Usage — Which agents to document D: Planning Triggers — When must planning happen before coding E: Confirm Findings — Review undocumented items, overly detailed sections

Phase 3: Restructure

Skip modifications if --dry-run flag is set (show preview only).

3a: Extract detailed content (if CLAUDE.md has >20 lines per section):

• Extract to docs/WORKFLOW.md, docs/ARCHITECTURE.md as needed

3b: Create slim CLAUDE.md (target: 60-200 lines):

Required sections (from .claude/rules/claude-md-standard.md):

1. Critical Rules — Must-follow rules
2. Project Overview — What, architecture, key dirs
3. Quick Commands — Frequently used commands

Recommended: Sub-Agent Usage, Navigation tables.

Preserve all managed blocks (<!-- OPENSPEC:START -->, <!-- TDD-ENFORCEMENT:START -->, etc.)

3c: Validate against .claude/rules/claude-md-standard.md and .claude/rules/project-structure.md

3d: Show results:

CLAUDE.md RESTRUCTURED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Before: {old_lines} lines
After:  {new_lines} lines

Created:
  ✓ docs/WORKFLOW.md (if extracted)

Preserved:
  ✓ All managed blocks

Changes:
  - Moved {X} lines to docs/
  - Removed outdated sections
  - Updated command references
  - Added navigation section

---

Examples

/audit              → Shows menu
/audit project      → Project health check
/audit code         → Code quality audit
/audit spec         → OpenSpec proposal quality check
/audit claude-md    → CLAUDE.md restructuring
/audit all          → All in sequence