folder-audit

name

folder-audit

description

Evaluates any project's folder architecture against the ICM five-layer context hierarchy. Scores Layer 0 (Map/CLAUDE.md), Layer 1 (Rooms/CONTEXT.md), Layer 2 (Stage Contracts), Layer 3 (Reference Material), Layer 4 (Working Artifacts), plus Tools assessment. Checks 14 anti-patterns (8 base + 6 ICM), measures 5 structural metrics. Outputs a graded audit report with prioritized fixes. Use when: setting up Claude Code on a project, reviewing workspace quality, debugging degraded AI output, onboarding a new codebase, scoring folder structure, checking folder quality, evaluating project organization.

Folder Architecture Audit Skill

Evaluates a project folder against the ICM five-layer context hierarchy and produces a scored audit report. The base audit scores Layers 0–1 and Tools (X/16). If ICM pipeline stages are detected, an extended assessment covers Layers 2–4 (X/18).

Trigger

Use this skill when:

• The user asks to audit, evaluate, review, or score a project's folder structure
• The user is onboarding Claude Code to an existing project
• The user reports degraded AI output quality and the cause may be structural
• The user says "folder audit", "evaluate structure", "score this project", "check folder quality", or similar

Procedure

Step 1: Snapshot the File Tree

Generate a file tree of the target project. Exclude hidden directories (except .claude/), node_modules/, dist/, build/, __pycache__/, and other generated directories.

Use two Bash commands:
1. find [project-path] -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -name '.DS_Store' | grep -v '/\.' | sort | head -150
2. find [project-path]/.claude -type f 2>/dev/null | sort

The second command captures the .claude/ directory (skills, settings) which the first command's grep -v '/\.' excludes.

Step 2: Score Layer 0 -- The Map (CLAUDE.md)

Read the root CLAUDE.md (or equivalent root config). Score each criterion 0 or 1:

#	Criterion	Check
1	Root config exists	CLAUDE.md or equivalent at project root
2	Length under 50 lines	Count non-blank lines
3	Routing table present	Table with Task / Go-to / Read columns (minimum)
4	Naming conventions defined	Explicit patterns per file type, not "follow existing"
5	Identity section	2-3 sentences: what the project is, who it's for
6	Read-only folders marked	Assets, references, vendor clearly labeled

Layer 0 Score: X/6

Step 3: Score Layer 1 -- The Rooms (CONTEXT.md)

For each major workspace folder, check for a CONTEXT.md. Score each criterion 0 or 1, then average across workspaces:

#	Criterion	Check
1	CONTEXT.md exists	One per workspace
2	Under 80 lines	Concise, not exhaustive
3	Describes the work (80%+)	Project/audience/constraints, not Claude personality
4	Includes "What to Avoid"	Explicit anti-patterns
5	Fresh	Updated within project's active period
6	Lists key files	Points to important files in the workspace

Layer 1 Score: X/6 (average across workspaces, rounded)

Step 4: Score Tools

Inventory skills, playbooks, or automation files. Score each criterion 0 or 1:

#	Criterion	Check
1	Skills born from friction	Created after repeated manual steps, not pre-built
2	Scoped to workspaces	Loaded only where needed, not globally
3	Instructions are markdown	Not coded orchestration logic
4	Anti-fragile	Model updates simplify, not break

Tools Score: X/4

If the project is new and has no tools yet, score N/A (not a penalty). Tools should not exist until friction is identified.

Note on criterion 3: Deterministic helper scripts for mechanical work (fetching data, moving files, formatting output) are explicitly endorsed by ICM and should NOT be penalized. Criterion 3 targets orchestration logic in code — agent coordination, context passing, stage sequencing — which belongs in markdown and folder structure, not scripts.

Step 5: Anti-Pattern Scan

Check for each anti-pattern. Mark found/clear:

#	Anti-Pattern	Found?
1	Oversized CLAUDE.md (>50 lines)
2	Missing routing table
3	Too many workspaces (5+ from day one)
4	Personality over context (context files describe behavior not work)
5	Stale context (>6 weeks without update on active project)
6	Flat dump (10+ files at one level, no subfolders)
7	Built before used (elaborate system, no work product)
8	Monolithic context loading (all instructions in one file/prompt instead of scoped per workspace)

Step 6: Calculate Structural Metrics

Metric	Formula	Ideal	Value
M1 Depth Ratio	Max folder depth / top-level folders	2-4
M2 File Density	Avg files per folder	3-10
M3 Naming Consistency	% of files following consistent pattern per folder	>80%
M4 Convention Coverage	% of file types with declared naming convention	100%
M5 Context-to-Content	Context files / total content files	5-15%

