Project Audit

Project Audit

Diagnose organizational health of any project: CLAUDE.md, memory, file structure, git, automations. Produce an actionable report grouped by severity, then let the user decide what to address.

Why this exists: Projects grow organically — CLAUDE.md gets stale, memory files accumulate dead links, files land in wrong places, secrets sneak into git. Without periodic checkups, Claude Code gets worse context and the user loses track of what's where.

What this skill does NOT do: It does not auto-fix anything. It diagnoses and recommends. The user decides which recommendations to act on — then can ask Claude to execute them.

Two modes:

• Quick (~5 min) — CLAUDE.md, memory, file architecture. No agents, no git, no automations. Best for regular checkups.
• Full (~8 min) — everything from Quick + git hygiene, automations, deep analysis via 5 parallel agents. Best for first audit, pre-share cleanup, or when something feels off.

Safety rules

Mode selection

MANDATORY: Always ask the user which mode they want before proceeding.

Args shortcut: When invoked as /project-audit full or /project-audit полный, the skill receives the argument via the args parameter. If args contain "full" or "полный" — skip the question and go straight to Full mode. Same for "quick" or "быстрый" → Quick mode.

If no args match, ask (use AskUserQuestion if available, text otherwise):

Какой режим аудита?

• Quick (~5 мин) — CLAUDE.md, memory, архитектура проекта
• Full (~8 мин) — всё из Quick + git гигиена, автоматизации, глубокий анализ через параллельных агентов

Step 0 — Reconnaissance (both modes)

Before auditing, map the environment. Run all discovery commands in parallel where possible.

First: root check. If CWD is /, C:\, or a drive root — refuse immediately:

"Запустите аудит из папки конкретного проекта, не из корня диска."

Git, CLAUDE.md, Memory discovery

git rev-parse --is-inside-work-tree 2>/dev/null && echo "GIT: yes" || echo "GIT: no"

Use the Glob tool with pattern **/CLAUDE.md to find all CLAUDE.md files in the project.

ls ~/.claude/projects/ 2>/dev/null | head -20

If no CLAUDE.md found — that is itself a Critical finding. If not a git repo — note for "Skipped" section.

Match current project to a memory slug. Check for MEMORY.md inside the matched folder. Also check for memory/ inside the project itself.

Read each found CLAUDE.md (first 100 lines) and store content for later analysis. Run ls on root and store output (first 20 lines).

Project type detection

Check for code manifests and business folders. Use detection signals from references/project-type-checklists.md section "Project Type Detection".

# Code signals — manifests AND src/ directory
ls package.json requirements.txt go.mod Cargo.toml pyproject.toml *.sln 2>/dev/null
ls -d src/ app/ lib/ 2>/dev/null

For business/product signals (also match numbered prefixes like 02-audience, 04-marketing), use the Glob tool with pattern *{audience,marketing,analytics,strategy,operations,products}* — check first 2 directory levels only.

Classification:

• Code manifests found AND src//app//lib/ exists, no business folders → Code
• Business folders found (3+), no src//app//lib/ → Product (even if package.json exists — utility scripts don't make it a code project)
• Mostly .md/.html/.txt with no manifests or business folders → Docs
• src//app//lib/ exists AND 3+ business folders → Mixed

Key insight: package.json alone doesn't indicate a Code project — many docs/product projects have it for utility scripts. The presence of src/, app/, or lib/ is a much stronger signal.

If none of the above match (very few files, no clear signals) → treat as Docs and focus on file hygiene. Note the ambiguity in the report.

File count

