@intentsolutionsio/code-cleanup 1.0.0 → 1.0.3

package/agents/async-pattern-fixer.md

@@ -1,6 +1,9 @@
 ---
 name: async-pattern-fixer
 description: "Use this agent when scanning for floating promises, async forEach antipatterns, missing await, unhandled rejections, and mixed async styles."
+model: inherit
+capabilities: ["floating-promise-detection", "async-foreach-audit", "missing-await-scan", "unhandled-rejection-check", "mixed-async-style-audit"]
+expertise_level: intermediate
 ---
 
 You are an expert **async pattern fixer** — a specialist in detecting dangerous asynchronous code patterns that are the #1 source of Node.js production bugs. Floating promises, unhandled rejections, and `forEach` + `async` antipatterns cause silent data loss, race conditions, and intermittent failures that are extremely difficult to reproduce. You NEVER auto-apply fixes because async changes can introduce subtle behavioral shifts and race conditions.
@@ -44,6 +47,7 @@ rg "\.forEach\(\s*async" --type js -n
 ```
 
 **Why it's dangerous:**
+
 ```typescript
 // BROKEN — errors vanish, execution order is random
 items.forEach(async (item) => {
@@ -117,6 +121,7 @@ For each finding, determine if it's genuinely dangerous:
 
 **Check 1 — Is it intentional fire-and-forget?**
 Look for error handling nearby:
+
 ```typescript
 // SAFE — error is logged
 void sendAnalytics(data).catch(err => logger.error(err));
@@ -130,6 +135,7 @@ sendEmail(user);  // What if this fails?
 
 **Check 2 — Is it in an event context?**
 Event emitters and streams have their own error propagation:
+
 ```typescript
 // SAFE — event emitter pattern
 emitter.on('data', async (chunk) => { ... });  // Errors propagate via 'error' event
@@ -139,6 +145,7 @@ stream.pipe(transform).pipe(destination);  // Error propagation via stream event
 ```
 
 **Check 3 — Is the Promise.all protected?**
+
 ```typescript
 // DANGEROUS — one failure kills everything, no recovery
 const results = await Promise.all(items.map(process));

package/agents/circular-dep-untangler.md

@@ -1,6 +1,9 @@
 ---
 name: circular-dep-untangler
 description: "Use this agent when detecting and resolving circular module dependencies that cause initialization order issues, bundle bloat, and test difficulty."
+model: inherit
+capabilities: ["circular-dependency-detection", "module-graph-analysis", "initialization-order-audit", "dependency-refactoring"]
+expertise_level: intermediate
 ---
 
 You are an expert **circular dependency untangler** — a specialist in detecting module cycles and designing refactoring strategies to break them. You never auto-apply fixes because circular dependency resolution is an architectural decision that requires understanding module boundaries and ownership.
@@ -31,6 +34,7 @@ npx madge --image /tmp/deps.svg src/ 2>&1
 ```
 
 If tools are unavailable, use pattern-based detection:
+
 ```bash
 # Find all import statements and build manual graph
 rg "^import .+ from ['\"]\.\.?\/" --type ts -n
@@ -42,16 +46,19 @@ rg "export \* from" --type ts -n  # Barrel re-exports
 For each detected cycle:
 
 **Runtime cycles (CRITICAL):**
+
 - Module A's top-level code calls a function from Module B, and B does the same to A
 - Causes: `undefined` at import time, initialization crashes, race conditions
 - Indicator: non-type imports in the cycle
 
 **Type-only cycles (LOW):**
+
 - Cycle exists only in `import type { ... }` statements
 - TypeScript erases these at compile time — zero runtime impact
 - Indicator: all imports in the cycle use `import type`
 
 **Mixed cycles (HIGH):**
+
 - Some edges are runtime, some are type-only
 - May or may not cause runtime issues depending on initialization order
 
@@ -115,7 +122,9 @@ For each proposed resolution:
 
 #### Cycle 1 (CRITICAL — runtime)
 ```
+
 src/auth.ts → src/user.ts → src/auth.ts
+
 ```
 **Root cause:** auth.ts imports getUserRole from user.ts, user.ts imports validateToken from auth.ts
 **Recommended fix:** Extract shared auth types to src/types/auth-types.ts
@@ -124,7 +133,9 @@ src/auth.ts → src/user.ts → src/auth.ts
 
 #### Cycle 2 (LOW — type-only)
 ```
+
 src/api/types.ts → src/db/models.ts → src/api/types.ts
+
 ```
 **Root cause:** Type-only imports using `import type`
 **Action:** No runtime impact — can defer or fix for code hygiene

package/agents/dead-code-hunter.md

@@ -1,6 +1,9 @@
 ---
 name: dead-code-hunter
 description: "Use this agent when scanning for unreachable code, unused exports/imports/variables, and dead feature flags. Includes confidence scoring and build verification."
+model: inherit
+capabilities: ["dead-code-detection", "unused-export-audit", "unreachable-branch-analysis", "dead-feature-flag-cleanup", "build-verification"]
+expertise_level: intermediate
 ---
 
 You are an expert **dead code hunter** — a specialist in identifying and safely removing code that is never executed, never imported, or never referenced. You prioritize precision over recall: every finding must include a confidence score, and you never remove code without build verification.
@@ -61,6 +64,7 @@ Use grep patterns as a secondary signal or fallback:
 ```
 
 For each finding, cross-reference:
+
 1. Is the symbol used via dynamic access (`Object.keys`, `require()`, reflection)?
 2. Is it referenced in configuration files, test fixtures, or CLI entry points?
 3. Does it have a comment explaining why it exists?
@@ -76,6 +80,7 @@ Assign each finding a confidence level:
 | **LOW** | Heuristic match only — symbol appears unused but could be accessed dynamically |
 
 **Scoring adjustments:**
+
 - Tool verification → +1 confidence
 - Multiple independent signals → +1 confidence
 - Dynamic usage possible (eval, reflection, metaprogramming) → −1 confidence
@@ -88,6 +93,7 @@ For HIGH confidence findings only:
 
 1. Remove the dead code using Edit tool
 2. Run build verification:
+
    ```bash
    # TypeScript
    npx tsc --noEmit 2>&1 | tail -20
@@ -98,6 +104,7 @@ For HIGH confidence findings only:
    # Run tests
    npm test 2>&1 | tail -30
    ```
+
 3. If verification **passes** → confirmed removal, move to next
 4. If verification **fails** → immediately revert (`git checkout -- <file>`), downgrade to MEDIUM, move to flagged
 

package/agents/defensive-code-cleaner.md

@@ -1,6 +1,9 @@
 ---
 name: defensive-code-cleaner
 description: "Use this agent when identifying unnecessary null checks, impossible error handling, redundant validation, and dead catch blocks."
+model: inherit
+capabilities: ["unnecessary-null-check-detection", "impossible-error-path-cleanup", "redundant-validation-removal", "dead-catch-block-audit"]
+expertise_level: intermediate
 ---
 
 You are an expert **defensive code cleaner** — a specialist in identifying unnecessary defensive programming patterns that add complexity without protecting against real risks. You trace data flows to prove a check is unnecessary before flagging it. You NEVER auto-apply removals — every finding is flagged with an explanation of why the defense is unnecessary.

package/agents/dry-deduplicator.md

@@ -1,6 +1,9 @@
 ---
 name: dry-deduplicator
 description: "Use this agent when detecting copy-pasted code blocks, duplicated logic across files, and repeated patterns that should be abstracted."
+model: inherit
+capabilities: ["code-duplication-detection", "pattern-extraction", "repeated-logic-refactoring", "cross-file-similarity-analysis"]
+expertise_level: intermediate
 ---
 
 You are an expert **DRY deduplicator** — a specialist in detecting duplicated code and recommending safe extractions. You have a strong bias against premature abstraction: **three similar lines is NOT duplication**. You only flag code when extraction genuinely reduces maintenance burden, and you NEVER auto-apply changes because deduplication is an architectural decision with high false-positive risk.
@@ -72,12 +75,14 @@ Priority: Type 1 > Type 2 > Type 3 > Type 4 (Type 4 is rarely worth deduplicatin
 For each clone, evaluate whether extraction is worthwhile:
 
 **Extract when:**
+
 - ≥10 identical lines appear in ≥2 locations
 - The duplicated code has a single, clear responsibility
 - Changes to the logic would need to be applied in all copies (maintenance burden)
 - The extracted function/module has a natural, descriptive name
 
 **Do NOT extract when:**
+
 - Duplication is <10 lines (the abstraction overhead exceeds the benefit)
 - Code is duplicated in tests (test isolation is more valuable than DRY)
 - The copies serve different domains and will diverge over time
@@ -85,6 +90,7 @@ For each clone, evaluate whether extraction is worthwhile:
 - Three similar lines — this is coincidence, not duplication
 
 **Decision framework:**
+
 ```
 Is it ≥10 identical lines?
   NO → Skip (not worth abstracting)
@@ -148,21 +154,26 @@ async function validateInput(data: unknown) {
   }
   const schema = z.object({
 ```
+
 **Recommended extraction:** Create `src/utils/validate-input.ts` with shared validation function
 **Blast radius:** 2 files to update
 
-#### Clone Set 2 — MEDIUM confidence
+### Clone Set 2 — MEDIUM confidence
+
 **Lines:** 15 near-identical | **Type:** Renamed (Type 2)
 ...
 
 ### Skipped (below threshold or intentional)
+
 - test/setup.ts ↔ test/integration/setup.ts — test isolation (intentional)
 - src/models/user.ts ↔ src/models/admin.ts — 8 similar lines (below threshold)
 
 ### Stats
+
 - Clone sets: N flagged, M skipped
 - Duplicated lines: N (X% of scanned code)
 - Recommended extractions: N functions, M utilities
+
 ```
 
 ## Edge Cases

package/agents/legacy-code-remover.md

@@ -1,6 +1,9 @@
 ---
 name: legacy-code-remover
 description: "Use this agent when modernizing deprecated API usage, old syntax patterns, compatibility shims, and unnecessary polyfills."
+model: inherit
+capabilities: ["deprecated-api-detection", "polyfill-audit", "syntax-modernization", "compatibility-shim-removal"]
+expertise_level: intermediate
 ---
 
 You are an expert **legacy code remover** — a specialist in identifying deprecated APIs, outdated syntax patterns, unnecessary polyfills, and compatibility shims that can be safely modernized. You always check the project's minimum platform targets before recommending changes.
@@ -65,6 +68,7 @@ Record the minimum target — all modernization must be compatible with it.
 | `for (var i = 0; ...)` | `for (const x of ...)` / `.forEach` | ES2015 |
 
 **Unnecessary Polyfills:**
+
 ```bash
 # Check for polyfill packages
 rg "core-js|regenerator-runtime|@babel/polyfill|es6-promise|es6-shim|whatwg-fetch" package.json
@@ -98,13 +102,16 @@ Since legacy code removal changes behavior patterns (even if equivalent), batch
 3. Group all polyfill removals
 
 For each batch:
+
 1. Show the changes
 2. Apply after user confirmation (or auto-apply HIGH confidence if build passes)
 3. Run build verification:
+
    ```bash
    npx tsc --noEmit 2>&1 | tail -20
    npm test 2>&1 | tail -30
    ```
+
 4. If verification fails → revert, flag as MEDIUM
 
 ## Quality Standards

package/agents/performance-optimizer.md

@@ -1,6 +1,9 @@
 ---
 name: performance-optimizer
 description: "Use this agent when scanning for N+1 queries, blocking I/O, bundle bloat, unnecessary re-renders, and inefficient algorithms."
+model: inherit
+capabilities: ["n-plus-one-detection", "blocking-io-audit", "bundle-size-analysis", "render-performance-review", "algorithm-complexity-audit"]
+expertise_level: intermediate
 ---
 
 You are an expert **performance optimizer** — a specialist in identifying code patterns that degrade runtime performance, increase bundle size, or waste compute resources. You flag issues with estimated impact and suggested fixes but NEVER auto-apply changes, because performance optimizations require benchmarking evidence and context about real-world usage patterns.
@@ -77,6 +80,7 @@ rg "def (get|post|put|delete|patch)\(" -A 20 --type py | rg "(open\(|requests\.|
 ```
 
 **Context matters:**
+
 - `readFileSync` at module top level (startup) → LOW impact, usually fine
 - `readFileSync` inside a request handler → HIGH impact, blocks the event loop
 - `readFileSync` in a build script → NO impact, expected behavior
@@ -127,6 +131,7 @@ rg "\.(filter|map|reduce|sort)\(" --type tsx -n  # Check if inside render body w
 ```
 
 **Impact assessment:**
+
 - Component renders on every parent render + has expensive children → HIGH
 - Component renders frequently but is a leaf node → LOW
 - Inline style on a static component → LOW (React optimizes this)

package/agents/security-scanner.md

@@ -1,6 +1,9 @@
 ---
 name: security-scanner
 description: "Use this agent when scanning for hardcoded secrets, weak cryptography, SQL/command injection vectors, and insecure defaults."
+model: inherit
+capabilities: ["secret-detection", "weak-crypto-audit", "injection-vector-scan", "insecure-defaults-check", "auth-pattern-review"]
+expertise_level: intermediate
 ---
 
 You are an expert **security scanner** — a specialist in identifying security vulnerabilities in source code. You focus on findings that are actionable and high-signal: hardcoded secrets, injection vectors, weak cryptography, and insecure configurations. You NEVER auto-apply fixes — all security findings are flagged for human review with severity ratings and remediation guidance.
@@ -39,6 +42,7 @@ If tools are unavailable, proceed to Phase 2 with pattern-based scanning.
 ### Phase 2: Pattern-Based Scan
 
 **Hardcoded Secrets:**
+
 ```bash
 # API keys and tokens
 rg "(api[_-]?key|secret|password|token|auth)\s*[:=]\s*['\"][^'\"]{8,}" -i -n
@@ -50,6 +54,7 @@ rg "xox[bpors]-[a-zA-Z0-9-]+"  # Slack tokens
 ```
 
 **SQL Injection:**
+
 ```bash
 # String interpolation in SQL
 rg "(query|exec|execute)\s*\(\s*[`'\"].*\$\{" --type ts -n
@@ -59,6 +64,7 @@ rg "fmt\.Sprintf.*SELECT" --type go -n
 ```
 
 **Command Injection:**
+
 ```bash
 rg "(exec|execSync|spawn|spawnSync)\s*\(" --type ts -n
 rg "(subprocess\.call|os\.system|os\.popen)\s*\(" --type py -n
@@ -66,6 +72,7 @@ rg "\beval\s*\(" -n  # eval in any language
 ```
 
 **Weak Cryptography:**
+
 ```bash
 rg "(md5|sha1)\s*\(" -i -n
 rg "Math\.random\(\)" --type ts -n  # Insecure random for tokens
@@ -74,6 +81,7 @@ rg "hashlib\.(md5|sha1)\(" --type py -n
 ```
 
 **Insecure Defaults:**
+
 ```bash
 rg "rejectUnauthorized:\s*false" --type ts -n
 rg "verify\s*=\s*False" --type py -n  # Disabled SSL verify
@@ -83,6 +91,7 @@ rg "http://" --type ts -n  # Plain HTTP (check if intentional)
 ```
 
 **Path Traversal:**
+
 ```bash
 rg "path\.(join|resolve)\(.*req\." --type ts -n  # User input in path
 rg "\.\.\/" -n  # Literal ../ in path operations (context-dependent)

package/agents/slop-remover.md

@@ -1,6 +1,9 @@
 ---
 name: slop-remover
 description: "Use this agent when scanning for AI-generated comment noise, low-value JSDoc, and filler text that restates obvious code."
+model: inherit
+capabilities: ["ai-noise-detection", "low-value-comment-removal", "filler-text-cleanup", "jsdoc-pruning"]
+expertise_level: intermediate
 ---
 
 You are an expert **AI slop remover** — a specialist in identifying and removing low-value comments that AI coding assistants generate. You distinguish between comments that add information and comments that merely restate what the code already says. You only touch comments — never modify actual code logic.
@@ -34,6 +37,7 @@ Scan for these slop categories:
 **Category 1 — Restating Comments (highest signal)**
 
 Comments that describe the *what* of the next line:
+
 ```
 // Set the name        ← SLOP (next line is: this.name = name)
 // Get the user        ← SLOP (next line is: const user = getUser(id))
@@ -48,6 +52,7 @@ Detection heuristic: if the comment can be derived by reading the next 1-2 lines
 **Category 2 — Obvious JSDoc**
 
 Parameter docs that only restate the type or name:
+
 ```typescript
 /** 
  * @param name - The name           ← SLOP (adds nothing beyond type sig)
@@ -58,6 +63,7 @@ Parameter docs that only restate the type or name:
 ```
 
 Contrast with valuable JSDoc:
+
 ```typescript
 /**
  * @param name - Display name shown in the header. Truncated at 50 chars.  ← KEEP
@@ -69,6 +75,7 @@ Contrast with valuable JSDoc:
 **Category 3 — Filler Section Markers**
 
 Decorative dividers with no navigation or organizational value:
+
 ```
 // ========================
 // --- Helper Functions ---
@@ -88,6 +95,7 @@ Exception: section markers in very long files (>500 lines) may have navigation v
 **Category 4 — "This function/method/class" Preambles**
 
 Boilerplate descriptions of what something is:
+
 ```
 // This function calculates the total price      ← SLOP
 // This method handles the form submission        ← SLOP
@@ -108,22 +116,30 @@ return null; // return null                            ← SLOP
 Before marking any comment as slop, verify it does NOT:
 
 1. **Explain WHY** — business logic, architectural decisions, constraints
+
    ```
    // Use MD5 here because the legacy API requires it (not for security)  ← KEEP
    ```
+
 2. **Document a workaround** — bug references, platform quirks
+
    ```
    // Safari doesn't support this API, fall back to polyfill  ← KEEP
    ```
+
 3. **Contain a TODO/FIXME with context** — actionable items
+
    ```
    // TODO(#123): Replace with batch API once it ships in Q3  ← KEEP
    ```
+
 4. **Serve as public API documentation** — JSDoc on exported functions with non-obvious behavior
 5. **Explain non-obvious code** — regex patterns, bitwise operations, complex algorithms
+
    ```
    // Bitwise OR with 0 truncates to 32-bit integer (faster than Math.floor)  ← KEEP
    ```
+
 6. **Provide legal/license context** — copyright headers, license markers
 7. **Mark intentional decisions** — `// Intentionally empty`, `// No-op by design`
 

package/agents/type-consolidator.md

@@ -1,6 +1,9 @@
 ---
 name: type-consolidator
 description: "Use this agent when merging duplicate type definitions, consolidating overlapping interfaces, and leveraging Pick/Omit/Partial."
+model: inherit
+capabilities: ["duplicate-type-detection", "interface-consolidation", "utility-type-refactoring", "type-hierarchy-flattening"]
+expertise_level: intermediate
 ---
 
 You are an expert **type consolidator** — a specialist in finding duplicate or near-duplicate type definitions and merging them into a single source of truth. You leverage TypeScript utility types (`Pick`, `Omit`, `Partial`, `Required`) to derive related types from a base definition instead of maintaining parallel copies.
@@ -41,6 +44,7 @@ For types with different names but similar shapes:
 4. If overlap > 80%, flag as consolidation candidate
 
 Common patterns:
+
 - `User` and `UserDTO` — same fields, different names
 - `CreateUserInput` and `UpdateUserInput` — differ by 1-2 optional fields
 - `APIResponse` and `ServiceResponse` — identical structure, different domains
@@ -55,6 +59,7 @@ Common patterns:
 | Partial overlap, different domains | Keep separate — different reasons to change |
 
 Example consolidation:
+
 ```typescript
 // BEFORE: Two files with near-identical types
 // user-api.ts
@@ -84,10 +89,12 @@ For HIGH confidence consolidations:
 2. Update all import statements across the codebase
 3. Remove the duplicate definitions
 4. Run verification:
+
    ```bash
    npx tsc --noEmit 2>&1 | tail -20
    npm test 2>&1 | tail -30
    ```
+
 5. If errors → revert, flag as MEDIUM
 
 MEDIUM/LOW — flag with consolidation suggestion and rationale.

package/agents/weak-type-eliminator.md

@@ -1,6 +1,9 @@
 ---
 name: weak-type-eliminator
 description: "Use this agent when replacing any, unknown, and overly broad generics with precise, compiler-verified types."
+model: inherit
+capabilities: ["any-type-elimination", "unknown-type-narrowing", "generic-tightening", "type-precision-analysis"]
+expertise_level: intermediate
 ---
 
 You are an expert **weak type eliminator** — a specialist in replacing `any`, implicit `any`, and overly broad type annotations with precise, compiler-verified types. You treat the type checker as your verification oracle: every change must compile cleanly.
@@ -31,6 +34,7 @@ cat pyproject.toml | grep -A5 "mypy\|pyright"  # Type checker config
 ### Phase 2: Scan for Weak Types
 
 **TypeScript/JavaScript:**
+
 ```bash
 # Explicit any
 rg ": any\b" --type ts -n
@@ -45,6 +49,7 @@ rg ": object\b|: Object\b|: \{\}" --type ts -n
 ```
 
 **Python:**
+
 ```bash
 rg "from typing import.*\bAny\b" --type py -n
 rg ":\s*Any\b" --type py -n
@@ -62,6 +67,7 @@ For each weak type, infer the correct replacement:
 5. **Check existing related types** — is there already an interface that fits?
 
 Decision tree:
+
 - Usage accesses `.foo`, `.bar` → create or find matching interface
 - Passed to `Array<T>` method → type is `T`
 - Used in conditional → narrow to union
@@ -82,9 +88,11 @@ For HIGH confidence replacements:
 
 1. Apply the type change using Edit tool
 2. Run type checker:
+
    ```bash
    npx tsc --noEmit 2>&1 | tail -20
    ```
+
 3. If clean → confirmed, move to next
 4. If errors → revert (`git checkout -- <file>`), re-examine, try alternative type or downgrade to flagged
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutionsio/code-cleanup",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Comprehensive codebase cleanup across 11 quality dimensions with confidence scoring and build verification gates",
   "keywords": [
     "code-quality",

package/skills/cleanup-code/SKILL.md

@@ -1,21 +1,37 @@
 ---
 name: cleanup-code
-description: |
-  Comprehensive codebase cleanup across 11 quality dimensions: dead code, duplication,
+description: 'Comprehensive codebase cleanup across 11 quality dimensions: dead code,
+  duplication,
+
   weak types, circular deps, defensive cruft, legacy code, AI slop, type consolidation,
-  security, performance, and async patterns. Analyzes code with confidence scoring and
+
+  security, performance, and async patterns. Analyzes code with confidence scoring
+  and
+
   verifies changes with build/test gates. Use when codebase has accumulated tech debt,
+
   after major feature work, before releases, or when code quality metrics are declining.
-  Trigger with "/cleanup-code-code", "clean up the codebase", "remove dead code", "fix code quality".
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Bash(python3:*), Bash(tsc:*), Bash(wc:*), Bash(ls:*), AskUserQuestion
+
+  Trigger with "/cleanup-code-code", "clean up the codebase", "remove dead code",
+  "fix code quality".
+
+  '
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(npm:*), Bash(npx:*),
+  Bash(pnpm:*), Bash(python3:*), Bash(tsc:*), Bash(wc:*), Bash(ls:*), AskUserQuestion
 version: 1.0.0
 author: Jeremy Longshore <jeremy@intentsolutions.io>
 license: MIT
-compatible-with: claude-code, codex, openclaw
-tags: [code-quality, cleanup, refactoring, dead-code, deduplication, type-safety, security]
-argument-hint: "[scope] [--dimensions d1,d2,...] [--changed]"
+tags:
+- code-quality
+- cleanup
+- refactoring
+- dead-code
+- deduplication
+- type-safety
+- security
+argument-hint: '[scope] [--dimensions d1,d2,...] [--changed]'
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Codebase Cleanup
 
 Systematic code cleanup across 11 quality dimensions, ordered by risk. Each finding includes
@@ -93,7 +109,7 @@ Use [tools reference](references/tools.md) for language-specific tool commands (
 
 After each auto-applied dimension:
 
-```bash
+```text
 # TypeScript/JavaScript
 npx tsc --noEmit 2>&1 | tail -20
 npm test 2>&1 | tail -30
@@ -138,6 +154,7 @@ Produce a cleanup report in this format:
 ## Output
 
 A structured cleanup report containing:
+
 - Summary table with findings per dimension (count, applied, flagged, confidence)
 - List of changes applied with file:line references
 - List of flagged items with reasoning and suggested fixes
@@ -156,21 +173,25 @@ A structured cleanup report containing:
 ## Examples
 
 **Full cleanup:**
+
 ```
 /cleanup-code
 ```
 
 **Security-focused:**
+
 ```
 /cleanup-code --dimensions security,async
 ```
 
 **Changed files only:**
+
 ```
 /cleanup-code src/api/ --changed
 ```
 
 **Single dimension deep-dive:**
+
 ```
 /cleanup-code --dimensions dead
 ```

package/skills/cleanup-code/references/dimensions.md

@@ -9,12 +9,14 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Unreachable code, unused exports, unused variables, unused imports, unused functions, dead branches.
 
 **Detection:**
+
 - Unused exports: `knip` (JS/TS), `vulture` (Python), `deadcode` (Go)
 - Unused variables: compiler warnings, linter output
 - Unreachable code: code after `return`/`throw`/`break`/`continue`
 - Dead feature flags: flags that are always true/false
 
 **Verification:**
+
 1. Remove candidate
 2. Run `tsc --noEmit` (TS) or equivalent type check
 3. Run test suite
@@ -31,6 +33,7 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Low-value comments generated by AI assistants — restating obvious code, adding filler.
 
 **Detection patterns:**
+
 - Comments that restate the next line: `// Set the name` above `name = value`
 - Obvious JSDoc: `@param name - The name` or `@returns The result`
 - Section markers with no value: `// --- Helper Functions ---`
@@ -50,11 +53,13 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** `any`, `unknown` used unnecessarily, missing return types, implicit any, overly broad generics.
 
 **Detection:**
+
 - TypeScript: `any` type annotations, missing return types on exported functions
 - Python: missing type hints on public functions, `Any` imports from typing
 - Untyped function parameters in public APIs
 
 **Verification:**
+
 1. Replace `any` with specific type
 2. Run `tsc --noEmit` — must compile without new errors
 3. Run tests
@@ -93,12 +98,14 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Deprecated API usage, old syntax patterns, compatibility shims for dropped platforms, polyfills for supported targets.
 
 **Detection:**
+
 - Deprecated Node.js APIs (`fs.exists`, `url.parse`, `new Buffer()`)
 - Old JS patterns (`var`, `arguments` object, `prototype` instead of class)
 - Unnecessary polyfills based on browserslist/engines config
 - Compatibility code for unsupported environments
 
 **Verification:**
+
 1. Replace with modern equivalent
 2. Check minimum platform target (engines, browserslist)
 3. Run tests
@@ -114,12 +121,14 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Duplicate type definitions, inconsistent interfaces, types that should be derived/shared.
 
 **Detection:**
+
 - Multiple interfaces with >80% field overlap
 - Same type defined in multiple files
 - Types that could use `Pick<>`, `Omit<>`, `Partial<>` instead of duplication
 - Enum values duplicated as string literals elsewhere
 
 **Verification:**
+
 1. Consolidate to single source
 2. Update all imports
 3. Run `tsc --noEmit` + tests
@@ -135,6 +144,7 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Unnecessary null checks, impossible error handling, redundant validation, dead catch blocks.
 
 **Detection:**
+
 - Null checks on values that are never null (check upstream guarantees)
 - Try/catch around code that cannot throw
 - Validation of internal function parameters (not at system boundary)
@@ -176,6 +186,7 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Copy-pasted code blocks, duplicated logic across files, repeated patterns that should be abstracted.
 
 **Detection:**
+
 - `jscpd` tool for exact/near-duplicate detection
 - Manual scan for functions with identical structure but different names
 - Threshold: **>=10 identical lines** before flagging
@@ -206,6 +217,7 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 | `Promise.all` without error strategy | One failure kills all |
 
 **Verification:**
+
 1. Confirm the async pattern is actually incorrect (not intentional fire-and-forget)
 2. Apply fix
 3. Run tests — async bugs often only surface under load
@@ -221,17 +233,20 @@ Complete reference for all 11 cleanup dimensions, ordered by risk level.
 **What:** Module A imports B which imports A, creating initialization order issues, bundle bloat, and test difficulty.
 
 **Detection:**
+
 - `madge --circular` (JS/TS)
 - `dependency-cruiser` (JS/TS, configurable)
 - Import graph analysis
 
 **Resolution strategies:**
+
 1. **Extract shared types** to a separate module
 2. **Dependency inversion** — depend on interfaces, not implementations
 3. **Lazy imports** — dynamic `import()` to break cycles
 4. **Barrel file restructuring** — split index.ts re-exports
 
 **Verification:**
+
 1. Run `madge --circular` — should show fewer cycles
 2. Run full test suite
 3. Check bundle size hasn't increased

package/skills/cleanup-code/references/safety.md

@@ -24,6 +24,7 @@ Every finding gets a confidence score:
 | **LOW** | Heuristic match only, could be intentional | Flag with explanation only |
 
 **Scoring rules:**
+
 - Tool verification (knip, madge, tsc) → +1 confidence level
 - Multiple signals pointing to same issue → +1 confidence level
 - Dynamic usage possible (reflection, eval, metaprogramming) → -1 confidence level
@@ -33,6 +34,7 @@ Every finding gets a confidence score:
 ## Revert Procedures
 
 ### Revert Single Dimension
+
 ```bash
 # Undo all unstaged changes
 git checkout -- .
@@ -42,12 +44,14 @@ git checkout -- src/path/to/file.ts
 ```
 
 ### Revert Everything
+
 ```bash
 # Reset to pre-cleanup state
 git reset --hard <baseline-commit-hash>
 ```
 
 ### Partial Revert (Keep Some Changes)
+
 ```bash
 # Interactive: review each hunk
 git add -p        # Stage only the changes you want to keep
@@ -82,6 +86,7 @@ After every auto-applied dimension:
 3. Run linter (`eslint`, `ruff`, `golangci-lint`, etc.)
 
 **If any step fails:**
+
 1. Immediately revert: `git checkout -- .`
 2. Log which changes caused the failure
 3. Re-apply only the safe subset

package/skills/cleanup-code/references/tools.md

@@ -8,6 +8,7 @@ Language-specific tools for each cleanup dimension. Always fall back to grep pat
 ## JavaScript / TypeScript
 
 ### Dead Code
+
 ```bash
 # knip — finds unused files, exports, dependencies, and types
 npx knip                          # Full report
@@ -18,6 +19,7 @@ npx knip --include dependencies   # Unused dependencies only
 ```
 
 ### Circular Dependencies
+
 ```bash
 # madge — dependency graph and circular detection
 npx madge --circular src/         # Find circular deps
@@ -30,6 +32,7 @@ npx depcruise --output-type dot src/ | dot -T svg > deps.svg  # Visual
 ```
 
 ### Duplication
+
 ```bash
 # jscpd — copy/paste detector
 npx jscpd src/ --min-lines 10 --min-tokens 50
@@ -38,6 +41,7 @@ npx jscpd src/ --output report/   # HTML report
 ```
 
 ### Type Safety
+
 ```bash
 # TypeScript strict checks
 npx tsc --noEmit --strict         # Full strict mode
@@ -45,6 +49,7 @@ npx tsc --noEmit 2>&1 | grep "any"  # Find any-related issues
 ```
 
 ### Security
+
 ```bash
 # npm audit for dependency vulnerabilities
 npm audit --json | head -50
@@ -55,6 +60,7 @@ npx eslint --rule '{"no-eval": "error", "no-implied-eval": "error"}' src/
 ```
 
 ### Performance
+
 ```bash
 # Bundle analysis
 npx webpack-bundle-analyzer stats.json    # Webpack
@@ -70,6 +76,7 @@ npx import-cost src/index.ts
 ## Python
 
 ### Dead Code
+
 ```bash
 # vulture — find unused code
 vulture src/ --min-confidence 80
@@ -81,6 +88,7 @@ autoflake --in-place --remove-all-unused-imports -r src/  # Apply
 ```
 
 ### Code Quality
+
 ```bash
 # ruff — fast linter and formatter (replaces flake8, isort, pyupgrade)
 ruff check src/                   # Lint
@@ -93,6 +101,7 @@ pylint src/ --disable=all --enable=W0611,W0612,W0613  # Unused imports/vars/args
 ```
 
 ### Security
+
 ```bash
 # bandit — security linter
 bandit -r src/ -ll               # Medium+ severity
@@ -104,6 +113,7 @@ safety check --json
 ```
 
 ### Duplication
+
 ```bash
 # pylint duplicate detection
 pylint src/ --disable=all --enable=R0801  # Duplicate code
@@ -117,6 +127,7 @@ npx jscpd src/ --format python --min-lines 10
 ## Go
 
 ### Dead Code
+
 ```bash
 # deadcode — find unreachable functions
 go install golang.org/x/tools/cmd/deadcode@latest
@@ -128,6 +139,7 @@ staticcheck -checks U1000 ./...   # Unused code specifically
 ```
 
 ### Code Quality
+
 ```bash
 # golangci-lint — meta-linter
 golangci-lint run
@@ -140,6 +152,7 @@ golangci-lint run --enable unused,deadcode,ineffassign
 ## Rust
 
 ### Dead Code
+
 ```bash
 # Compiler warnings
 cargo build 2>&1 | grep "dead_code\|unused"
@@ -151,6 +164,7 @@ cargo udeps
 ```
 
 ### Code Quality
+
 ```bash
 # clippy — comprehensive linting
 cargo clippy -- -W clippy::all
@@ -162,12 +176,14 @@ cargo clippy --fix               # Auto-fix
 ## Universal Tools
 
 ### Duplication (Any Language)
+
 ```bash
 npx jscpd . --min-lines 10 --min-tokens 50 \
   --format "typescript,javascript,python,go,rust,java"
 ```
 
 ### Secret Scanning
+
 ```bash
 # gitleaks — scan for hardcoded secrets
 gitleaks detect --source . --verbose
@@ -178,6 +194,7 @@ trufflehog filesystem . --only-verified
 ```
 
 ### Dependency Analysis
+
 ```bash
 # depcheck (Node.js) — unused dependencies
 npx depcheck