Step 7: Verify Scores

Before generating the report, cross-check:

• Does each score have specific evidence in the findings? If a criterion scored 1, confirm the evidence exists. If 0, confirm the gap is real.
• Do the anti-pattern flags match the layer scores? (e.g., if #1 "Oversized CLAUDE.md" is found, Layer 0 criterion #2 should score 0)
• Do the metrics align with anti-patterns? (e.g., if M2 File Density is >10, #6 "Flat dump" should be flagged)

Fix any inconsistencies before proceeding.

Step 8: Generate Report

Output the audit report using this structure:

# Folder Architecture Audit: [Project Name]
**Date:** [today]
**Path:** [project path]

## Scores

| Layer | Score | Max | Grade |
|-------|-------|-----|-------|
| Layer 0 (Map) | X | 6 | [A/B/C/F] |
| Layer 1 (Rooms) | X | 6 | [A/B/C/F] |
| Tools | X | 4 | [A/B/C/F or N/A] |
| **Total** | **X** | **16** | **[Grade]** |

Grading: A = 15-16, B = 10-14, C = 6-9, F = 0-5

## Anti-Patterns Found

[List each found anti-pattern with a one-line fix]

## Structural Metrics

| Metric | Value | Status |
|--------|-------|--------|
| M1 Depth Ratio | X | [OK/Warning] |
| M2 File Density | X | [OK/Warning] |
| M3 Naming Consistency | X% | [OK/Warning] |
| M4 Convention Coverage | X% | [OK/Warning] |
| M5 Context-to-Content | X% | [OK/Warning] |

## Top 3 Fixes (Priority Order)

1. [Most impactful fix -- what to do and why]
2. [Second fix]
3. [Third fix]

## Detailed Findings

### Layer 0: The Map
[What exists, what's missing, specific issues]

### Layer 1: The Rooms
[Per-workspace assessment]

### Tools
[Inventory and assessment, or note if premature]

### File Tree Snapshot
[The tree from Step 1]

Step 9: Imprint Structure Rules (Persistent Memory)

After the audit, offer to write structural guardrails into the audited project's CLAUDE.md. This is how the audit "sticks" -- future Claude sessions in that project will follow the structure automatically.

What to write: Append a ## Structure Rules section to the target project's CLAUDE.md (create one if it doesn't exist). Generate the rules from the audit findings -- not a generic template. Only include rules that address actual gaps found.

## Structure Rules
<!-- Generated by folder-audit on [date]. Re-audit to update. -->

### Naming Conventions
[Extracted from audit: the conventions the project SHOULD follow, stated as rules]

### Folder Boundaries
[Which folders exist, what goes in each, what NOT to put where]

### File Placement
- New [type] files go in: [path]
- New [type] files go in: [path]
- Never create files in: [paths] (read-only)

### When Creating New Folders
- Only add a workspace folder when an existing one exceeds 10 files or mixes two unrelated concerns
- Every new workspace folder must include a CONTEXT.md before adding content

Rules for imprinting:

• Always ask the user before writing to their project's CLAUDE.md
• If CLAUDE.md already has a Structure Rules section, replace it (not duplicate)
• Keep the section under 30 lines -- these are guardrails, not documentation
• Include the audit date so staleness is visible
• If the project scored A (15-16), skip imprinting -- the structure is already self-documenting

Step 10: Escalate to Skill Creation (Integration with skill-creator)

If the audit reveals repeated friction (the same type of file is created manually more than twice, or the same process is described in multiple CONTEXT.md files), recommend creating a skill for it.

When to escalate:

• Anti-pattern #7 is clear (no premature tooling) AND repeated manual steps are visible
• A process described in a CONTEXT.md is complex enough (5+ steps) to warrant a SKILL.md
• The user has done the same structural fix across multiple projects

How to escalate: First, check if a skill-creator skill exists: look for .claude/skills/skill-creator/SKILL.md or ~/.claude/skills/skill-creator/SKILL.md. Then tell the user: "This project has friction worth automating: [describe]. Use the skill-creator workflow to build a skill for it." If the skill-creator skill is available, offer to invoke it directly. If not, suggest installing it from anthropics/skills.

Do NOT auto-create skills. Tools should always be a conscious decision, not an audit side-effect.

---

Step 11: ICM Pipeline Audit (Conditional)

When to run: Only if the file tree from Step 1 shows numbered stage folders (e.g., 01_research/, 02_script/, 03_production/) or a stages/ directory. These indicate the project follows Interpretable Context Methodology (ICM) -- a method that uses folder structure as agent orchestration. If no stage folders are found, skip this step entirely and note "ICM: Not detected" in the report.

The base audit (Steps 2-4) covers Layers 0-1 and Tools. This step evaluates Layers 2-4, which are where ICM's pipeline value lives.

11a: Score Stage Contracts (ICM Layer 2)

For each numbered stage folder, check for a CONTEXT.md that functions as a stage contract. Score each criterion 0 or 1, then average across stages:

#	Criterion	Check
1	Stage CONTEXT.md exists	One per numbered stage folder
2	Inputs table present	Lists specific files with Layer 3 (reference) vs Layer 4 (working) labels
3	Process section defined	Clear instructions for what the stage does
4	Outputs section defined	Names the output files and their destination (e.g., -> output/)
5	Single responsibility	Stage does one job -- not research AND scripting in the same stage
6	Scoped context	Stage only references files it needs, not everything in the workspace

Stage Contracts Score: X/6

11b: Score Reference/Working Separation (ICM Layers 3-4)

Check whether the project distinguishes stable reference material from per-run working artifacts:

#	Criterion	Check
1	Reference folders exist	references/, _config/, or shared/ directories present
2	Output folders exist	output/ directory per stage for working artifacts
3	Reference files are stable	Files in reference folders don't change between runs (no dated output mixed in)
4	Output files are per-run	Output folders contain artifacts from pipeline execution, not configuration
5	Stage inputs distinguish types	CONTEXT.md Inputs table labels which files are reference vs working
6	Factory configured once	_config/ or setup/ folder holds workspace-wide settings (voice, style, conventions)

Reference/Working Score: X/6

11c: Score Pipeline Architecture

Check the structural properties of the stage pipeline:

#	Criterion	Check
1	Stages are numbered	Folders use numeric prefixes that encode execution order
2	Handoffs are file-based	Output of stage N is readable as input to stage N+1
3	No stage reads everything	Each stage loads scoped context, not the entire workspace
4	Review gates are possible	Human can inspect and edit output/ before the next stage runs
5	Incremental re-run supported	Can re-run stage N without re-running stages 1 through N-1
6	Pipeline is self-documenting	Reading CONTEXT.md files top to bottom explains the entire workflow

Pipeline Score: X/6

11d: ICM Anti-Patterns

#	Anti-Pattern	Found?
1	Monolithic stage (one stage does everything)
2	Missing output folders (stages write to random locations)
3	Mixed reference and working files (config and output in same folder)
4	No Inputs table (stage CONTEXT.md doesn't specify what to load)
5	Forward dependency (stage N reads from stage N+2 or later)
6	Over-staged (trivial steps split into separate stages unnecessarily)

11e: Calculate ICM Score

Component	Score	Max
Stage Contracts (11a)	X	6
Reference/Working (11b)	X	6
Pipeline Architecture (11c)	X	6
ICM Total	X	18

ICM Grading: A = 16-18, B = 11-15, C = 6-10, F = 0-5

11f: Incorporate into Report

Add an ## ICM Pipeline Assessment section to the report after Structural Metrics:

## ICM Pipeline Assessment

**Detected:** Yes -- [N] stages found
**ICM Score:** X/18 ([Grade])

| Component | Score | Max | Grade |
|-----------|-------|-----|-------|
| Stage Contracts | X | 6 | [A/B/C/F] |
| Reference/Working Separation | X | 6 | [A/B/C/F] |
| Pipeline Architecture | X | 6 | [A/B/C/F] |

### ICM Anti-Patterns Found
[List each found with a one-line fix]

### Stage-by-Stage Assessment
[For each stage: what its contract says, whether inputs/outputs are clean, any issues]

The ICM score is reported separately from the base score (X/16). The two are complementary:

• Base score tells you if the project is well-organized for any AI tool
• ICM score tells you if the pipeline architecture is well-structured for staged workflows

A project can score A on the base audit and F on ICM (good structure, bad pipeline), or vice versa. Both matter.

---

What NOT to Penalize

• No tools on a new project (premature tooling is worse than none)
• Simple projects with only 1-2 workspaces (not every project needs four)
• Missing "What to Avoid" if the project is in early exploration
• Lack of frontmatter if the project doesn't use Obsidian
• No ICM structure on a non-pipeline project (ICM is for sequential staged workflows, not every project)
• Only 2-3 stages in a pipeline (fewer well-defined stages beat many thin ones)
• Missing _config/ folder if reference material lives in stage-local references/ directories (both are valid)

For full methodology background, scoring rationale, and the 60/30/10 rule, see the Playbook: File-tree audit/Playbook - Folder Architecture Evaluation.md