/cleanup-audit

namespace: aiwg
name: cleanup-audit
description: Audit codebase for dead code, unused exports, orphaned files, and stale manifests
commandHint:
  argumentHint: "[--scope <path>] [--type <exports|files|deps|manifests>] [--json] [--fix] [--dry-run]"
  allowedTools: Bash, Read, Write, Glob, Grep
  category: utilities
  orchestration: false
platforms: [all]

Cleanup Audit

Audits the codebase for accumulated dead weight: unused TypeScript/JS exports, orphaned source files, npm dependencies that are declared but never imported, and manifest entries that point to files that do not exist. Every finding carries a confidence rating. Only HIGH confidence findings are safe to auto-fix.

Natural Language Triggers

Users may say:

• "cleanup audit"
• "dead code audit"
• "find dead code"
• "orphan files"
• "unused exports"
• "cleanup analysis"
• "find unused dependencies"
• "stale manifest entries"
• "what can I delete"
• "codebase cleanup"

Parameters

--scope `<path>`

Restrict analysis to a subtree. Default is the full repository root.

aiwg cleanup-audit --scope src/cli/
aiwg cleanup-audit --scope agentic/code/addons/

--type `<exports|files|deps|manifests>`

Run only the specified audit type. Omit to run all four.

| Value | Audits | |-------|--------| | `exports` | TypeScript/JS exports with no importers | | `files` | Source files not referenced by any import or manifest | | `deps` | npm dependencies declared in package.json but not used in code | | `manifests` | Manifest entries (skills, agents) whose source file does not exist |

Multiple types can be combined:

aiwg cleanup-audit --type exports --type deps

--json

Emit findings as newline-delimited JSON to stdout instead of the formatted report. Useful for piping into other tools or CI scripts.

aiwg cleanup-audit --json | jq 'select(.confidence == "HIGH")'

--fix

Auto-apply removals for all HIGH confidence findings. Has no effect without confirmation when any HIGH finding involves a non-trivial deletion (more than 10 lines or a full file). Combine with `--dry-run` to preview what `--fix` would remove.

--dry-run

Show what `--fix` would remove without writing any changes. If used without `--fix`, behaves as the default read-only audit.

Execution Flow

Phase 1: Determine Analysis Scope

1. Parse `--scope` — default to repo root 2. Parse `--type` — default to all four types 3. Parse `--json`, `--fix`, `--dry-run` flags 4. Build file inventory for the scope:

• All `.ts`, `.tsx`, `.js`, `.mjs` files (for exports and files audits)
• `package.json` (for deps audit)
• All `manifest.json` files under `agentic/` (for manifests audit)

5. Communicate scope before analysis begins

**Communicate**:

Cleanup Audit
Scope: {scope}
Types: {types}
Mode: {read-only | fix | dry-run fix}

Building file inventory...
  Source files: {N}
  Manifests: {N}

Phase 2: Analyze Unused Exports

Applies to `--type exports`. Identifies TypeScript and JavaScript named exports that are never imported anywhere in the scope.

**Detection approach**: 1. Glob all source files in scope: `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.mjs` 2. Extract all export declarations: `export function`, `export class`, `export const`, `export type`, `export interface`, `export enum` 3. For each exported identifier, grep all source files for imports of that identifier 4. An export is unused if: zero import matches AND it is not referenced in a manifest entry AND it is not a re-export pattern (`export * from`)

**Confidence rules**:

| Signal | Confidence | |--------|-----------| | Zero imports found across entire scope | HIGH | | Zero imports but identifier is a common name (e.g., `index`, `default`) | MEDIUM | | Zero imports but file is an entry point (`index.ts`, `main.ts`) | LOW | | Export appears in a barrel file (`index.ts` re-export) | LOW — skip |

**Output per finding**:

[UNUSED-EXPORT] HIGH
  File: src/extensions/registry.ts:45
  Export: registerExtension
  Declared: export function registerExtension(ext: Extension): void
  Importers found: 0
  Safe to remove: yes

Phase 3: Detect Orphaned Files

Applies to `--type files`. Identifies source files that are not imported by any other file and not listed in any manifest.

**Detection approach**: 1. Build full file list for scope 2. For each file, check whether its path appears in:

• Any `import` or `require` statement in any other source file
• Any `manifest.json` `scripts` or `path` field
• Any `package.json` `main`, `exports`, or `bin` field

3. A file is orphaned if none of the above references exist

**Confidence rules**:

| Signal | Confidence | |--------|-----------| | No references found anywhere | HIGH | | No references but filename matches common entry point pattern | MEDIUM | | No references but file is in root of package (may be undiscovered entry) | LOW | | Test file with no corresponding source file | MEDIUM (orphaned test) |

**Output per finding**:

[ORPHANED-FILE] HIGH
  File: src/legacy/old-config-reader.ts
  References found: 0 (imports: 0, manifests: 0, package.json: 0)
  Last modified: 2025-11-02
  Safe to remove: yes

Phase 4: Audit Dependencies

Applies to `--type deps`. Finds npm packages declared in `package.json` that have no `import` or `require` usage anywhere in the codebase.

**Detection approach**: 1. Read `dependencies` and `devDependencies` from `package.json` 2. For each package name, grep source files for:

• `import ... from '{package}'`
• `require('{package}')`
• `import('{package}')`
• Scoped sub-path imports: `import ... from '{package}/...'`

3. Also check config files for tool references: `.eslintrc`, `jest.config.*`, `tsconfig.json`

**Confidence rules**:

| Signal | Confidence | |--------|-----------| | No import/require in source, no config reference | HIGH | | No import in source but referenced in a config file | LOW — tool dependency, do not remove | | No import