--- name: deep-clean description: "Full-spectrum consolidation of AI agent configuration files. Goes beyond memory-only dream skills: audits and optimizes context files (CLAUDE.md/AGENTS.md/GEMINI.md/.cursorrules), rules, skills, and memory. Detects stale references, dead file paths, duplicated rules, stack mismatches, contradictions, vague directives, and bloated indexes. Works on any repo, any stack, any agent." tags: [memory, maintenance, consolidation, audit, rules, skills, optimization, universal] --- # Deep Clean — Full Configuration Consolidation for AI Coding Agents > Dream cleans your memory. Deep Clean cleans **everything**. Most dream/consolidation skills only touch memory files. Your context files, rules, and skills rot just as fast — stale file paths, rules for a stack you don't use, duplicated directives, vague instructions no agent can follow. Deep Clean fixes all of it. Works with: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Windsurf, and any agent supporting the SKILL.md standard. --- ## What It Does ``` Phase 0: DETECT → Identify which agent is running, resolve paths Phase 1: AUDIT → Scan everything, report problems Phase 2: CONTEXT → Consolidate the main context file Phase 3: RULES → Clean up rules directory Phase 4: SKILLS → Audit installed skills Phase 5: MEMORY → Standard dream consolidation Phase 6: VERIFY → Validate all changes ``` --- ## How to Run Run `/deep-clean` manually, or say "run deep clean" in any session. First run always does a **dry run** (report only, no changes) unless you explicitly say "run deep clean and apply changes". --- ## Phase 0: DETECT AGENT **Goal:** Identify which agent is running and set paths for the rest of the process. ### Agent detection Check which directories exist to determine the active agent: ```bash # Detect agent by directory presence ls .claude/ 2>/dev/null && echo "AGENT: claude-code" ls .cursor/ 2>/dev/null && echo "AGENT: cursor" ls .gemini/ 2>/dev/null && echo "AGENT: gemini-cli" ls .agents/ 2>/dev/null && echo "AGENT: codex/universal" ls .windsurf/ 2>/dev/null && echo "AGENT: windsurf" ls .github/copilot/ 2>/dev/null && echo "AGENT: copilot" ``` ### Set variables for all subsequent phases Based on the detected agent, use these paths throughout: | Variable | Claude Code | Cursor | Gemini CLI | Codex | Windsurf | |----------|------------|--------|------------|-------|----------| | `CONTEXT_FILE` | `CLAUDE.md` | `.cursorrules` | `GEMINI.md` | `AGENTS.md` | `.windsurfrules` | | `RULES_DIR` | `.claude/rules/` | `.cursor/rules/` | `.gemini/rules/` | `.agents/rules/` | `.windsurf/rules/` | | `SKILLS_DIR` | `.claude/skills/` | `.cursor/skills/` | `.gemini/skills/` | `.agents/skills/` | `.windsurf/skills/` | | `MEMORY_DIR` | `~/.claude/projects/*/memory/` | `~/.cursor/projects/*/memory/` | `~/.gemini/memory/` | `~/.agents/memory/` | — | | `ARCHIVE_DIR` | `{RULES_DIR}/_archive/` | `{RULES_DIR}/_archive/` | `{RULES_DIR}/_archive/` | `{RULES_DIR}/_archive/` | `{RULES_DIR}/_archive/` | **Also check for the universal `.agents/` directory** — many agents support it as a fallback: ```bash ls .agents/skills/ 2>/dev/null && echo "UNIVERSAL: .agents/ directory found" ``` If multiple agents are detected, process all of them. Skills in `.agents/skills/` are shared across agents. For the rest of this document, `CONTEXT_FILE`, `RULES_DIR`, `SKILLS_DIR`, and `MEMORY_DIR` refer to the resolved paths from this phase. --- ## Phase 1: AUDIT **Goal:** Build a complete picture of the current configuration state before touching anything. ### Step 1: Inventory all configuration files ```bash # Context files (check all known names) for f in CLAUDE.md AGENTS.md GEMINI.md .cursorrules .windsurfrules; do [ -f "$f" ] && echo "CONTEXT: $f ($(wc -l < "$f") lines)" done # Rules ls ${RULES_DIR}/*.md 2>/dev/null # Skills (SKILL.md files) find ${SKILLS_DIR} -name "SKILL.md" 2>/dev/null # Memory ls ${MEMORY_DIR}/*.md 2>/dev/null ``` ### Step 2: Detect project stack Determine the actual tech stack by checking for marker files. Do NOT rely on what the context file says — check reality: ```bash # Python ls pyproject.toml setup.py requirements.txt Pipfile 2>/dev/null && echo "STACK: python" # Node/JS/TS ls package.json 2>/dev/null && echo "STACK: node" # Rust ls Cargo.toml 2>/dev/null && echo "STACK: rust" # Go ls go.mod 2>/dev/null && echo "STACK: go" # Ruby ls Gemfile 2>/dev/null && echo "STACK: ruby" ``` Also detect frameworks: ```bash # Python frameworks grep -l "fastapi\|flask\|django\|starlette" pyproject.toml setup.py requirements.txt 2>/dev/null # JS frameworks grep -l "react\|vue\|svelte\|next\|nuxt\|angular" package.json 2>/dev/null ``` ### Step 3: Measure sizes For each file, note line count. Flag anything over these thresholds: | File | Warning | Critical | |------|---------|----------| | Context file | > 500 lines | > 1000 lines | | Any single rule | > 100 lines | > 200 lines | | MEMORY.md (index) | > 100 lines | > 200 lines | | Any memory topic file | > 50 lines | > 100 lines | ### Step 4: Cross-reference file paths Read the context file and extract every file path mentioned (anything that looks like `path/to/file` or `app/module/`). Then verify each one exists: ```bash # For each path found in context file, check if it exists # Example: if it mentions "app/auth/router.py" ls app/auth/router.py 2>/dev/null || echo "DEAD PATH: app/auth/router.py" ``` This is the most valuable check. Context file descriptions of project structure drift constantly as code evolves. ### Step 5: Detect duplications Search for the same concept appearing in multiple places: 1. Read the context file — note every rule/convention/pattern described 2. Read each rule file in `RULES_DIR` — note overlaps with the context file 3. Check if the context file repeats things that are in rules files Common duplications: - Git conventions in both context file and a `conventions.md` rule - Testing instructions in both context file and a `testing.md` rule - API conventions in both context file and rules ### Step 6: Detect stack mismatches Compare detected stack (Step 2) against rule files: - A Python/FastAPI project with `svelte.md`, `typescript.md`, `testing.md` (Vitest/Playwright) rules = **mismatch** - A Node project with `python-testing-patterns` skill = **mismatch** - Frontend-only rules in a backend-only project = **mismatch** ### Output: Audit Report Produce a structured report: ```markdown ## Deep Clean Audit Report ### Agent Detected - Agent: [name] - Context file: [CONTEXT_FILE] (X lines) ### Configuration Files - Context file: X lines (WARNING/OK) - Rules: N files, X total lines - Skills: N skills installed - Memory: N topic files ### Stack Detection - Detected: [python, fastapi] from pyproject.toml - Monorepo: no ### Issues Found #### Dead File Paths (X found) - [CONTEXT_FILE] line Y: `path/to/deleted/file.py` — does not exist #### Stack Mismatches (X found) - Rule `svelte.md` — Svelte 5 rules in a Python/FastAPI project #### Duplications (X found) - Git conventions: [CONTEXT_FILE] §Conventions AND rules/conventions.md §Git #### Vague Directives (X found) - [CONTEXT_FILE]: "Write clean code" — no measurable threshold #### Size Warnings - [CONTEXT_FILE]: 1124 lines (CRITICAL, threshold: 1000) #### Stale Memory Entries (X found) - memory/project_foo.md: references file that no longer exists ``` **STOP HERE on first run.** Present the report and ask: "Should I proceed with consolidation, or do you want to review the issues first?" --- ## Phase 2: CONTEXT FILE CONSOLIDATION **Goal:** Make the context file (CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules) accurate, lean, and current. ### Rules 1. **Verify before deleting.** For every file path, table, or endpoint listed, verify it still exists before removing it. If a file was renamed or moved, update the path. If it was deleted, remove the entry. 2. **Structure check.** Run `ls` / `find` on the actual project structure and compare against what the context file describes. Add missing files/modules. Remove deleted ones. 3. **Endpoint check.** If the context file lists API endpoints, verify each one exists in the router files. Remove endpoints that were deleted. Add new ones that aren't listed. 4. **Table check.** If the context file lists database tables/models, verify each one exists in the model files. Update accordingly. 5. **Remove duplications with rules.** If something is thoroughly covered in a rules file, the context file should reference the rule, not duplicate the content. Exception: critical project-specific info that must be seen first. 6. **Convert vague directives to thresholds.** Replace: - "Write clean code" → remove (meaningless) - "Keep functions short" → "Max 50 lines per function" (or whatever the project's actual convention is — check existing code to determine) - "Good test coverage" → "Coverage >= 80% (enforced by CI)" (or check actual CI config) 7. **Never delete architectural decisions.** Decision sections are historical record. Only update if a decision was explicitly reversed. ### How to apply Use the Edit tool to make targeted changes. Never rewrite the entire file — make surgical edits to specific sections. --- ## Phase 3: RULES CONSOLIDATION **Goal:** Remove irrelevant rules, deduplicate, strengthen. ### Step 1: Stack relevance check For each rule file in `RULES_DIR`, determine if it applies to the detected stack: | Rule file | Relevant if | Action if irrelevant | |-----------|-------------|---------------------| | `svelte.md` | package.json has svelte | Archive or delete | | `typescript.md` | package.json has typescript | Archive or delete | | `testing.md` | References project's actual test framework | Rewrite for actual framework | | `accessibility.md` | Project has frontend UI | Archive if backend-only | | `design-workflow.md` | Project has frontend design system | Archive if backend-only | | `python-*.md` | pyproject.toml or requirements.txt exists | Archive if not Python | **Archive = move to `ARCHIVE_DIR` with a note explaining why.** ### Step 2: Deduplication If a rule file repeats content from the context file, decide which is the authority: - Project-specific details → keep in context file - General conventions → keep in rules file, remove from context file ### Step 3: Strengthen vague rules Apply numeric thresholds where possible. Check the project's actual linter config, CI config, and existing code to determine realistic thresholds: ```bash # Check existing linter config for thresholds cat pyproject.toml | grep -A20 "\[tool.ruff" 2>/dev/null cat .eslintrc* eslint.config.* 2>/dev/null cat pytest.ini pyproject.toml | grep -A10 "\[tool.pytest" 2>/dev/null ``` --- ## Phase 4: SKILLS AUDIT **Goal:** Identify unused, redundant, or oversized skills. ### Step 1: List all installed skills ```bash # Check both agent-specific and universal skill directories find ${SKILLS_DIR} -name "SKILL.md" -exec bash -c 'echo "$(wc -l < "$1") $1"' _ {} \; find .agents/skills -name "SKILL.md" -exec bash -c 'echo "$(wc -l < "$1") $1"' _ {} \; 2>/dev/null ``` ### Step 2: Relevance check For each skill, check: 1. Does the skill's domain match the project stack? 2. Is the skill duplicating another skill's functionality? 3. Is the skill relevant to this type of project (backend/frontend/fullstack)? ### Step 3: Size check Skills with large `references/` directories consume context when triggered. Flag skills where total reference content exceeds 5000 lines. ### Actions - **Irrelevant skills**: Recommend removal - **Redundant skills**: Recommend keeping the better one - **Oversized skills**: Recommend trimming references **Do not auto-remove skills.** Always recommend and let the user decide. --- ## Phase 5: MEMORY CONSOLIDATION **Goal:** Standard dream — clean, dedupe, and index memory files. ### Step 1: Read all memory files ```bash ls ${MEMORY_DIR}/*.md 2>/dev/null ``` Read MEMORY.md (index) and each topic file. If no memory directory is found, skip this phase. ### Step 2: Check for issues - **Stale entries**: Memory references files/functions that no longer exist - **Relative dates**: "yesterday", "last week" without an anchor date - **Duplicates**: Same fact in multiple files - **Contradictions**: File A says X, File B says not-X - **Orphaned files**: Topic files not referenced in MEMORY.md - **Dead index entries**: MEMORY.md references files that don't exist ### Step 3: Fix issues 1. Convert relative dates to absolute: check file modification time for context 2. Merge duplicate entries — keep the most recent, note the merge 3. Resolve contradictions — keep the most recent, remove the old 4. Remove orphaned files or add them to MEMORY.md 5. Remove dead index entries ### Step 4: Enforce limits - MEMORY.md index: max 200 lines - Each topic file: keep focused, one topic per file - Each index entry: one line, under 150 characters --- ## Phase 6: VERIFY **Goal:** Confirm all changes are valid. ### Checks 1. **No broken references**: Every file path in the context file still exists 2. **MEMORY.md under 200 lines**: `wc -l` on MEMORY.md 3. **No duplicate rules**: Grep for identical sentences across context file and rules 4. **Rules match stack**: No frontend rules in backend projects (or vice versa) 5. **No relative dates in memory**: `grep -rn "yesterday\|last week\|last month\|tomorrow" ${MEMORY_DIR} 2>/dev/null` ### Summary Print a consolidation summary: ```markdown ## Deep Clean Summary ### Changes Applied - [CONTEXT_FILE]: X dead paths removed, Y entries updated, Z lines reduced - Rules: N files archived (stack mismatch), M directives strengthened - Skills: N flagged for removal (user decision pending) - Memory: X duplicates merged, Y contradictions resolved, Z stale entries removed ### Before/After | File | Before | After | Delta | |------|--------|-------|-------| | [CONTEXT_FILE] | X lines | Y lines | -Z | | rules/ total | X lines | Y lines | -Z | | memory/ total | X lines | Y lines | -Z | ### Remaining Issues (manual review needed) - Skill `frontend-design`: recommend removal (Y/N?) - ... ``` --- ## Safety - **First run is always dry run** unless user explicitly requests changes - **Back up before modifying**: Copy context file and rules before first edit - **Never delete architectural decisions** from context files - **Never auto-remove skills** — only recommend - **Preserve memory entries** — move to archive rather than delete - **Git-friendly**: All changes are made via Edit tool, reviewable in `git diff` --- ## Auto-trigger (optional, Claude Code only) To run automatically every 7 days, add a Stop hook. See `clean-hook.sh` and `should-clean.sh` in this skill's directory for details.