From 3f6f642f6bd7bf706041907c3f57cb19746968e6 Mon Sep 17 00:00:00 2001
From: Giancarmine Salucci <giancarmine@gmail.com>
Date: Tue, 23 Jun 2026 00:54:40 +0200
Subject: [PATCH] feat: portable cross-runtime code-simplification skill

ast-grep-driven detection + ranking into a JSON ledger, two-track apply
(deterministic autofix + model span-edits), configurable report/apply modes.
Rule packs for JS/TS, Python, Go, Rust, Java; Svelte/SvelteKit support via
project tooling + opt-in grammar. Runtime-neutral SKILL.md (Agent Skills spec).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitattributes                    |   4 +
 .gitignore                        |  13 ++
 README.md                         |  59 ++++++++
 SKILL.md                          | 233 ++++++++++++++++++++++++++++++
 assets/ledger.schema.json         |  90 ++++++++++++
 bin/README.md                     |  40 +++++
 bin/VERSION                       |   1 +
 bin/checksums.txt                 |   1 +
 fixtures/EXAMPLE-findings.json    | 146 +++++++++++++++++++
 fixtures/go/messy.go              |  23 +++
 fixtures/java/Messy.java          |  23 +++
 fixtures/js/messy.js              |  21 +++
 fixtures/py/messy.py              |  24 +++
 fixtures/rust/messy.rs            |  21 +++
 fixtures/ts/messy.ts              |  40 +++++
 references/DETECTION.md           |  95 ++++++++++++
 references/OPTIMIZATION.md        |  54 +++++++
 references/PATTERNS.md            | 107 ++++++++++++++
 references/PORTABILITY.md         |  77 ++++++++++
 references/SVELTE.md              | 102 +++++++++++++
 rules/go/complexity.yml           |  38 +++++
 rules/go/simplify.yml             |  19 +++
 rules/java/complexity.yml         |  38 +++++
 rules/java/simplify.yml           |  18 +++
 rules/javascript/complexity.yml   |  38 +++++
 rules/javascript/simplify.yml     |  41 ++++++
 rules/manifest.json               |  54 +++++++
 rules/python/complexity.yml       |  43 ++++++
 rules/python/simplify.yml         |  49 +++++++
 rules/rust/complexity.yml         |  39 +++++
 rules/rust/simplify.yml           |  18 +++
 rules/svelte/runes.yml.example    |  53 +++++++
 rules/svelte/template.yml.example |  21 +++
 rules/typescript/complexity.yml   |  46 ++++++
 rules/typescript/simplify.yml     |  47 ++++++
 sgconfig.yml                      |  40 +++++
 36 files changed, 1776 insertions(+)
 create mode 100644 .gitattributes
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 SKILL.md
 create mode 100644 assets/ledger.schema.json
 create mode 100644 bin/README.md
 create mode 100644 bin/VERSION
 create mode 100644 bin/checksums.txt
 create mode 100644 fixtures/EXAMPLE-findings.json
 create mode 100644 fixtures/go/messy.go
 create mode 100644 fixtures/java/Messy.java
 create mode 100644 fixtures/js/messy.js
 create mode 100644 fixtures/py/messy.py
 create mode 100644 fixtures/rust/messy.rs
 create mode 100644 fixtures/ts/messy.ts
 create mode 100644 references/DETECTION.md
 create mode 100644 references/OPTIMIZATION.md
 create mode 100644 references/PATTERNS.md
 create mode 100644 references/PORTABILITY.md
 create mode 100644 references/SVELTE.md
 create mode 100644 rules/go/complexity.yml
 create mode 100644 rules/go/simplify.yml
 create mode 100644 rules/java/complexity.yml
 create mode 100644 rules/java/simplify.yml
 create mode 100644 rules/javascript/complexity.yml
 create mode 100644 rules/javascript/simplify.yml
 create mode 100644 rules/manifest.json
 create mode 100644 rules/python/complexity.yml
 create mode 100644 rules/python/simplify.yml
 create mode 100644 rules/rust/complexity.yml
 create mode 100644 rules/rust/simplify.yml
 create mode 100644 rules/svelte/runes.yml.example
 create mode 100644 rules/svelte/template.yml.example
 create mode 100644 rules/typescript/complexity.yml
 create mode 100644 rules/typescript/simplify.yml
 create mode 100644 sgconfig.yml

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..ade629c
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,4 @@
+# Engine binaries are gitignored (see .gitignore). If you re-enable committing them
+# and have git-lfs, uncomment to track them with LFS:
+# bin/**/ast-grep filter=lfs diff=lfs merge=lfs -text
+# bin/**/ast-grep.exe filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..aacafc0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,13 @@
+# Bundled engine binaries are large (~50 MB) and platform-specific. They are NOT
+# committed (no git-lfs here); they are fetched on first run or at packaging time.
+# See bin/README.md. The local working tree keeps them so installed skills run offline.
+bin/**/ast-grep
+bin/**/ast-grep.exe
+grammars/
+
+# Skill runtime output (per-project ledger / reports), never part of the skill.
+simplify/
+
+# OS / editor noise
+.DS_Store
+*.swp
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2d6a3cd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# simplify-code
+
+A portable [Agent Skill](https://agentskills.io/specification) 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 reduces complexity, nesting, duplication, magic numbers, dead code, and long
+functions **while preserving behavior** — detecting opportunities mechanically with a
+bundled [`ast-grep`](https://ast-grep.github.io/) engine, ranking the biggest wins,
+and applying fixes one at a time with build/test verification.
+
+## Why it stays fast and cheap
+
+- **Codebase out of context.** `ast-grep` finds + ranks candidates mechanically; the
+  model reads only the flagged spans, from a small JSON ledger on disk.
+- **Two-track apply.** Mechanical fixes are applied by deterministic `ast-grep`
+  autofix rules (zero model tokens, zero hallucination); only genuinely semantic
+  refactors go to the model.
+- **Resumable.** Progress is a `status` field in `simplify/findings.json`; reruns skip
+  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 (detect + autofix)
+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" (preview) or "simplify and apply".
+
+## 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, with an
+opt-in ast-grep grammar path — see `references/SVELTE.md`.
+
+License: MIT.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..69ad3d7
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,233 @@
+---
+name: simplify-code
+description: >-
+  Simplify and refactor a codebase safely and incrementally — reduce complexity,
+  nesting, duplication, magic numbers, dead code, and long functions while
+  preserving behavior. Detects opportunities mechanically with ast-grep, ranks
+  the biggest wins, and applies fixes one at a time with build/test verification.
+  Use when asked to simplify, clean up, refactor, reduce complexity, remove dead
+  code, or improve readability of code in any language (JS/TS, Python, Go, Rust,
+  Java, Svelte/SvelteKit, and more).
+license: MIT
+metadata:
+  author: simplify-code
+  version: "0.1.0"
+allowed-tools: Read Edit Write Bash(git:*) Bash(ast-grep:*) Bash(sg:*)
+---
+
+# Simplify Code
+
+Systematic, behavior-preserving code simplification that runs the same way in any
+agent runtime (Claude Code, GitHub Copilot CLI/VS Code, pi, Codex, Gemini CLI).
+
+The skill keeps the codebase **out of your context**: a bundled `ast-grep` binary
+finds and ranks candidates mechanically, you assemble a small JSON **ledger** on
+disk, and then you touch only the flagged spans — one fix at a time, verified.
+
+> Throughout, "run" means execute via your shell/terminal tool; "read the span"
+> means read only the indicated line range; "edit" means your native file-edit
+> tool. These map to whatever each runtime calls them.
+
+## When to use
+
+Activate when the user wants to simplify / clean up / refactor / de-duplicate /
+reduce complexity / remove dead code / improve readability — for a file, a
+directory, or a whole repository.
+
+## How it works (overview)
+
+```
+detect (ast-grep, 0 tokens) → assemble ledger (cheap) → infer build/test/lint (once)
+   → baseline gate → apply top findings (Track A: ast-grep autofix | Track B: span edit)
+   → verify each change → report
+```
+
+Two modes (default **report**):
+- **report** — dry-run: produce proposed diffs + `simplification-report.md`, change nothing.
+- **apply** — edit in place, re-running build/test after every change.
+
+Pick mode from the user's words ("dry run / preview / report" → report; "apply / do it
+/ fix it" → apply). If unclear, do **report** first and offer to apply.
+
+---
+
+## Step 0 — Locate the ast-grep engine
+
+`ast-grep` is the only required tool and is **bundled** with this skill — no install.
+Detect platform and pick the binary; fall back gracefully.
+
+1. Determine `<os>-<arch>`:
+   - OS: Linux→`linux`, macOS/Darwin→`darwin`, Windows→`win32`.
+   - Arch: x86_64/amd64→`x64`, arm64/aarch64→`arm64`.
+2. Use `<skill-dir>/bin/<os>-<arch>/ast-grep` (`ast-grep.exe` on Windows). Make it
+   executable if needed (`chmod +x` on Unix).
+3. **If that file is missing** (fresh clone — binaries aren't committed), fetch the pinned
+   release once into that dir, then verify against `bin/checksums.txt`:
+   the version is in `bin/VERSION`; releases are at
+   `https://github.com/ast-grep/ast-grep/releases/download/<VERSION>/app-<triple>.zip`
+   (triples: `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`,
+   `x86_64-apple-darwin`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc`). Or just use a
+   PATH `ast-grep` / install it (next step).
+5. Verify: run `ast-grep --version`.
+6. **Fallbacks**, in order, if the bundled binary won't run (rare arch, or macOS
+   Gatekeeper / Windows SmartScreen blocking an unsigned binary):
+   a. an `ast-grep` (or `sg`) already on `PATH`;
+   b. if none, tell the user the one-line install for their OS
+      (`npm i -g @ast-grep/cli` · `brew install ast-grep` · `cargo install ast-grep`
+      · `scoop install ast-grep`) and offer to continue with **LLM-heuristic
+      detection** (grep + reading suspicious files) — slower, less precise.
+
+Refer to the binary below as `AST_GREP`.
+
+## Step 1 — Scope the candidate files
+
+Never touch files git ignores.
+
+- In a git repo: candidates = `git ls-files` plus
+  `git ls-files --others --exclude-standard` (tracked + untracked-but-unignored).
+- Not a git repo: ask the user which paths to include before doing anything.
+- Honor any path the user named (a file, dir, or glob) by intersecting with the above.
+
+## Step 2 — Detect (mechanical, ~0 tokens)
+
+Run ast-grep with this skill's bundled rules and emit JSON:
+
+```
+AST_GREP scan -c <skill-dir>/sgconfig.yml --json <paths>
+```
+
+- `sgconfig.yml` points at `rules/` (per-language packs: detection + autofix).
+- Rules cover: redundant boolean/ternary, magic numbers, dead/unreachable code,
+  deep nesting, long parameter lists, simplifiable APIs, duplicate-ish patterns.
+- **Optional enrichment, only if already installed** (never install, never block on
+  absence): `scc`, `gocyclo`, `staticcheck`, `cargo clippy`, `knip`, `jscpd`, `pmd`.
+  Fold their output into the ledger as extra `signal`/findings.
+
+See `references/DETECTION.md` for rule authoring and the full enrichment matrix.
+
+**Svelte / SvelteKit (`.svelte`):** ast-grep has no built-in Svelte grammar, so handle
+these specially (full guide: `references/SVELTE.md`):
+- Detect primarily with the project's own Svelte tooling **if present** — run
+  `svelte-check` (machine output), the project's `eslint` (eslint-plugin-svelte) on
+  `**/*.svelte`, and/or `svelte/compiler` warnings; fold results into the ledger.
+- Optionally, if a tree-sitter-svelte grammar has been built and enabled in
+  `sgconfig.yml`, the TS/JS packs apply to `<script>` blocks via injection.
+- Otherwise do model-driven refactors (runes migration, store→`$state`, etc.) — and
+  **obey the SvelteKit guardrails in `references/SVELTE.md`** (never break
+  `+page`/`+layout`/`load`/form-action conventions). Verify with `svelte-check` too.
+
+## Step 3 — Assemble the ledger (`findings.json`)
+
+Read ast-grep's JSON and write `simplify/findings.json` (create the `simplify/` dir).
+Use a **cheap/fast model** for this step if your runtime lets you choose one.
+
+For each match, compute and record a finding (schema: `assets/ledger.schema.json`):
+- location (`file`, `start_line`, `end_line`), `lang`, `detector` (rule id),
+- `signal` (metric values — e.g. nesting depth, param count, function length derived
+  from the match range; plus any enrichment metrics),
+- `suggested_pattern` (from the catalog in `references/PATTERNS.md`),
+- `apply_track`: `ast-grep` if the rule carries a `fix:`, else `llm`,
+- `difficulty`: `mechanical` (has fix) | `semantic` (needs judgment) | `hard` (multi-file/risky),
+- `confidence` (0–1), `severity` (0–100), `status: pending`.
+
+Rank biggest-win-first:
+`severity = max(0, cyclomatic-10)*(lines/20) + unused_params*10 + dup_blocks*50 + ast_grep_hits*5`
+(tune as needed; see DETECTION.md).
+
+Write a top-level `config:` block too (filled in Step 4) so everything lives in one file.
+
+**Resumability:** if `findings.json` already exists, load it and process only
+`status: pending` items — do not re-scan-and-overwrite completed work.
+
+## Step 4 — Infer build / test / lint commands (once, cached)
+
+These are project-specific and must NOT be hardcoded. Infer them from the project's
+manifests/structure, then cache in `findings.json` → `config:`:
+
+```json
+"config": {
+  "build":  "<cmd or null>",
+  "test":   "<cmd or null>",
+  "lint":   "<cmd or null>",
+  "format": "<cmd or null>",
+  "detected_from": "package.json|pyproject.toml|go.mod|Cargo.toml|pom.xml|Makefile|...",
+  "runtime": "node|python|go|rust|java|...",
+  "inferred_at": "<commit-or-marker>"
+}
+```
+
+Hints by ecosystem (verify they exist before trusting them):
+- Node: `package.json` scripts (`build`/`test`/`lint`), pnpm/yarn/npm.
+- Python: `pyproject.toml`/`tox.ini`/`pytest.ini` → `pytest`; ruff/black for lint/format.
+- Go: `go build ./...`, `go test ./...`, `gofmt`, `go vet`.
+- Rust: `cargo build`, `cargo test`, `cargo fmt`, `cargo clippy`.
+- Java: Maven (`mvn -q test`) / Gradle (`./gradlew test`).
+
+Re-infer only if `config` is missing or the manifest changed. If a command can't be
+found, set it `null` and tell the user; treat a missing test command as "no automatic
+verification available" (be more conservative; prefer report mode).
+
+## Step 5 — Baseline gate
+
+Run `config.build` then `config.test`. If either FAILS, **STOP** and report — never
+simplify on top of a red baseline. (If both are `null`, warn and proceed cautiously.)
+
+## Step 6 — Apply (process the ledger top-down)
+
+Take the top-N `pending` findings (start small, e.g. N=10; respect any user/token budget).
+For each, **one change at a time**:
+
+### Track A — mechanical (ast-grep autofix, 0 LLM tokens)
+The rule carries a `fix:`. 
+- **apply mode:** `AST_GREP scan -c sgconfig.yml --update-all` (or `--rule <file>` to
+  scope to one rule). 
+- **report mode:** capture the diff with `AST_GREP scan -c sgconfig.yml --json` /
+  dry-run; do not write.
+
+### Track B — semantic (LLM span edit)
+- Read **only** the flagged span (± a few context lines), not the whole file.
+- Apply the catalog pattern (`references/PATTERNS.md`) via your native edit tool
+  (a search/replace style edit — keep the surrounding code identical). For a large
+  rewrite, replace the whole function/block.
+- Keep behavior unchanged. Do not invent abstractions. One pattern per step.
+
+### After each change → verify
+Run cached `config.build` + `config.test` (+ `config.lint` if cheap):
+- **pass** → mark finding `status: applied`, record `model_used`; continue.
+- **fail** → revert that one change, mark `status: failed` with the diagnostic, then
+  retry up to 3× with more context. Still failing → if your runtime allows a stronger
+  model, escalate it for that finding; otherwise mark `failed` and move on.
+
+Never batch unrelated changes into a single verify step. Update `findings.json` as you go.
+
+## Step 7 — Report
+
+Write `simplify/simplification-report.md`:
+- summary (counts by status, by pattern, by language),
+- per-finding: file, pattern, track, result, and (report mode) the proposed diff /
+  (apply mode) the applied diff,
+- anything skipped/failed with the reason and rollback guidance,
+- remaining `pending` findings for a future run.
+
+In **report mode** also emit proposed changes as `simplify/patches/*.patch` (e.g.
+`git diff` of a throwaway application, or ast-grep diffs) so a human can apply them.
+
+---
+
+## Guardrails
+
+- Never modify git-ignored files. Never change public/observable behavior unless the
+  user explicitly asks. No speculative abstractions, no drive-by rewrites.
+- Prefer Track A (deterministic) over Track B whenever a vetted `fix:` exists.
+- If classification is uncertain, treat the finding as Track B + rely on the verify gate.
+- Keep your own context lean: work from the ledger and span reads, not whole files.
+- Stop and ask if the baseline is red, the repo isn't under version control, or a
+  change would alter an API/exported symbol.
+
+## Optimization & portability
+
+- Token/model tactics (span reads, cheap-model triage, optional sub-agent fan-out,
+  cache-friendly prefixes): `references/OPTIMIZATION.md`.
+- Per-runtime install locations, invocation, and model-override notes:
+  `references/PORTABILITY.md`.
+- Svelte / SvelteKit handling, the opt-in grammar, and guardrails: `references/SVELTE.md`.
diff --git a/assets/ledger.schema.json b/assets/ledger.schema.json
new file mode 100644
index 0000000..353efea
--- /dev/null
+++ b/assets/ledger.schema.json
@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/simplify-code/ledger.schema.json",
+  "title": "simplify-code ledger (findings.json)",
+  "description": "One file holding the inferred project commands (config) and the ranked, resumable list of simplification findings. Written by the assembly step (SKILL.md Step 3) and updated as fixes are applied.",
+  "type": "object",
+  "required": ["config", "findings"],
+  "properties": {
+    "config": {
+      "type": "object",
+      "description": "Project build/test/lint/format commands, inferred ONCE by the model and cached. Re-inferred only if missing or the manifest changed.",
+      "properties": {
+        "build":   { "type": ["string", "null"] },
+        "test":    { "type": ["string", "null"] },
+        "lint":    { "type": ["string", "null"] },
+        "format":  { "type": ["string", "null"] },
+        "detected_from": { "type": "string", "description": "e.g. package.json | pyproject.toml | go.mod | Cargo.toml | pom.xml | Makefile" },
+        "runtime": { "type": "string", "description": "node | python | go | rust | java | ..." },
+        "inferred_at": { "type": "string", "description": "commit hash or marker used to detect manifest changes" }
+      }
+    },
+    "engine": {
+      "type": "object",
+      "description": "Which detection engine produced the findings, for reproducibility.",
+      "properties": {
+        "ast_grep_version": { "type": "string" },
+        "binary": { "type": "string", "description": "bundled <os>-<arch> | PATH | none(llm-fallback)" },
+        "enrichment": { "type": "array", "items": { "type": "string" }, "description": "optional tools used, e.g. scc, knip, svelte-check" }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "file", "start_line", "end_line", "lang", "detector", "apply_track", "difficulty", "severity", "status"],
+        "properties": {
+          "id": { "type": "string", "description": "stable id, e.g. f0001" },
+          "file": { "type": "string" },
+          "start_line": { "type": "integer", "minimum": 1 },
+          "end_line": { "type": "integer", "minimum": 1 },
+          "lang": { "type": "string" },
+          "detector": { "type": "string", "description": "ast-grep ruleId, or enrichment tool id (svelte-check, scc, ...)" },
+          "suggested_pattern": { "type": "string", "description": "catalog key from references/PATTERNS.md" },
+          "signal": {
+            "type": "object",
+            "description": "metric values backing the finding (any subset)",
+            "properties": {
+              "cyclomatic": { "type": "number" },
+              "lines": { "type": "number" },
+              "nesting": { "type": "number" },
+              "params": { "type": "number" },
+              "dup_blocks": { "type": "number" }
+            }
+          },
+          "apply_track": { "enum": ["ast-grep", "llm"] },
+          "difficulty": { "enum": ["mechanical", "semantic", "hard"] },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "severity": { "type": "number", "minimum": 0, "maximum": 100, "description": "ranking score; biggest-win-first" },
+          "status": { "enum": ["pending", "applied", "skipped", "failed"] },
+          "model_used": { "type": ["string", "null"] },
+          "notes": { "type": "string" }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "config": {
+        "build": "npm run build", "test": "npm test", "lint": "npm run lint", "format": "npx prettier -w .",
+        "detected_from": "package.json", "runtime": "node", "inferred_at": "a1b2c3d"
+      },
+      "engine": { "ast_grep_version": "0.44.0", "binary": "linux-x64", "enrichment": ["knip"] },
+      "findings": [
+        {
+          "id": "f0001", "file": "src/cart.ts", "start_line": 4, "end_line": 4, "lang": "typescript",
+          "detector": "ts-prefer-includes", "suggested_pattern": "prefer-includes",
+          "apply_track": "ast-grep", "difficulty": "mechanical", "confidence": 0.99,
+          "severity": 5, "status": "pending", "model_used": null, "notes": ""
+        },
+        {
+          "id": "f0002", "file": "src/cart.ts", "start_line": 20, "end_line": 38, "lang": "typescript",
+          "detector": "ts-deep-nesting", "suggested_pattern": "guard-clauses",
+          "signal": { "nesting": 3, "lines": 18 },
+          "apply_track": "llm", "difficulty": "semantic", "confidence": 0.7,
+          "severity": 38, "status": "pending", "model_used": null, "notes": ""
+        }
+      ]
+    }
+  ]
+}
diff --git a/bin/README.md b/bin/README.md
new file mode 100644
index 0000000..333c1d7
--- /dev/null
+++ b/bin/README.md
@@ -0,0 +1,40 @@
+# Bundled `ast-grep` binaries
+
+The skill ships a self-contained `ast-grep` binary per platform so it works with
+**no install step and offline**. `SKILL.md` (Step 0) detects `<os>-<arch>` and runs
+the matching binary; if it can't (rare arch, or macOS Gatekeeper / Windows
+SmartScreen blocking an unsigned binary) it falls back to a PATH `ast-grep`, then to
+LLM-heuristic detection.
+
+## Layout
+
+```
+bin/
+├── linux-x64/ast-grep
+├── linux-arm64/ast-grep
+├── darwin-x64/ast-grep
+├── darwin-arm64/ast-grep
+└── win32-x64/ast-grep.exe
+```
+
+## Populating / updating the binaries (packaging step)
+
+These are not source; they are fetched at package time from the official releases
+(MIT-licensed): https://github.com/ast-grep/ast-grep/releases
+
+For each platform, download the release archive, extract the `ast-grep` binary into
+the matching `bin/<os>-<arch>/` directory, and record its SHA-256 in `checksums.txt`.
+Pin a single upstream version across all platforms (see `VERSION`).
+
+> Size note: the `ast-grep` binary is ~50 MB per platform. Because of that (and no
+> git-lfs here), the binaries are **gitignored, not committed** (`.gitignore`). The skill
+> is still self-contained *once installed* — the local working tree keeps the binary, so a
+> copied/symlinked skill runs offline. On a **fresh clone**, `SKILL.md` Step 0 fetches the
+> pinned release (`VERSION`) into `bin/<os>-<arch>/` on first use and verifies it against
+> `checksums.txt`. To pre-bundle for distribution instead, commit the binaries with
+> git-lfs (see `.gitattributes`) or ship per-platform packages.
+
+## Verification
+
+`SKILL.md` may verify a binary against `checksums.txt` before first use. Never run a
+binary whose checksum does not match.
diff --git a/bin/VERSION b/bin/VERSION
new file mode 100644
index 0000000..a8ab6c9
--- /dev/null
+++ b/bin/VERSION
@@ -0,0 +1 @@
+0.44.0
diff --git a/bin/checksums.txt b/bin/checksums.txt
new file mode 100644
index 0000000..b809357
--- /dev/null
+++ b/bin/checksums.txt
@@ -0,0 +1 @@
+e08eea52023724e309c7104ca32c41fb9b205d976d3b3e6e681753b2394a3069  linux-x64/ast-grep
diff --git a/fixtures/EXAMPLE-findings.json b/fixtures/EXAMPLE-findings.json
new file mode 100644
index 0000000..2e2594b
--- /dev/null
+++ b/fixtures/EXAMPLE-findings.json
@@ -0,0 +1,146 @@
+{
+  "config": {
+    "build": "npm run build",
+    "test": "npm test",
+    "lint": "npm run lint",
+    "format": "npx prettier -w .",
+    "detected_from": "package.json",
+    "runtime": "node",
+    "inferred_at": "<commit>"
+  },
+  "engine": {
+    "ast_grep_version": "0.44.0",
+    "binary": "linux-x64",
+    "enrichment": []
+  },
+  "findings": [
+    {
+      "id": "f0006",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 31,
+      "end_line": 36,
+      "lang": "typescript",
+      "detector": "ts-deep-nesting",
+      "suggested_pattern": "guard-clauses",
+      "apply_track": "llm",
+      "difficulty": "semantic",
+      "confidence": 0.7,
+      "severity": 20.3,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0008",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 33,
+      "end_line": 35,
+      "lang": "typescript",
+      "detector": "ts-deep-nesting",
+      "suggested_pattern": "guard-clauses",
+      "apply_track": "llm",
+      "difficulty": "semantic",
+      "confidence": 0.7,
+      "severity": 20.1,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0005",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 20,
+      "end_line": 27,
+      "lang": "typescript",
+      "detector": "ts-long-param-list",
+      "suggested_pattern": "parameter-object",
+      "apply_track": "llm",
+      "difficulty": "semantic",
+      "confidence": 0.7,
+      "severity": 10.4,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0001",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 4,
+      "end_line": 4,
+      "lang": "typescript",
+      "detector": "ts-prefer-includes",
+      "suggested_pattern": "prefer-includes",
+      "apply_track": "ast-grep",
+      "difficulty": "mechanical",
+      "confidence": 0.95,
+      "severity": 5,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0002",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 8,
+      "end_line": 8,
+      "lang": "typescript",
+      "detector": "ts-prefer-not-includes",
+      "suggested_pattern": "prefer-includes",
+      "apply_track": "ast-grep",
+      "difficulty": "mechanical",
+      "confidence": 0.95,
+      "severity": 5,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0003",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 12,
+      "end_line": 12,
+      "lang": "typescript",
+      "detector": "ts-ternary-to-boolean",
+      "suggested_pattern": "simplify-boolean",
+      "apply_track": "ast-grep",
+      "difficulty": "mechanical",
+      "confidence": 0.95,
+      "severity": 5,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0004",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 16,
+      "end_line": 16,
+      "lang": "typescript",
+      "detector": "ts-ternary-negate",
+      "suggested_pattern": "simplify-boolean",
+      "apply_track": "ast-grep",
+      "difficulty": "mechanical",
+      "confidence": 0.95,
+      "severity": 5,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    },
+    {
+      "id": "f0007",
+      "file": "fixtures/ts/messy.ts",
+      "start_line": 33,
+      "end_line": 33,
+      "lang": "typescript",
+      "detector": "ts-magic-number",
+      "suggested_pattern": "magic-number",
+      "apply_track": "llm",
+      "difficulty": "semantic",
+      "confidence": 0.7,
+      "severity": 3.0,
+      "status": "pending",
+      "model_used": null,
+      "notes": ""
+    }
+  ]
+}
diff --git a/fixtures/go/messy.go b/fixtures/go/messy.go
new file mode 100644
index 0000000..aaae34d
--- /dev/null
+++ b/fixtures/go/messy.go
@@ -0,0 +1,23 @@
+package fixtures
+
+func decide(ready bool, blocked bool) bool {
+	if ready == true {
+		return false
+	}
+	if blocked == false {
+		return true
+	}
+	return false
+}
+
+func price(base int, qty int, taxRate int, discount int, shipping int, region string) int {
+	total := base * qty
+	if qty > 0 {
+		if region == "EU" {
+			if taxRate > 0 {
+				total = total + total*5000
+			}
+		}
+	}
+	return total + shipping
+}
diff --git a/fixtures/java/Messy.java b/fixtures/java/Messy.java
new file mode 100644
index 0000000..b4a69a9
--- /dev/null
+++ b/fixtures/java/Messy.java
@@ -0,0 +1,23 @@
+public class Messy {
+    public boolean decide(boolean ready, boolean blocked) {
+        if (ready == true) {
+            return false;
+        }
+        if (blocked == false) {
+            return true;
+        }
+        return false;
+    }
+
+    public int price(int base, int qty, int taxRate, int discount, int shipping, String region) {
+        int total = base * qty;
+        if (qty > 0) {
+            if (region.equals("EU")) {
+                if (taxRate > 0) {
+                    total = total + total * 5000;
+                }
+            }
+        }
+        return total + shipping;
+    }
+}
diff --git a/fixtures/js/messy.js b/fixtures/js/messy.js
new file mode 100644
index 0000000..a6321b7
--- /dev/null
+++ b/fixtures/js/messy.js
@@ -0,0 +1,21 @@
+// Intentionally messy JavaScript for validating simplify-code rules.
+
+function hasTag(tags, tag) {
+  return tags.indexOf(tag) !== -1;
+}
+
+function isReady(flag) {
+  return flag ? true : false;
+}
+
+function price(base, qty, taxRate, discount, shipping, region) {
+  let total = base * qty;
+  if (qty > 0) {
+    if (region === "EU") {
+      if (taxRate > 0) {
+        total = total + total * taxRate;
+      }
+    }
+  }
+  return total + shipping;
+}
diff --git a/fixtures/py/messy.py b/fixtures/py/messy.py
new file mode 100644
index 0000000..4696092
--- /dev/null
+++ b/fixtures/py/messy.py
@@ -0,0 +1,24 @@
+"""Intentionally messy Python for validating simplify-code rules."""
+
+
+def get_user(user, cache):
+    if user == None:
+        return None
+    if not user in cache:
+        return None
+    return cache[user]
+
+
+def is_empty(items):
+    return len(items) == 0
+
+
+def price(base, qty, tax_rate, discount, shipping, region):
+    total = base * qty
+    if qty > 0:
+        if region == "EU":
+            if tax_rate > 0:
+                total = total + total * tax_rate
+                if total > 5000:
+                    total = total - discount
+    return total + shipping
diff --git a/fixtures/rust/messy.rs b/fixtures/rust/messy.rs
new file mode 100644
index 0000000..298ff62
--- /dev/null
+++ b/fixtures/rust/messy.rs
@@ -0,0 +1,21 @@
+pub fn decide(ready: bool, blocked: bool) -> bool {
+    if ready == true {
+        return false;
+    }
+    if blocked == false {
+        return true;
+    }
+    false
+}
+
+pub fn price(base: i64, qty: i64, tax_rate: i64, discount: i64, shipping: i64) -> i64 {
+    let mut total = base * qty;
+    if qty > 0 {
+        if tax_rate > 0 {
+            if total > 5000 {
+                total = total - discount;
+            }
+        }
+    }
+    total + shipping
+}
diff --git a/fixtures/ts/messy.ts b/fixtures/ts/messy.ts
new file mode 100644
index 0000000..4fc94ac
--- /dev/null
+++ b/fixtures/ts/messy.ts
@@ -0,0 +1,40 @@
+// Intentionally messy TypeScript for validating simplify-code rules.
+
+export function hasTag(tags: string[], tag: string): boolean {
+  return tags.indexOf(tag) !== -1;
+}
+
+export function missingTag(tags: string[], tag: string): boolean {
+  return tags.indexOf(tag) === -1;
+}
+
+export function isReady(flag: boolean): boolean {
+  return flag ? true : false;
+}
+
+export function isBlocked(flag: boolean): boolean {
+  return flag ? false : true;
+}
+
+// Deeply nested + magic numbers + long parameter list
+export function price(
+  base: number,
+  qty: number,
+  taxRate: number,
+  discount: number,
+  shipping: number,
+  region: string,
+): number {
+  let total = base * qty;
+  if (qty > 0) {
+    if (region === "EU") {
+      if (taxRate > 0) {
+        total = total + total * taxRate;
+        if (total > 5000) {
+          total = total - discount;
+        }
+      }
+    }
+  }
+  return total + shipping;
+}
diff --git a/references/DETECTION.md b/references/DETECTION.md
new file mode 100644
index 0000000..482fa03
--- /dev/null
+++ b/references/DETECTION.md
@@ -0,0 +1,95 @@
+# Detection, ranking & the ledger
+
+How candidates are found mechanically, scored, classified, and recorded — so the model
+works from a small file on disk instead of the whole codebase.
+
+## The scan command
+
+```
+AST_GREP scan -c <skill-dir>/sgconfig.yml --json=compact <paths>
+```
+
+- `<paths>` is the git-visible candidate set (SKILL.md Step 1).
+- `--json=compact` emits one JSON array of matches. Use `--json=stream` for very large
+  repos (newline-delimited; process incrementally).
+
+### JSON fields you can rely on
+
+Each match object includes (ast-grep 0.44):
+- `ruleId` — the rule that matched (join key to `rules/manifest.json`).
+- `file` — path.
+- `range.start.line` / `range.end.line` — **0-indexed**; add 1 for human/editor lines.
+- `range.start.column` / `range.end.column`, plus byte offsets.
+- `lines` — the matched source text.
+- `metaVariables` — captured `$VARS` (single + `$$$` multi).
+- `severity`, `message`, `note`.
+
+> `metadata` set in a rule is **not** emitted in JSON. That is why classification lives
+> in `rules/manifest.json`, keyed by `ruleId` — read it once during assembly.
+
+## Classification (`rules/manifest.json`)
+
+For every `ruleId`, the manifest gives:
+- `pattern` — catalog key (`references/PATTERNS.md`),
+- `track` — `ast-grep` (rule carries a `fix:`, deterministic Track A) or `llm` (Track B),
+- `difficulty` — `mechanical | semantic | hard`,
+- `weight` — contribution to the ranking score,
+- optional `requires` — a capability gate (e.g. `svelte-grammar`).
+
+If a `ruleId` is missing from the manifest, default to `track: llm`,
+`difficulty: semantic`, `weight: 5`, and note it.
+
+## Metrics that aren't single nodes
+
+ast-grep matches nodes, not measurements. Derive these during assembly:
+- **Function length** — from a finding's `range` (end − start lines), or from enrichment.
+- **Param count** — the `*-long-param-list` rules fire at ≥5 via `nthChild`; exact count
+  comes from the matched signature text or enrichment.
+- **Nesting depth** — the `*-deep-nesting` rules fire at ≥3 nested conditionals.
+- **Cyclomatic complexity** — only via enrichment tools (below); otherwise approximate
+  from nesting + branch counts.
+
+## Optional enrichment tools (only if already installed)
+
+Never install these; use them when present and fold output into `signal`/extra findings.
+
+| Language | Metrics | Dead code | Duplication |
+|----------|---------|-----------|-------------|
+| any      | `scc` (size), `lizard` (CC, multi-lang) | — | `jscpd` |
+| JS/TS    | `eslint` (+`sonarjs` cognitive complexity) | `knip` | `jscpd` |
+| Python   | `radon` (CC/MI) | `vulture` | `jscpd` |
+| Go       | `gocyclo` | `staticcheck` | — |
+| Rust     | `rust-code-analysis`, `cargo clippy` | `cargo-machete` (deps) | — |
+| Java     | `PMD` (CC + dead + CPD) | PMD | PMD CPD |
+| Svelte   | `svelte-check`, `eslint-plugin-svelte`, `svelte/compiler` warnings | eslint | — |
+
+## Ranking (biggest-win-first)
+
+Per finding, base score from the manifest `weight`, scaled by available metrics:
+
+```
+severity = manifest.weight
+         + max(0, cyclomatic - 10) * (lines / 20)
+         + unused_params * 10
+         + dup_blocks * 50
+```
+
+Clamp to 0–100. Process highest first, capped at a small top-N per run (default 10) plus
+any user/token budget. Tune the weights against `fixtures/`.
+
+## The ledger (`simplify/findings.json`)
+
+Full schema + example: `../assets/ledger.schema.json`. Two blocks: `config` (Step 4) and
+`findings`. Key rule: **status is the source of truth** — on rerun, load the ledger and
+process only `status: pending`; never blindly re-scan-and-overwrite.
+
+## Authoring new rules
+
+- One YAML doc per rule (separate docs in a file with `---`). Required: `id`, `language`,
+  `rule`. Add `fix` only when the rewrite is behavior-preserving for *all* operand types
+  (→ `track: ast-grep`); otherwise leave it out (→ `track: llm`).
+- **Quote any `pattern` containing `:` or `?`** (e.g. ternaries) or YAML mis-parses it.
+- Prefer relational rules (`inside`/`has` + `stopBy: end`, `nthChild`) for structural
+  smells; prefer `pattern` for concrete rewrites.
+- Add a matching entry to `rules/manifest.json` and a fixture under `fixtures/`.
+- Validate: `AST_GREP scan -c sgconfig.yml --json=compact fixtures/<lang>/...`.
diff --git a/references/OPTIMIZATION.md b/references/OPTIMIZATION.md
new file mode 100644
index 0000000..51f7b3f
--- /dev/null
+++ b/references/OPTIMIZATION.md
@@ -0,0 +1,54 @@
+# Token & model optimization
+
+Make the model do the least possible work, and only the hard part. These are layered;
+apply as many as your runtime supports. All are optional accelerators — the skill is
+correct without any of them.
+
+## 1. Push work out of the model
+- Detection is the bundled `ast-grep` binary — **zero model tokens**.
+- Mechanical fixes are Track A (`ast-grep --update-all`) — the model never reads them.
+- Goal: the model only ever touches `difficulty: semantic | hard` findings.
+
+## 2. Span-scoped reads
+Never read a whole file to make one edit. From the ledger you already have
+`file` + `start_line`/`end_line`; read only that range plus a few context lines (~95% fewer
+read tokens on large files). The codebase enters context only as flagged spans.
+
+## 3. Cheap-model steps
+Use a small/fast model (Haiku / GPT-5-mini / Gemini Flash) for:
+- **ledger assembly** (Step 3) — mechanical JSON→JSON join with the manifest;
+- **classification / triage** — mechanical vs semantic, confidence;
+- **verification reading** — interpreting build/test output (pass/fail + which finding).
+
+## 4. Model tiering (capability-detected)
+- Semantic apply → a mid model (Sonnet).
+- `hard` / multi-file / low-confidence / post-retry → escalate to a frontier model (Opus)
+  **only then**. Confidence-based cascading typically cuts cost ~50–85% at ~95% quality.
+- **How to route**, by runtime:
+  - Claude Code — sub-agents with a per-agent `model:` override.
+  - pi — provider-agnostic; pick the model per sub-agent/step.
+  - Copilot / others without per-step model choice — run on the invoked model and use
+    `confidence`/`difficulty` to order work and decide attempt-vs-defer (defer `hard` ones
+    to report mode for a human).
+
+## 5. Optional sub-agent fan-out
+On runtimes with sub-agents (Claude Code, pi), process independent findings/files in
+parallel isolated contexts; each returns a compact JSON status row to the parent. Keeps the
+orchestrator context clean. Falls back to a sequential ledger loop everywhere else. Keep
+each change's verify gate inside its own sub-agent so failures isolate cleanly.
+
+## 6. Cache-friendly prefix
+Keep static context (the pattern catalog, the manifest, the ledger summary) front-loaded
+and stable so the runtime's prompt cache hits; append per-finding dynamic context (the
+span) after it. Don't reorder the stable prefix between findings.
+
+## 7. Resumability = the cheapest rerun
+`findings.json` `status` is the source of truth. On rerun, load it and process only
+`pending` items — an interrupted or repeated run skips finished work (~80–90% saving).
+Don't re-scan-and-overwrite a ledger that still has `pending` work.
+
+## Rough budget intuition
+detect = free (binary). assembly + triage = cheap model, one pass over compact JSON.
+apply = one mid-model span edit per semantic finding + one verify read. Mechanical findings
+= free. So cost scales with the number of *semantic* findings you choose to process
+(top-N), not with repo size.
diff --git a/references/PATTERNS.md b/references/PATTERNS.md
new file mode 100644
index 0000000..adbad7a
--- /dev/null
+++ b/references/PATTERNS.md
@@ -0,0 +1,107 @@
+# Simplification pattern catalog
+
+The refactoring patterns this skill applies. Each entry: what it is, which rule(s) detect
+it, the apply track, a before/after, and **when NOT to apply**. Behavior preservation is
+non-negotiable — when in doubt, downgrade to Track B (model edit) and rely on the verify
+gate.
+
+`suggested_pattern` keys in the ledger map to the headings here.
+
+---
+
+## simplify-boolean — Track A (mechanical)
+Redundant boolean expressions.
+Detectors: `ts/js-ternary-to-boolean`, `*-ternary-negate`, `go/rs/java-eq-true`, `*-eq-false`.
+
+```diff
+- return flag ? true : false;      // → Boolean(flag)
+- return flag ? false : true;      // → !(flag)
+- if (ready == true) {}            // (typed langs) → if (ready)
+- if (blocked == false) {}         // → if (!blocked)
+```
+**Not when:** in dynamically-typed JS/TS where `x === true` is intentional strict-equality
+on a non-boolean (we only rewrite the `? true : false` form there, which is always safe;
+`== true` rewrites are restricted to statically-typed Go/Rust/Java).
+
+## prefer-includes — Track A (mechanical)
+Detectors: `ts/js-prefer-includes`, `*-prefer-not-includes`.
+
+```diff
+- if (tags.indexOf(tag) !== -1) {}   // → tags.includes(tag)
+- if (tags.indexOf(tag) === -1) {}   // → !tags.includes(tag)
+```
+**Not when:** the index value is used afterwards, or `NaN` membership matters (`includes`
+finds `NaN`, `indexOf` doesn't).
+
+## identity-compare / membership / truthiness — Track A (Python)
+Detectors: `py-is-none`, `py-is-not-none`, `py-not-in`, `py-not-is`, `py-empty-seq-falsy`.
+
+```diff
+- if x == None:        # → x is None
+- if x != None:        # → x is not None
+- if not x in seq:     # → x not in seq
+- if not x is y:       # → x is not y
+- if len(items) == 0:  # → not items   (sequences only)
+```
+**Not when:** `__eq__` is overloaded (for the None rewrites), or the value may be a number
+where `len()` doesn't apply / `0` is meaningful (for the truthiness rewrite — the rule
+notes this).
+
+## guard-clauses — Track B (semantic)
+Detector: `*-deep-nesting` (≥3 nested conditionals).
+Flatten with early returns / continues instead of deep nesting.
+
+```diff
+- function f(x) {
+-   if (a) { if (b) { if (c) { doThing(); } } }
+- }
++ function f(x) {
++   if (!a) return;
++   if (!b) return;
++   if (!c) return;
++   doThing();
++ }
+```
+**Not when:** branches have `else` side effects, cleanup must run on all paths, or
+inverting conditions changes short-circuit evaluation. Read the whole block first.
+
+## parameter-object — Track B (semantic)
+Detector: `*-long-param-list` (≥5 params).
+Group related params into an object/struct/dataclass.
+**Not when:** params are unrelated, the function is a hot path where an allocation matters,
+or it's a public API signature you may not change.
+
+## magic-number — Track B (semantic)
+Detector: `*-magic-number`.
+Replace an unexplained literal with a named constant.
+
+```diff
+- if (total > 5000) {}
++ const FREE_SHIPPING_THRESHOLD = 5000;
++ if (total > FREE_SHIPPING_THRESHOLD) {}
+```
+**Not when:** the literal is self-evident (array index, `0`/`1`), or already adjacent to a
+clear name.
+
+## extract-method — Track B (semantic)
+No single detector — triggered by long functions (length from ledger `signal.lines`) or
+repeated blocks. Pull a cohesive chunk into a well-named helper.
+**Not when:** the chunk shares many locals (would need a long param list — reconsider), or
+extraction would hurt readability.
+
+## remove-dead-code — Track B (semantic), or tool-applied
+From enrichment (`knip`, `vulture`, `staticcheck`, `cargo-machete`) or unreachable-branch
+rules. Delete unused exports/vars/imports/branches.
+**Not when:** the symbol is part of a public API, used via reflection/dynamic import, or
+referenced only in files outside the scanned set — verify first.
+
+## svelte-event-property — Track B (Svelte; mechanical-ish)
+Detector: `svelte-event-directive-to-property` (opt-in grammar). `on:click={h}` →
+`onclick={h}`. See `SVELTE.md` for the full Svelte catalog and SvelteKit guardrails.
+
+---
+
+### Applying a pattern (Track B)
+1. Read only the finding's span (± a few context lines).
+2. Apply exactly one pattern with the native edit tool; keep surrounding code byte-identical.
+3. Verify (build/test). Pass → `applied`; fail → revert, retry ≤3, then escalate/defer.
diff --git a/references/PORTABILITY.md b/references/PORTABILITY.md
new file mode 100644
index 0000000..2ffb82e
--- /dev/null
+++ b/references/PORTABILITY.md
@@ -0,0 +1,77 @@
+# Portability: install & run in any runtime
+
+One `SKILL.md` (Agent Skills spec) runs across runtimes. Differences are only in *where*
+the skill lives and *how* you invoke/route models.
+
+## Install locations
+
+Copy or symlink the whole `simplify-code/` directory into a skills location:
+
+| Runtime | Personal (all projects) | Project-local |
+|---------|-------------------------|---------------|
+| Claude Code | `~/.claude/skills/simplify-code` | `.claude/skills/simplify-code` |
+| Copilot (CLI/VS Code) | `~/.copilot/skills/` or `~/.agents/skills/` | `.github/skills/` or `.claude/skills/` or `.agents/skills/` |
+| pi | `~/.pi/agent/skills/simplify-code` | (project skills dir) |
+| Codex / Gemini CLI / Cursor | per each tool's skills dir | per each tool |
+
+### Per-OS copy/symlink (no `make`, no script)
+
+```bash
+# Unix (symlink keeps it updated in place)
+ln -s "$PWD/simplify-code" ~/.claude/skills/simplify-code
+# or copy
+cp -R simplify-code ~/.claude/skills/
+```
+```powershell
+# Windows (PowerShell)
+Copy-Item -Recurse simplify-code $HOME\.claude\skills\
+# or a junction:
+New-Item -ItemType Junction -Path $HOME\.claude\skills\simplify-code -Target (Resolve-Path .\simplify-code)
+```
+
+> If you tracked `bin/**` with git-lfs, run `git lfs pull` before copying so the binaries
+> are real files, not LFS pointers.
+
+## Invoking
+
+Most runtimes auto-activate a skill from its `description` when you ask to "simplify /
+clean up / refactor / reduce complexity / remove dead code". You can also name it
+explicitly (e.g. `/simplify-code` where slash-skills are supported, or "use the
+simplify-code skill").
+
+Choose a mode in plain words: "preview / dry-run / report" → **report**; "apply / fix it /
+do it" → **apply**. Default is report.
+
+## The bundled engine
+
+`SKILL.md` Step 0 detects `<os>-<arch>` and runs `bin/<os>-<arch>/ast-grep`
+(`ast-grep.exe` on Windows). On Unix it may need `chmod +x`. If a bundled binary is
+blocked (macOS Gatekeeper / Windows SmartScreen for an unsigned binary) or missing for a
+rare arch, it falls back to a PATH `ast-grep`, then to LLM-heuristic detection.
+
+## Model routing per runtime
+
+See `OPTIMIZATION.md` §4. Summary:
+- **Claude Code** — sub-agents accept a `model:` override; route triage→Haiku,
+  apply→Sonnet, hard→Opus.
+- **pi** — provider-agnostic; set the model per step/sub-agent.
+- **Copilot / others** — no per-step model pick; run on the invoked model and use the
+  ledger's `confidence`/`difficulty` to order and defer.
+
+## `allowed-tools` caveat
+
+The frontmatter `allowed-tools` is honored by the Claude Code CLI, **silently ignored by
+the Agent SDK**, and partially supported elsewhere. Treat it as an optimization, never as a
+correctness/security boundary. The skill only needs: shell (git + ast-grep), file read,
+and file edit/write.
+
+## Capability degradation summary
+
+| Capability absent | Effect |
+|-------------------|--------|
+| bundled binary won't run | PATH ast-grep → LLM-heuristic detection |
+| per-step model override | run on invoked model; order/defer via ledger |
+| sub-agents | sequential ledger loop |
+| enrichment tools | ast-grep-only signals |
+| Svelte grammar | project Svelte tooling + model refactors (see SVELTE.md) |
+| not a git repo | ask the user for include paths before any change |
diff --git a/references/SVELTE.md b/references/SVELTE.md
new file mode 100644
index 0000000..505f0a8
--- /dev/null
+++ b/references/SVELTE.md
@@ -0,0 +1,102 @@
+# Svelte / SvelteKit support
+
+Svelte is compiler-based and `.svelte` files mix three languages — an HTML-like
+template, one or more `<script>` / `<script lang="ts">` blocks, and `<style>`. That
+means generic structural tooling needs special handling. This skill supports Svelte in
+two layers; use whichever the environment allows.
+
+## Detection strategy (in priority order)
+
+### 1. Project's own Svelte tooling — PRIMARY, zero extra setup
+Any SvelteKit project already ships the best Svelte analyzers. Use them as enrichment
+when present (run via the project's package manager; never install them yourself):
+
+| Tool | Catches | Invoke |
+|------|---------|--------|
+| `svelte-check` | type errors, component validation, machine-readable diagnostics | `npx svelte-check --output machine` |
+| `eslint-plugin-svelte` | 100+ rules: store misuse, reactive-statement bugs, SvelteKit violations, a11y | project's `eslint` run on `**/*.svelte` |
+| `svelte/compiler` warnings | reactivity (`non_reactive_update`, `state_referenced_locally`), a11y (`a11y_*`), deprecations, unused CSS, perf (`perf_*`) | `compile()`/`parse()` (needs Node) |
+
+Fold their output into the ledger as findings (`detector: "svelte-check"` etc.),
+classified `track: llm` unless the tool offers a safe autofix (`eslint --fix`), in which
+case `track: ast-grep`-equivalent (tool-applied) is fine.
+
+> These run only if already in the project (Node + the dev deps). Their absence never
+> blocks a run — fall back to layer 2 / model-driven refactors.
+
+**Recipe — `svelte-check` → ledger (works today, no grammar):**
+```
+# machine output is one diagnostic per line: TYPE filepath line col code message
+npx --no-install svelte-check --output machine 2>/dev/null
+```
+For each `ERROR`/`WARNING` line, add a finding: `detector: "svelte-check"`,
+`file`/`start_line` from the diagnostic, `apply_track: llm`, `difficulty: semantic`
+(or `mechanical` if the code is `eslint --fix`-able), `status: pending`. Same idea for
+`eslint -f json **/*.svelte` (use `messages[].ruleId/line`, `fix` present ⇒ mechanical).
+
+### 2. ast-grep structural rules — OPT-IN (requires building a grammar)
+ast-grep has no built-in Svelte grammar. To run structural rules on `.svelte`:
+
+1. Build `tree-sitter-svelte` into a shared library and put it at
+   `grammars/svelte.so` (`.dylib` on macOS, `.dll` on Windows):
+   ```
+   # one-time, needs the tree-sitter CLI + a C compiler
+   git clone https://github.com/tree-sitter-grammars/tree-sitter-svelte
+   cd tree-sitter-svelte && tree-sitter build --output svelte.so
+   ```
+2. Uncomment the `customLanguages` + `languageInjections` blocks in `sgconfig.yml`.
+3. Enable the template rules: `mv rules/svelte/template.yml.example rules/svelte/template.yml`
+   (shipped disabled because a `language: svelte` rule errors every scan until the grammar
+   is registered).
+4. Result: the existing **typescript/javascript rule packs automatically apply to the
+   code inside `<script>` blocks** (via injection), and `rules/svelte/` adds
+   template-level rules (e.g. `on:click` → `onclick`).
+
+This is opt-in because shipping a compiled grammar per platform conflicts with the
+skill's "bundled, no-compile" principle. Most users should rely on layer 1 + layer 3.
+
+### 3. Model-driven semantic refactors — always available
+For Svelte-specific refactors that no rule expresses, the model edits the relevant span
+with the guardrails below.
+
+## Svelte simplification catalog
+
+**Svelte 4 → 5 runes migration (mostly mechanical, but verify):**
+- `export let prop;` → `let { prop } = $props();`
+- `let x = v;` that is reactive → `let x = $state(v);`
+- `$: doubled = x * 2;` (pure computed) → `let doubled = $derived(x * 2);`
+- `$: { sideEffect(); }` (side effect) → `$effect(() => { sideEffect(); });`
+- `createEventDispatcher()` + `dispatch('e')` → callback props
+- `<slot />` → `{@render children?.()}`
+- `on:click={h}` → `onclick={h}` (template; see `rules/svelte/template.yml`)
+
+**Reactivity correctness (semantic — judgment required):**
+- `$effect` used to compute a value → should be `$derived` (perf + correctness).
+- Object/array mutated without reassignment in legacy mode → won't react.
+- Redundant writable store used purely inside one component → local `$state`.
+- `derived(store, ...)` replaceable by `$derived(...)`.
+
+**Mechanical vs semantic:**
+- Mechanical: `on:` → property, `export let` → `$props()`, `<slot/>` → `{@render}`.
+- Semantic: `$derived` vs `$effect` choice, store→state, hoisting load functions.
+
+## SvelteKit guardrails — DO NOT BREAK
+
+Refactor the *insides* freely; never violate these conventions:
+
+- **`+page.svelte` / `+layout.svelte`**: UI only. `load`/actions must NOT live here.
+  Keep the `children` snippet/render in layouts.
+- **`+page.ts` / `+page.server.ts` / `+layout(.server).ts`**: `load` lives here; form
+  `actions` only in `+page.server.ts`. Don't move `load` into a component. Don't change
+  universal-vs-server (`.server`) semantics. A page `load`'s data is page-scoped; only
+  hoist to a layout `load` if siblings actually need it.
+- **`+server.ts`**: HTTP handlers (`GET`/`POST`/…) — preserve method semantics; no GET
+  side effects.
+- **`+error.svelte`** must keep accepting `error`; **`+layout.svelte`** must keep
+  accepting `data` from its `load`.
+- Named vs default form actions can't coexist on one page; named actions need
+  `action="?/name"`. Don't rename one without the other.
+- Never touch generated/`$app/*`/`$env/*` wiring or `.svelte-kit/`.
+
+After any Svelte change, the verify gate should run the project's `svelte-check` and
+build/test from the ledger `config`, not just a generic build.
diff --git a/rules/go/complexity.yml b/rules/go/complexity.yml
new file mode 100644
index 0000000..bf99931
--- /dev/null
+++ b/rules/go/complexity.yml
@@ -0,0 +1,38 @@
+# Go — complexity smells (detection only, no `fix:` → Track B / semantic).
+
+id: go-deep-nesting
+language: Go
+severity: warning
+message: "Deeply nested conditional (>=3 levels) — consider early returns."
+rule:
+  kind: if_statement
+  inside:
+    kind: if_statement
+    stopBy: end
+    inside:
+      kind: if_statement
+      stopBy: end
+
+---
+id: go-long-param-list
+language: Go
+severity: warning
+message: "Long parameter list (>=5) — consider a struct parameter."
+rule:
+  kind: parameter_list
+  has:
+    kind: parameter_declaration
+    nthChild: 5
+
+---
+id: go-magic-number
+language: Go
+severity: info
+message: "Magic number in an expression — consider a named constant."
+rule:
+  kind: int_literal
+  not:
+    regex: "^(0|1|2|10|100|1000)$"
+  inside:
+    kind: binary_expression
+    stopBy: end
diff --git a/rules/go/simplify.yml b/rules/go/simplify.yml
new file mode 100644
index 0000000..0b256e8
--- /dev/null
+++ b/rules/go/simplify.yml
@@ -0,0 +1,19 @@
+# Go — mechanical, behavior-preserving simplifications (Track A: carry `fix:`).
+# Go is statically typed, so boolean-comparison removal is exactly equivalent.
+
+id: go-eq-true
+language: Go
+severity: hint
+message: "Redundant `== true` on a bool."
+rule:
+  pattern: $X == true
+fix: $X
+
+---
+id: go-eq-false
+language: Go
+severity: hint
+message: "`== false` on a bool is a negation."
+rule:
+  pattern: $X == false
+fix: "!$X"
diff --git a/rules/java/complexity.yml b/rules/java/complexity.yml
new file mode 100644
index 0000000..70e2c3d
--- /dev/null
+++ b/rules/java/complexity.yml
@@ -0,0 +1,38 @@
+# Java — complexity smells (detection only, no `fix:` → Track B / semantic).
+
+id: java-deep-nesting
+language: Java
+severity: warning
+message: "Deeply nested conditional (>=3 levels) — consider guard clauses / extract method."
+rule:
+  kind: if_statement
+  inside:
+    kind: if_statement
+    stopBy: end
+    inside:
+      kind: if_statement
+      stopBy: end
+
+---
+id: java-long-param-list
+language: Java
+severity: warning
+message: "Long parameter list (>=5) — consider a parameter object."
+rule:
+  kind: formal_parameters
+  has:
+    kind: formal_parameter
+    nthChild: 5
+
+---
+id: java-magic-number
+language: Java
+severity: info
+message: "Magic number in an expression — consider a named constant."
+rule:
+  kind: decimal_integer_literal
+  not:
+    regex: "^(0|1|2|10|100|1000)$"
+  inside:
+    kind: binary_expression
+    stopBy: end
diff --git a/rules/java/simplify.yml b/rules/java/simplify.yml
new file mode 100644
index 0000000..4efdc3e
--- /dev/null
+++ b/rules/java/simplify.yml
@@ -0,0 +1,18 @@
+# Java — mechanical, behavior-preserving simplifications (Track A: carry `fix:`).
+
+id: java-eq-true
+language: Java
+severity: hint
+message: "Redundant `== true` on a boolean."
+rule:
+  pattern: $X == true
+fix: $X
+
+---
+id: java-eq-false
+language: Java
+severity: hint
+message: "`== false` on a boolean is a negation."
+rule:
+  pattern: $X == false
+fix: "!($X)"
diff --git a/rules/javascript/complexity.yml b/rules/javascript/complexity.yml
new file mode 100644
index 0000000..980d606
--- /dev/null
+++ b/rules/javascript/complexity.yml
@@ -0,0 +1,38 @@
+# JavaScript/JSX — complexity smells (detection only, no `fix:` → Track B / semantic).
+
+id: js-deep-nesting
+language: JavaScript
+severity: warning
+message: "Deeply nested conditional (>=3 levels) — consider guard clauses / extract method."
+rule:
+  kind: if_statement
+  inside:
+    kind: if_statement
+    stopBy: end
+    inside:
+      kind: if_statement
+      stopBy: end
+
+---
+id: js-long-param-list
+language: JavaScript
+severity: warning
+message: "Long parameter list (>=5) — consider a parameter object."
+rule:
+  kind: formal_parameters
+  has:
+    kind: identifier
+    nthChild: 5
+
+---
+id: js-magic-number
+language: JavaScript
+severity: info
+message: "Magic number in an expression — consider a named constant."
+rule:
+  kind: number
+  not:
+    regex: "^(0|1|2|-1|10|100|1000)$"
+  inside:
+    kind: binary_expression
+    stopBy: end
diff --git a/rules/javascript/simplify.yml b/rules/javascript/simplify.yml
new file mode 100644
index 0000000..016f4b7
--- /dev/null
+++ b/rules/javascript/simplify.yml
@@ -0,0 +1,41 @@
+# JavaScript/JSX — mechanical, behavior-preserving simplifications (Track A: carry `fix:`).
+
+id: js-ternary-to-boolean
+language: JavaScript
+severity: hint
+message: "Ternary `c ? true : false` is just a boolean — use Boolean(c)."
+rule:
+  pattern: "$C ? true : false"
+fix: Boolean($C)
+
+---
+id: js-ternary-negate
+language: JavaScript
+severity: hint
+message: "Ternary `c ? false : true` is a negation — use !c."
+rule:
+  pattern: "$C ? false : true"
+fix: "!($C)"
+
+---
+id: js-prefer-includes
+language: JavaScript
+severity: hint
+message: "Use .includes() instead of .indexOf() comparison."
+rule:
+  any:
+    - pattern: $OBJ.indexOf($X) !== -1
+    - pattern: $OBJ.indexOf($X) >= 0
+    - pattern: $OBJ.indexOf($X) > -1
+fix: $OBJ.includes($X)
+
+---
+id: js-prefer-not-includes
+language: JavaScript
+severity: hint
+message: "Use !...includes() instead of .indexOf() === -1."
+rule:
+  any:
+    - pattern: $OBJ.indexOf($X) === -1
+    - pattern: $OBJ.indexOf($X) < 0
+fix: "!$OBJ.includes($X)"
diff --git a/rules/manifest.json b/rules/manifest.json
new file mode 100644
index 0000000..82286b2
--- /dev/null
+++ b/rules/manifest.json
@@ -0,0 +1,54 @@
+{
+  "_comment": "Maps ast-grep ruleId -> ledger classification. ast-grep's --json output includes ruleId + range but NOT rule metadata, so the assembly step (SKILL.md Step 3) joins each match to this table. `track`: ast-grep (has a fix:, deterministic) | llm (needs a span edit). `weight`: severity contribution in ranking.",
+  "rules": {
+    "ts-ternary-to-boolean": { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "ts-ternary-negate":     { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "ts-prefer-includes":    { "pattern": "prefer-includes",  "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "ts-prefer-not-includes":{ "pattern": "prefer-includes",  "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "ts-deep-nesting":       { "pattern": "guard-clauses",    "track": "llm", "difficulty": "semantic", "weight": 20 },
+    "ts-long-param-list":    { "pattern": "parameter-object", "track": "llm", "difficulty": "semantic", "weight": 10 },
+    "ts-magic-number":       { "pattern": "magic-number",     "track": "llm", "difficulty": "semantic", "weight": 3 },
+
+    "js-ternary-to-boolean": { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "js-ternary-negate":     { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "js-prefer-includes":    { "pattern": "prefer-includes",  "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "js-prefer-not-includes":{ "pattern": "prefer-includes",  "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "js-deep-nesting":       { "pattern": "guard-clauses",    "track": "llm", "difficulty": "semantic", "weight": 20 },
+    "js-long-param-list":    { "pattern": "parameter-object", "track": "llm", "difficulty": "semantic", "weight": 10 },
+    "js-magic-number":       { "pattern": "magic-number",     "track": "llm", "difficulty": "semantic", "weight": 3 },
+
+    "py-is-none":            { "pattern": "identity-compare", "track": "ast-grep", "difficulty": "mechanical", "weight": 4 },
+    "py-is-not-none":        { "pattern": "identity-compare", "track": "ast-grep", "difficulty": "mechanical", "weight": 4 },
+    "py-not-in":             { "pattern": "membership",       "track": "ast-grep", "difficulty": "mechanical", "weight": 4 },
+    "py-not-is":             { "pattern": "identity-compare", "track": "ast-grep", "difficulty": "mechanical", "weight": 4 },
+    "py-empty-seq-falsy":    { "pattern": "truthiness",       "track": "ast-grep", "difficulty": "mechanical", "weight": 4 },
+    "py-deep-nesting":       { "pattern": "guard-clauses",    "track": "llm", "difficulty": "semantic", "weight": 20 },
+    "py-long-param-list":    { "pattern": "parameter-object", "track": "llm", "difficulty": "semantic", "weight": 10 },
+    "py-magic-number":       { "pattern": "magic-number",     "track": "llm", "difficulty": "semantic", "weight": 3 },
+
+    "svelte-event-directive-to-property": { "pattern": "svelte-event-property", "track": "llm", "difficulty": "mechanical", "weight": 4, "requires": "svelte-grammar" },
+    "svelte-export-let-to-props":   { "pattern": "svelte-props",            "track": "llm", "difficulty": "semantic", "weight": 6, "requires": "svelte-grammar" },
+    "svelte-reactive-to-derived":   { "pattern": "svelte-runes-reactivity", "track": "llm", "difficulty": "semantic", "weight": 8, "requires": "svelte-grammar" },
+    "svelte-create-event-dispatcher":{ "pattern": "svelte-callback-props",  "track": "llm", "difficulty": "semantic", "weight": 6, "requires": "svelte-grammar" },
+    "svelte-slot-to-render":        { "pattern": "svelte-snippets",         "track": "llm", "difficulty": "semantic", "weight": 5, "requires": "svelte-grammar" },
+    "svelte-check":                 { "pattern": "svelte-diagnostic",       "track": "llm", "difficulty": "semantic", "weight": 7 },
+
+    "go-eq-true":            { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "go-eq-false":           { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "go-deep-nesting":       { "pattern": "guard-clauses",    "track": "llm", "difficulty": "semantic", "weight": 20 },
+    "go-long-param-list":    { "pattern": "parameter-object", "track": "llm", "difficulty": "semantic", "weight": 10 },
+    "go-magic-number":       { "pattern": "magic-number",     "track": "llm", "difficulty": "semantic", "weight": 3 },
+
+    "rs-eq-true":            { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "rs-eq-false":           { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "rs-deep-nesting":       { "pattern": "guard-clauses",    "track": "llm", "difficulty": "semantic", "weight": 20 },
+    "rs-long-param-list":    { "pattern": "parameter-object", "track": "llm", "difficulty": "semantic", "weight": 10 },
+    "rs-magic-number":       { "pattern": "magic-number",     "track": "llm", "difficulty": "semantic", "weight": 3 },
+
+    "java-eq-true":          { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "java-eq-false":         { "pattern": "simplify-boolean", "track": "ast-grep", "difficulty": "mechanical", "weight": 5 },
+    "java-deep-nesting":     { "pattern": "guard-clauses",    "track": "llm", "difficulty": "semantic", "weight": 20 },
+    "java-long-param-list":  { "pattern": "parameter-object", "track": "llm", "difficulty": "semantic", "weight": 10 },
+    "java-magic-number":     { "pattern": "magic-number",     "track": "llm", "difficulty": "semantic", "weight": 3 }
+  }
+}
diff --git a/rules/python/complexity.yml b/rules/python/complexity.yml
new file mode 100644
index 0000000..559904d
--- /dev/null
+++ b/rules/python/complexity.yml
@@ -0,0 +1,43 @@
+# Python — complexity smells (detection only, no `fix:` → Track B / semantic).
+
+id: py-deep-nesting
+language: Python
+severity: warning
+message: "Deeply nested conditional (>=3 levels) — consider guard clauses / early returns."
+rule:
+  kind: if_statement
+  inside:
+    kind: if_statement
+    stopBy: end
+    inside:
+      kind: if_statement
+      stopBy: end
+
+---
+id: py-long-param-list
+language: Python
+severity: warning
+message: "Long parameter list (>=5) — consider a dataclass / parameter object."
+rule:
+  kind: parameters
+  has:
+    any:
+      - kind: identifier
+      - kind: typed_parameter
+      - kind: default_parameter
+    nthChild: 5
+
+---
+id: py-magic-number
+language: Python
+severity: info
+message: "Magic number in an expression — consider a named constant."
+rule:
+  kind: integer
+  not:
+    regex: "^(0|1|2|10|100|1000)$"
+  inside:
+    any:
+      - kind: binary_operator
+      - kind: comparison_operator
+    stopBy: end
diff --git a/rules/python/simplify.yml b/rules/python/simplify.yml
new file mode 100644
index 0000000..0dabd7a
--- /dev/null
+++ b/rules/python/simplify.yml
@@ -0,0 +1,49 @@
+# Python — mechanical, behavior-preserving simplifications (Track A: carry `fix:`).
+# These are conventional, idiomatic rewrites (PEP 8 / common style).
+
+id: py-is-none
+language: Python
+severity: hint
+message: "Compare to None with `is`, not `==`."
+rule:
+  pattern: $X == None
+fix: $X is None
+
+---
+id: py-is-not-none
+language: Python
+severity: hint
+message: "Compare to None with `is not`, not `!=`."
+rule:
+  pattern: $X != None
+fix: $X is not None
+
+---
+id: py-not-in
+language: Python
+severity: hint
+message: "Use `not in` instead of `not ... in`."
+rule:
+  pattern: not $X in $Y
+fix: $X not in $Y
+
+---
+id: py-not-is
+language: Python
+severity: hint
+message: "Use `is not` instead of `not ... is`."
+rule:
+  pattern: not $X is $Y
+fix: $X is not $Y
+
+---
+id: py-empty-seq-falsy
+language: Python
+severity: hint
+message: "Empty-sequence check: prefer truthiness (`not seq` / `seq`)."
+metadata: { note: "Safe for lists/tuples/dicts/sets/str; if value may be a number or None, keep explicit." }
+rule:
+  any:
+    - pattern: len($X) == 0
+    - pattern: len($X) < 1
+fix: not $X
diff --git a/rules/rust/complexity.yml b/rules/rust/complexity.yml
new file mode 100644
index 0000000..8745376
--- /dev/null
+++ b/rules/rust/complexity.yml
@@ -0,0 +1,39 @@
+# Rust — complexity smells (detection only, no `fix:` → Track B / semantic).
+# Note: Rust conditionals are `if_expression`.
+
+id: rs-deep-nesting
+language: Rust
+severity: warning
+message: "Deeply nested conditional (>=3 levels) — consider early returns / let-else."
+rule:
+  kind: if_expression
+  inside:
+    kind: if_expression
+    stopBy: end
+    inside:
+      kind: if_expression
+      stopBy: end
+
+---
+id: rs-long-param-list
+language: Rust
+severity: warning
+message: "Long parameter list (>=5) — consider a struct parameter."
+rule:
+  kind: parameters
+  has:
+    kind: parameter
+    nthChild: 5
+
+---
+id: rs-magic-number
+language: Rust
+severity: info
+message: "Magic number in an expression — consider a named constant."
+rule:
+  kind: integer_literal
+  not:
+    regex: "^(0|1|2|10|100|1000)$"
+  inside:
+    kind: binary_expression
+    stopBy: end
diff --git a/rules/rust/simplify.yml b/rules/rust/simplify.yml
new file mode 100644
index 0000000..244ba05
--- /dev/null
+++ b/rules/rust/simplify.yml
@@ -0,0 +1,18 @@
+# Rust — mechanical, behavior-preserving simplifications (Track A: carry `fix:`).
+
+id: rs-eq-true
+language: Rust
+severity: hint
+message: "Redundant `== true` on a bool."
+rule:
+  pattern: $X == true
+fix: $X
+
+---
+id: rs-eq-false
+language: Rust
+severity: hint
+message: "`== false` on a bool is a negation."
+rule:
+  pattern: $X == false
+fix: "!($X)"
diff --git a/rules/svelte/runes.yml.example b/rules/svelte/runes.yml.example
new file mode 100644
index 0000000..51d640c
--- /dev/null
+++ b/rules/svelte/runes.yml.example
@@ -0,0 +1,53 @@
+# Svelte 4 -> 5 runes migration rules.
+#
+# REQUIRES the opt-in Svelte grammar (see ../../sgconfig.yml + ../../references/SVELTE.md).
+# Shipped as .example so it never breaks default scans. Enable with:
+#   mv runes.yml.example runes.yml
+# These are conservative: prop/event rewrites are mechanical-ish, but reactive-statement
+# migrations (`$:`) need judgment (derived vs effect), so they are detection-only (Track B).
+
+id: svelte-export-let-to-props
+language: svelte
+severity: hint
+message: "Svelte 5: replace `export let` with `$props()` destructuring."
+metadata: { pattern: svelte-props, track: llm, difficulty: semantic }
+rule:
+  any:
+    - pattern: "export let $PROP;"
+    - pattern: "export let $PROP = $DEFAULT;"
+note: |
+  Merge ALL props of a component into a single `let { a, b = 1 } = $props();` — do not
+  emit one destructure per prop. That cross-statement merge is why this is Track B.
+
+---
+id: svelte-reactive-to-derived
+language: svelte
+severity: hint
+message: "Svelte 5: `$:` computed value -> `$derived`; `$:` side effect -> `$effect`."
+metadata: { pattern: svelte-runes-reactivity, track: llm, difficulty: semantic }
+rule:
+  any:
+    - pattern: "$: $X = $EXPR;"          # pure assignment -> $derived
+    - pattern: "$: { $$$BODY }"          # block -> usually $effect
+note: |
+  `$: x = expr;` with no side effects -> `let x = $derived(expr);`.
+  `$: { ... }` performing side effects -> `$effect(() => { ... });`.
+  Decide by inspecting the body; never blindly convert.
+
+---
+id: svelte-create-event-dispatcher
+language: svelte
+severity: hint
+message: "Svelte 5: prefer callback props over createEventDispatcher()."
+metadata: { pattern: svelte-callback-props, track: llm, difficulty: semantic }
+rule:
+  pattern: "createEventDispatcher($$$)"
+
+---
+id: svelte-slot-to-render
+language: svelte
+severity: hint
+message: "Svelte 5: replace <slot/> with the {@render children()} snippet."
+metadata: { pattern: svelte-snippets, track: llm, difficulty: semantic }
+rule:
+  pattern: "<slot />"
diff --git a/rules/svelte/template.yml.example b/rules/svelte/template.yml.example
new file mode 100644
index 0000000..052f87a
--- /dev/null
+++ b/rules/svelte/template.yml.example
@@ -0,0 +1,21 @@
+# Svelte — template-level mechanical simplifications.
+#
+# REQUIRES the opt-in Svelte grammar (see sgconfig.yml + references/SVELTE.md).
+# Without it these rules are inert (ast-grep can't parse .svelte). The JS/TS code
+# inside <script> blocks is handled by the existing typescript/javascript packs via
+# language injection — no Svelte-specific rules needed for that part.
+#
+# NOTE: `language: svelte` only resolves once tree-sitter-svelte is registered as a
+# customLanguage. These patterns target Svelte 5 syntax.
+
+id: svelte-event-directive-to-property
+language: svelte
+severity: hint
+message: "Svelte 5: prefer the `onclick` property over the `on:click` directive."
+metadata: { pattern: svelte-event-property, track: llm, difficulty: mechanical }
+rule:
+  any:
+    - pattern: 'on:click={$H}'
+    - pattern: 'on:input={$H}'
+    - pattern: 'on:change={$H}'
+    - pattern: 'on:submit={$H}'
diff --git a/rules/typescript/complexity.yml b/rules/typescript/complexity.yml
new file mode 100644
index 0000000..0c8cd39
--- /dev/null
+++ b/rules/typescript/complexity.yml
@@ -0,0 +1,46 @@
+# TypeScript — complexity smells (detection only, no `fix:` → Track B / semantic).
+# These flag spans for the model to refactor with judgment (guard clauses, extract
+# method, named constants). Function length is computed by the assembly step from the
+# match range; param count from the matched signature.
+
+id: ts-deep-nesting
+language: TypeScript
+severity: warning
+message: "Deeply nested conditional (>=3 levels) — consider guard clauses / extract method."
+metadata: { pattern: guard-clauses, apply_track: llm, difficulty: semantic }
+rule:
+  kind: if_statement
+  inside:
+    kind: if_statement
+    stopBy: end
+    inside:
+      kind: if_statement
+      stopBy: end
+
+---
+id: ts-long-param-list
+language: TypeScript
+severity: warning
+message: "Long parameter list (>=5) — consider a parameter object."
+metadata: { pattern: parameter-object, apply_track: llm, difficulty: semantic }
+rule:
+  kind: formal_parameters
+  has:
+    any:
+      - kind: required_parameter
+      - kind: optional_parameter
+    nthChild: 5
+
+---
+id: ts-magic-number
+language: TypeScript
+severity: info
+message: "Magic number in an expression — consider a named constant."
+metadata: { pattern: magic-number, apply_track: llm, difficulty: semantic }
+rule:
+  kind: number
+  not:
+    regex: "^(0|1|2|-1|10|100|1000)$"
+  inside:
+    kind: binary_expression
+    stopBy: end
diff --git a/rules/typescript/simplify.yml b/rules/typescript/simplify.yml
new file mode 100644
index 0000000..7965477
--- /dev/null
+++ b/rules/typescript/simplify.yml
@@ -0,0 +1,47 @@
+# TypeScript — mechanical, behavior-preserving simplifications (Track A: carry `fix:`).
+# Each is safe regardless of operand types; the assembly step reads `metadata` to set
+# apply_track / difficulty / suggested_pattern in the ledger.
+
+id: ts-ternary-to-boolean
+language: TypeScript
+severity: hint
+message: "Ternary `c ? true : false` is just a boolean — use Boolean(c)."
+metadata: { pattern: simplify-boolean, apply_track: ast-grep, difficulty: mechanical }
+rule:
+  pattern: "$C ? true : false"
+fix: Boolean($C)
+
+---
+id: ts-ternary-negate
+language: TypeScript
+severity: hint
+message: "Ternary `c ? false : true` is a negation — use !c."
+metadata: { pattern: simplify-boolean, apply_track: ast-grep, difficulty: mechanical }
+rule:
+  pattern: "$C ? false : true"
+fix: "!($C)"
+
+---
+id: ts-prefer-includes
+language: TypeScript
+severity: hint
+message: "Use .includes() instead of .indexOf() comparison."
+metadata: { pattern: prefer-includes, apply_track: ast-grep, difficulty: mechanical }
+rule:
+  any:
+    - pattern: $OBJ.indexOf($X) !== -1
+    - pattern: $OBJ.indexOf($X) >= 0
+    - pattern: $OBJ.indexOf($X) > -1
+fix: $OBJ.includes($X)
+
+---
+id: ts-prefer-not-includes
+language: TypeScript
+severity: hint
+message: "Use !...includes() instead of .indexOf() === -1."
+metadata: { pattern: prefer-includes, apply_track: ast-grep, difficulty: mechanical }
+rule:
+  any:
+    - pattern: $OBJ.indexOf($X) === -1
+    - pattern: $OBJ.indexOf($X) < 0
+fix: "!$OBJ.includes($X)"
diff --git a/sgconfig.yml b/sgconfig.yml
new file mode 100644
index 0000000..f3af431
--- /dev/null
+++ b/sgconfig.yml
@@ -0,0 +1,40 @@
+# ast-grep project configuration for the simplify-code skill.
+# Docs: https://ast-grep.github.io/reference/sgconfig.html
+#
+# `ast-grep scan -c <this file> --json <paths>` loads every rule under ruleDirs.
+# Rules are grouped per language; each carries a `severity`, a detection `rule:`,
+# and — for mechanical simplifications — a `fix:` (Track A autofix).
+ruleDirs:
+  - rules
+
+# ---------------------------------------------------------------------------
+# OPT-IN: Svelte / SvelteKit structural rules on .svelte files.
+#
+# ast-grep has no built-in Svelte grammar. To run structural rules on .svelte
+# files you must register tree-sitter-svelte as a custom language AND inject the
+# JS/TS grammar into <script> blocks. This needs a compiled grammar library
+# (.so/.dylib/.dll), so it is NOT bundled — it is opt-in. See references/SVELTE.md
+# for the one-time build steps. Once built, uncomment the blocks below AND enable the
+# template rules (mv rules/svelte/template.yml.example rules/svelte/template.yml); then
+# the existing TypeScript/JavaScript rule packs automatically apply to the code inside
+# <script> blocks via injection, and rules/svelte/ adds template-level rules.
+#
+# customLanguages:
+#   svelte:
+#     libraryPath: ./grammars/svelte.so   # build per references/SVELTE.md
+#     extensions: [svelte]
+#     expandoChar: _                       # $ -> _ so $state/$props parse cleanly
+#
+# languageInjections:
+#   - hostLanguage: svelte
+#     rule: { pattern: '<script lang="ts">$CONTENT</script>' }
+#     injected: typescript
+#   - hostLanguage: svelte
+#     rule: { pattern: "<script>$CONTENT</script>" }
+#     injected: javascript
+# ---------------------------------------------------------------------------
+#
+# Without the grammar, Svelte is still supported: detection falls back to the
+# project's own Svelte tooling (svelte-check, eslint-plugin-svelte, svelte
+# compiler warnings) as enrichment, and semantic refactors go to the model with
+# the SvelteKit guardrails in references/SVELTE.md.