# Count project files (exclude common noise directories)
find . -type f -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.next/*' -not -path '*/dist/*' 2>/dev/null | wc -l

(Note: find is acceptable here — Glob doesn't support counting. Pipe through wc -l only.)

Previous audit check

Derive memory slug from CWD: replace /, \, :, spaces with -, lowercase. Example: E:\VibeCoding\MyProject → e--vibecoding-myproject.

Check ~/.claude/projects/<slug>/memory/audits/ for existing reports. If found:

Предыдущий аудит: [date]. Показать что изменилось?

If user agrees — after the current audit completes, read previous report and compare:

• Fixed — issues from previous audit no longer present
• New — issues not in previous audit
• Persists — issues still present from previous audit

Add a "Changes since last audit" section to the report before the Action plan.

Show summary

Окружение:
- Git: yes/no
- CLAUDE.md: [locations or none]
- Memory: [path or none]
- Тип проекта: code/product/docs/mixed
- Файлов: ~N

Quick mode

Quick runs Steps 1-3 sequentially. No agents, no git checks, no automations.

Quick Step 1 — CLAUDE.md audit

Use checklist from references/checklists.md, section "CLAUDE.md checklist".

Key checks:

• Documented folder structure vs reality — run ls on project root and compare with what CLAUDE.md describes. Stale structure docs are the #1 source of Claude getting confused about where things are. This is the single most impactful check.
• Broken internal links — extract all paths/links from CLAUDE.md, verify each exists. Use Glob or ls to check.
• Freshness — look for dates in CLAUDE.md. If "Updated" date is >3 months old, flag as Warning. Check if described state matches current reality.
• Empty or stub sections — headers with no content underneath, or placeholder text like "TODO", "TBD".
• Secrets or tokens — scan for patterns like sk-, ghp_, Bearer, API keys. If found: Critical.
• Missing critical sections — project description, key files list, instructions for Claude, gotchas/warnings. Each missing section = Warning.
• Multiple CLAUDE.md files — if found at different depths, check for contradictions between them.

Quick Step 2 — Memory audit

Skip if no memory found in Step 0. Note skip in report.

Use fallback checklist from references/checklists.md, section "Memory checklist".

Checks:

1. Broken links — does each link in MEMORY.md point to a file that actually exists? Check with Glob or ls.
2. Orphan files — .md files in memory folder not referenced by MEMORY.md. List all .md files, cross-reference with MEMORY.md links.
3. Frontmatter — each memory file should have name, description, type in YAML frontmatter. Missing fields = Warning.
4. Zombie references — memory files that mention specific project files, paths, or URLs that no longer exist. Read each linked memory file (don't recurse deeper) and verify key references.
5. CLAUDE.md overlap — same information maintained in both MEMORY.md and CLAUDE.md leads to drift. Flag overlapping content.
6. Stale entries — entries with dates >6 months old, or statuses like "В процессе" / "In progress" for clearly finished work.

Quick Step 3 — Architecture scan

1. Top-level scan: Use the Glob tool with pattern */ and */*/ to list directories up to 2 levels deep. Also run ls -la for root contents.

2. Load checklist from references/project-type-checklists.md matching detected project type (Code/Product/Docs/Mixed). For Mixed projects, load both Code and Product checklists.

3. Zone presence — check expected folders for this project type exist. Missing critical zones = Warning.

4. File hygiene:

   • Root clutter — data files, HTML pages, images in root that should be in subdirectories. Standard root files are fine: README, CLAUDE.md, package.json, .gitignore, config files, LICENSE.
   • Temp/duplicate files — .tmp, .bak, Copy of..., files with (1), (2) suffixes
   • Large files (>1MB):

     find . -type f -size +1M -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | head -20
     

     (Note: find -size has no Glob equivalent — bash is acceptable here.)
   • IDE artifacts — .idea/, .vscode/ with non-standard contents, *.swp, Thumbs.db, .DS_Store
   • Empty directories:

     find . -type d -empty -not -path '*/.git/*' 2>/dev/null | head -10
     

     (Note: empty dir detection has no Glob equivalent — bash is acceptable here.)

5. Apply severity modifiers from references/project-type-checklists.md section "Severity Modifiers Table"

After Step 3, compile the detailed report (see Report template below). Fill in sections 1-3. Sections 4-5 go into "Пропущено" with note: "Quick mode — git и автоматизации не проверяются."

End Quick report with:

Для полного аудита (git, автоматизации, глубокий анализ): /project-audit full

Full mode

After Step 0, dispatch 5 parallel agents using the Agent tool. Full mode covers everything Quick does plus git hygiene, automations, and deeper analysis.

Agent dispatch

Preparation — read all reference files first:

1. Read references/agent-prompts.md — get prompt templates, common blocks (Safety Rules, Output Format)
2. Read references/checklists.md — get all checklists
3. Read references/project-type-checklists.md — get type detection, severity modifiers
4. Build RECON RESULTS context block from Step 0 data:
   • Project name (derived from CWD folder name)
   • Project type (code/product/docs/mixed)
   • Git status (yes/no)
   • CLAUDE.md locations (paths found)
   • Memory path (or "none")
   • File count
   • Root listing (ls output, first 20 lines)
   • CLAUDE.md content (first 100 lines of each found file)

Build each agent prompt by replacing these placeholders:

Agent ↔ checklist mapping:

• Agent 1 → "CLAUDE.md checklist" + "Severity Modifiers Table"
• Agent 2 → "Memory checklist"
• Agent 3 → "File structure checklist" + the project-type checklist (Code/Product/Docs) + "Severity Modifiers Table"
• Agent 4 → "Git checklist"
• Agent 5 → "Automations checklist"

Why inject: Agents run in the project directory, not the skill directory. They cannot access references/ files themselves. The orchestrator MUST read these files and paste their content into each agent's prompt.

Dispatch all 5 agents in parallel using the Agent tool:

• Agent 1 (CLAUDE.md deep audit) — subagent_type: "Explore"
• Agent 2 (Memory audit) — subagent_type: "Explore"
• Agent 3 (File structure) — subagent_type: "Explore"
• Agent 4 (Git hygiene) — subagent_type: "Explore"
• Agent 5 (Automations) — subagent_type: "Explore"

Important: Agents do NOT invoke companion skills. Checklists are injected into prompts by the orchestrator. This keeps agent context small and prevents token explosion from nested skill invocations.

Synthesis

After all 5 agents return:

1. Collect all FINDINGS blocks from agent responses (each agent outputs findings in the Common Output Format)
2. Deduplicate — same issue found by multiple agents → keep the more detailed version, note which agents flagged it
3. Apply severity modifiers from references/project-type-checklists.md section "Severity Modifiers Table" (e.g., missing .gitignore in a docs project is Warning, not Critical)
4. Build the detailed report — map each agent's findings to the corresponding report section:
   • Agent 1 → Section "1. CLAUDE.md"
   • Agent 2 → Section "2. Memory"
   • Agent 3 → Section "3. Архитектура и файлы"
   • Agent 4 → Section "4. Git гигиена"
   • Agent 5 → Section "5. Автоматизации"
5. For each section, fill in "Что проверено" (from agent's ALL CLEAR + findings topics), "Находки" (findings with severity), "Рекомендации" (actionable fix for each finding)
6. Build the summary table from highest severity per area
7. Build the Action plan from all Critical + Warning findings across all areas
8. If any agent failed or timed out — note in "Пропущено" section with reason

Report template

The report is a detailed document with analysis per area, not a summary table. Each area gets its own section with what was checked, what was found, and specific recommendations.

# Аудит: [project name]

**Дата:** YYYY-MM-DD | **Режим:** Quick/Full | **Тип:** Code/Product/Docs/Mixed
**Файлов:** ~N | **Проблем:** Z

## Сводка

| Область | Статус | Находок |
|---------|--------|---------|
| CLAUDE.md | 🟢/⚠️/🔴 | N |
| Memory | 🟢/⚠️/🔴 | N |
| Архитектура | 🟢/⚠️/🔴 | N |
| Git | 🟢/⚠️/🔴 или ⏭️ | N |
| Автоматизации | 🟢/⚠️/🔴 или ⏭️ | N |

*Статус = наивысший severity среди находок в области. ⏭️ = пропущено (Quick mode).*

---

## 1. CLAUDE.md

### Что проверено
[Список проверок: структура, ссылки, свежесть, секреты, дубли с memory...]

### Находки
- 🔴 Critical: [конкретная проблема с путями/файлами]
- ⚠️ Warning: [проблема]
- 🟢 Low: [мелочь]

*(Если всё чисто: "Проблем не обнаружено.")*

### Рекомендации
- [Что конкретно сделать для каждой находки]

---

## 2. Memory

### Что проверено
[MEMORY.md индекс, ссылки, orphans, frontmatter, zombie references, overlap с CLAUDE.md...]

### Находки
- ...

### Рекомендации
- ...

---

## 3. Архитектура и файлы

### Что проверено
[Зоны по чеклисту типа проекта, root clutter, пустые папки, большие файлы, дубли...]

### Находки
- ...

### Рекомендации
- ...

---

## 4. Git гигиена *(только Full)*

### Что проверено
[.gitignore, секреты по имени файла, бинарники, untracked, статус...]

### Находки
- ...

### Рекомендации
- ...

---

## 5. Автоматизации *(только Full)*

### Что проверено
[Hooks, MCP серверы, settings, рекомендации по типу проекта...]

### Находки
- ...

### Рекомендации
- ...

---

## Пропущено
- [что пропущено и почему — Quick mode пропускает секции 4-5, отсутствие git/memory и т.д.]

---

## Action plan

Приоритезированный список действий (только Critical + Warning):

1. 🔴 [действие — конкретное, с указанием файлов]
2. 🔴 [действие]
3. ⚠️ [действие]
4. ⚠️ [действие]

**Какие пункты выполнить?**

Report principles

• Per-area structure — each area has "Что проверено", "Находки", "Рекомендации". This makes the report a useful reference document, not just a list.
• Summary table at top — quick overview before the details
• Findings are specific — include file paths, counts, examples. Not "есть проблемы" but "CLAUDE.md:15 ссылается на docs/api.md — файл не найден"
• Recommendations are actionable — not "fix this" but "переместить report.html из корня в docs/"
• Action plan = Critical + Warning only — Low items stay informational in area sections
• Language adaptation — match the user's language (RU or EN), section structure stays constant
• Closing question is key — "Какие пункты выполнить?" lets the user pick what to address. Skill does NOT execute fixes.

Severity criteria

Report saving

Path derivation

1. Derive slug from CWD: replace /, \, :, spaces with -, lowercase
   • E:\VibeCoding\MyProject → e--vibecoding-myproject
2. Target: ~/.claude/projects/<slug>/memory/audits/YYYY-MM-DD-audit.md

Steps

SLUG=$(pwd | tr '[:upper:]' '[:lower:]' | sed 's/[\/\\: ]/-/g')
AUDIT_DIR="$HOME/.claude/projects/$SLUG/memory/audits"
mkdir -p "$AUDIT_DIR"

Write the full report to $AUDIT_DIR/YYYY-MM-DD-audit.md.

If a file with the same date already exists → append -2, -3, etc.:

BASE="$AUDIT_DIR/2026-03-18-audit"
if [ -f "$BASE.md" ]; then
  N=2; while [ -f "$BASE-$N.md" ]; do N=$((N+1)); done
  FILE="$BASE-$N.md"
else
  FILE="$BASE.md"
fi

After writing:

1. Verify the file exists: ls -la "$FILE"
2. Confirm to user: "Отчёт сохранён: [full path]"

Edge cases

Reference files

All reference files live in references/ relative to this skill's directory:

Every references/ path in this file MUST point to an existing file. If a reference file is missing at runtime, skip the dependent check and note it in the report.