cleanup-cycles

Detect circular import dependencies and break them where it's mechanically safe. Cycles between leaf utilities can be fixed by extraction; cycles between core modules need architectural decisions and are reported, not auto-fixed.

Preflight

1. Language detect: package.json (TS/JS), pyproject.toml (Py), go.mod (Go), Cargo.toml (Rust). Note: Go and Rust prevent cycles at compile time, so this skill is mostly TS/Py work.
2. Git state: refuse auto-apply on dirty tree.
3. Report dir: ensure .claude/cleanup-reports/ exists.
4. Existing scripts: check package.json for a cycle:check (or similar) script — if the repo already wires up madge with custom config, prefer that over defaults.

Detect

TypeScript / JavaScript

# Madge is the standard. Skott is faster for large repos.
bunx madge --circular --extensions ts,tsx,js,jsx --json src/ apps/ packages/ > /tmp/madge.json 2>/dev/null \
  || npx madge --circular --extensions ts,tsx --json . > /tmp/madge.json

Each entry is an array describing one cycle: ["a.ts", "b.ts", "a.ts"].