improve

# improve — audit with a strong model, execute with cheap ones `improve` is an agent skill (Agent Skills format) that audits any codebase and writes implementation plans for other agents to execute. The premise: spend your most capable model on the part where intelligence compounds — understanding the codebase, judging what is worth doing, writing the spec — and hand execution to cheaper models. The skill never implements anything itself; the plan is the product. ``` you → /improve (expensive model, advises) plans/ → 001-fix-n-plus-one.md (self-contained specs) other agent → implements, tests, ships (cheap model, executes) ``` ## Install ```bash npx skills add shadcn/improve ``` It works in any agent supporting the Agent Skills format. Plans are plain markdown, so any agent or human can pick them up. ## Commands - `/improve` — full audit → prioritized findings → plans - `/improve quick` — cheap pass: hotspots, top findings only - `/improve deep` — exhaustive: every package, every category - `/improve security` — focused audit (also perf, tests, bugs, ...) - `/improve branch` — audit only what the current branch changes - `/improve next` — feature suggestions, where to take the project - `/improve plan <description>` — skip the audit, spec one thing - `/improve review-plan <file>` — critique and tighten an existing plan - `/improve execute <plan>` — dispatch a cheaper executor, review its work - `/improve reconcile` — refresh the backlog: verify, unblock, retire - `--issues` — also publish plans as GitHub issues ## Typical first run 1. Open your agent in the repo and run `/improve` (or `/improve quick` to keep it cheap). 2. It maps the repo, audits it, and returns a findings table. Reply with the ones you want planned, e.g. "plan 1, 3 and 5". 3. Plans land in `plans/` — one file each, plus an index with recommended order. They are meant to be reviewed. 4. Hand a plan to any agent ("implement plans/001-*.md"), or let the skill run it: `/improve execute 001` dispatches a cheaper model in an isolated worktree, reviews the diff against the plan, and reports a verdict. Merging stays up to you. 5. Next session, `/improve reconcile` cleans up the backlog: verify what landed, refresh what drifted, unblock what got stuck. Before a PR, `/improve branch` scopes the same process to just what the branch changes. ## How it works - **Recon.** Maps the repo: stack, conventions, and exact build/test/lint commands, which become verification gates in every plan. It also ingests intent and design docs when present — ADRs (`docs/adr/`), PRDs, `CONTEXT.md`, `DESIGN.md`, `PRODUCT.md` — so decided tradeoffs are not re-flagged, direction suggestions stay grounded in stated product intent, and plans use the repo's own vocabulary. - **Audit.** Fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction (feature suggestions must cite evidence from the repo itself). Every finding carries `file:line` evidence, impact, effort, and confidence. - **Vet.** Because subagents over-report, the advisor re-reads every cited location before showing anything; false positives are dropped, wrong attributions corrected, rejections recorded. - **Prioritize.** Findings land in a table ordered by leverage (impact ÷ effort, weighted by confidence). You choose what becomes plans. - **Plan.** One file per selected finding in `plans/`, with an index, priority order, and dependency graph. ## What makes the plans executable Plans target the weakest plausible executor — a model that never saw the advisor session and may be much smaller. Three properties carry that: - **Self-contained.** All context is inlined: exact file paths, current-state code excerpts, repo conventions with an exemplar file, verified commands. No "as discussed above." - **Verification gates.** Every step ends with a command and its expected output; done criteria are machine-checkable, so the executor never has to judge success. - **Hard boundaries.** Explicit out-of-scope lists and STOP conditions ("if X, stop and report") instead of letting a small model improvise when reality does not match the plan. Each plan stamps the git commit it was written against, so executors can run a mechanical drift check before touching anything. ## Closing the loop - **`execute <plan>`** spawns a cheaper executor subagent in an isolated git worktree, hands it the plan, then reviews the result like a tech lead — re-runs every done criterion, checks scope compliance, reads the diff against intent. Verdict: approve (merging stays your call), send back for revision (max 2 rounds), or block and refine the plan. - **`reconcile`** processes what happened since: verifies DONE plans still hold, investigates BLOCKED ones and rewrites around the obstacle, refreshes drifted plans, retires findings fixed independently. - **`--issues`** publishes plans as GitHub issues with the same self-contained body, so any agent or human can pick them up where work already lives. ## Hard rules - Never modifies source code itself. The only writes go to `plans/`; executors edit only in disposable worktrees, and merging is always yours. - Never runs commands that mutate the working tree — read, search, and read-only analysis only. - Never reproduces secret values; locations and credential types only, rotation always recommended. - Asked to implement, it declines and points at the plan (or offers `execute`). ## License MIT © shadcn