simplify-code/README.md

simplify-code

A portable Agent Skill that simplifies a codebase safely and incrementally from any agent runtime — Claude Code, GitHub Copilot (CLI / VS Code), pi, Codex CLI, Gemini CLI, Cursor.

It finds complexity, nesting, duplication, magic numbers, dead code, long functions, duplicated enums/types, near-duplicate functions, and reinvented utilities — detecting mechanically with bundled engines (ast-grep, cpd, scc, biome, ruff), ranking the biggest wins, and writing one actionable report for an agent to act on. It does not modify code.

Two analysis passes (both report-only)

• Pass A — structural (per-node): nesting, magic numbers, booleans, params, dead branches — each emitted as a finding with a concrete action.
• Pass B — consolidation & anti-pattern analysis (cross-file, report-only): duplicate enums/types, near-duplicate functions, untyped repeated DTOs, reinvented utilities, plus lint/metrics enrichment. Targets the measured AI failure mode (duplication up, reuse down). Every candidate is model-judged with anti-over-abstraction (AHA) guardrails; nothing is auto-merged. See references/CONSOLIDATION.md and references/ANTIPATTERNS.md.

All engines are bundled single static binaries (ast-grep, cpd, scc, biome, ruff — bin/manifest.json); nothing is assumed about the target environment, and Pass B never writes into the project.

Report-only — it never modifies your code

This skill does not edit, fix, or format anything. It analyzes and writes two files under simplify/: findings.json (machine-actionable ledger) and a ranked *-report.md action queue. The calling agent reads the report and acts on it; the skill has no apply/verify/modify step and no modes.

Why it stays fast and cheap

• Codebase out of context. Bundled binaries find + rank candidates mechanically; the model reads only flagged spans, and is used only to judge cross-file candidates.
• Actionable findings. Each finding carries an explicit action (what to change) and verify (how to confirm after acting) so a finding is independently executable.
• Resumable. The acting agent flips a status field in findings.json; reruns keep finished work.

Design constraints (deliberate)

• No Python, no .sh/.ps1/make. The engine is one cross-platform binary (identical CLI on Win/macOS/Linux); the command sequence lives in SKILL.md and the agent issues OS-appropriate invocations. Detection rules are declarative YAML.
• Self-contained. ast-grep is bundled per platform under bin/ (see bin/README.md); no install step, works offline.
• JSON end-to-end for the ledger (matches ast-grep --json); the only YAML is ast-grep's own mandated rule/config format.
• Framework-agnostic. Build/test/lint commands are inferred by the model once and cached in the ledger — never hardcoded.

Layout

SKILL.md            entry point (read this first)
sgconfig.yml        ast-grep project config → rules/
bin/                bundled ast-grep binary per platform
rules/<lang>/       ast-grep rule packs (detection + suggested fixes for the report)
references/         PATTERNS · DETECTION · OPTIMIZATION · PORTABILITY
assets/             ledger.schema.json
fixtures/           messy sample code for validating the skill

Install

Copy or symlink this directory into your runtime's skills location — see references/PORTABILITY.md for per-OS, per-runtime instructions. Then ask your agent to "simplify this codebase" / "find duplication" — it writes simplify/findings.json + a report, which the agent (or you) then acts on.

Languages

JS/TS, Python, Go, Rust, Java today (ast-grep supports 20+; add a rule pack to extend). Svelte/SvelteKit is supported specially (no built-in grammar): detection leans on the project's own Svelte tooling + model-driven refactors with SvelteKit guardrails, plus an opt-in ast-grep grammar (one-command build → sgconfig.svelte.yml) that injects JS/TS rules into <script> blocks and adds template rules — see references/SVELTE.md.

License: MIT.