shadcn/improve: audit once, write plans for cheap models

A GitHub trend worth watching this week is shadcn/improve, an agent skill released under MIT. The author is shadcn — the same person whose UI primitives sit in half of modern React projects. As of November 13 the repository has around 11.6k stars; it was created in June 2026 and its last commit is from September.

The repository description is short and exact:

“Use your most capable model to audit your codebase and write plans for cheaper models to execute.”

In other words: put the expensive model where intelligence compounds — understanding the code, deciding what is worth doing, writing the spec. Hand execution to cheaper models.

you          →  /improve                    (expensive model, advises)
plans/       →  001-fix-n-plus-one.md       (self-contained specs)
other agent  →  implements, tests, ships    (cheap model, executes)

The core idea: the plan is the product, not the code. The skill never implements anything itself.

How it works

A five-step pipeline, described fairly openly in the README.

Recon. The skill maps the repository: stack, conventions, the exact build, test and lint commands. Those become verification gates in every plan later. If the project keeps ADRs, a PRD, CONTEXT.md, DESIGN.md or PRODUCT.md, it reads them so settled tradeoffs do not resurface as findings.

Audit. Parallel subagents cover nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction. Every finding carries file:line, impact, effort and confidence. Suggestions for direction must cite evidence from the repository itself — the README calls out “no generic idea-slop”.

Vet. Subagents over-report, so the advising model re-reads every cited location itself before showing the list. False positives are dropped, wrong attributions corrected, and rejections recorded so they do not come back next run.

Prioritize. Findings are ranked by leverage: impact divided by effort, weighted by confidence. You pick what becomes a plan.

Plan. One markdown file per selected finding in plans/, plus an index with priority order and a dependency graph.

Why the plans are executable

This is the most practical part of the README. Plans are written for the weakest plausible executor — a model that never saw the advisor session and may be considerably smaller. Three properties carry that:

• Self-contained. Exact paths, current-code excerpts, repo conventions with an exemplar file, verified commands.
• Verification gates. Every step ends with a command and its expected output, so done criteria are machine-checkable.
• Hard boundaries. Explicit out-of-scope lists and STOP conditions instead of letting a small model improvise when reality diverges from the plan.

Each plan also stamps the git commit it was written against, so an executor can detect drift before touching anything.

What the commands do

/improve                        full audit → prioritized findings → plans
/improve quick                  cheap pass: hotspots and 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                   direction 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
/improve ... --issues           publish plans as GitHub issues

Worth a separate mention: execute spawns a cheaper 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 with you), send back for revision (at most two rounds), or block and refine the plan.

There are also “hard rules”: the skill never changes source code — its only writes go to plans/; it does not run commands that mutate the working tree; it never reproduces secret values (only locations and credential types, with a rotation recommendation). Asked to “just implement it”, it declines and points at the plan.

Why this matters in practice

The idea of “expensive model thinks, cheap model does” is a division of labour for agentic development. Most cheap-model experiments fail because the task was never specified well. Here the quality comes from the specification: if a plan is self-contained and checkable, the executor does not need a large context or an expensive model — it needs a precise brief.

The second effect: an audit stops being a one-off. Findings and rejections are recorded, and reconcile returns to them later — what landed, what drifted, what got unblocked. The tech-debt backlog lives in the repository instead of someone’s head.

Where it could fit our stack

To be clear: we have not deployed this project in production. Everything below is a review of the README and repository, not a report from our own practice.

Web and CRM development. Our stack is Astro and Next.js on the front end, Python and PHP on the back end. Before changes, /improve branch makes sense: audit only the current branch’s diff rather than “rewrite everything”. For security, /improve security complements a normal review — it does not replace a dependency scanner.

The content pipeline. The same principle works outside code: a strong model writes a detailed brief for an article or a pipeline change, and routine execution goes to cheaper agents. The requirement of “self-contained plan with checkable gates” disciplines task definition as much as it improves auditing.

Monitoring. One boundary to keep straight: improve looks at code, not server configuration. Its security category does not replace tracking CVEs in nginx, PHP, the kernel and dependencies — those are two separate loops, and both are needed.

Things to consider before installing: you need an agent that supports the Agent Skills format (npx skills add shadcn/improve); the project is young and its last activity is September 2026, so behaviour may change; and most importantly, this is a development tool, not a business audit. It will tell you where an N+1 query and duplicated configuration live — not whether you need to change your sales model.

Repository: github.com/shadcn/improve

📞 +7 (906) 311-77-69 · ✉ hello@automata.sale · 💬 Telegram: @automatasale · 🌐 automata.sale

ИП Урядов Евгений Евгеньевич · ИНН 645112058391 · ОГРНИП 312645301900058 We work across Russia, Belarus and Kazakhstan