Recommend this project: shadcn (author of shadcn/ui) built an Agent Skill — letting the most expensive model handle audit and planning, while cheap models write the code. The idea itself isn’t new, but shadcn turned it into an installable, orchestratable system with a closed execution loop — every design decision is practical.

shadcn/improve: an Agent Skill that lets the strongest model audit and the cheap model write code.

Core philosophy: put the part where intelligence compounds — understanding the codebase, judging what’s worth doing, writing the spec — on the strongest model. Execution goes to cheap models. The skill never implements anything itself. The plan is the product.

/improve → global audit → prioritized findings → plans

Usage:

/improve               # full audit
/improve quick         # cheap: hotspots + top priority
/improve deep          # exhaustive: every package, every category
/improve security      # focused audit (also: perf, tests, bugs...)
/improve branch        # only what the current branch changes
/improve next          # product direction suggestions
/improve plan <description>   # skip audit, draft a plan directly
/improve review-plan <file>   # critique and tighten an existing plan
/improve execute <plan>       # dispatch cheap executor, review its work
/improve reconcile            # refresh backlog: verify, unblock, retire

Internal workflow:

1. Recon. Map the repo: stack, conventions, accurate build/test/lint commands — these become verification gates in every plan. Also reads design documents (ADR, PRD, CONTEXT.md etc.) so already-decided tradeoffs don’t get re-flagged.

2. Audit. Parallel sub-agents fan out across 9 categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, direction. Each finding comes with file:line evidence, impact, effort, and confidence.

3. Vet. Sub-agents over-report, so the advisor re-reads every cited location before showing you — false positives get dropped, wrong attributions get corrected, rejections get recorded.

4. Prioritize. Findings sorted by leverage (impact ÷ effort, weighted by confidence). You pick which become plans.

5. Plan. One file per selected finding, written to plans/ with an index, priority order, and dependency graph.

What makes these plans executable:

Plans are written for the weakest reasonable executor — a model that has never seen the advisor session and may be much smaller. Three properties make this work:

• Self-contained. All context inlined: exact file paths, current-state code excerpts, repo conventions with exemplar files, verified commands. No “as discussed above.”
• Verification gates. Every step ends with a command and its expected output. Done criteria are machine-checkable. The executor never has to judge if it succeeded.
• Hard boundaries. Explicit out-of-scope lists, plus STOP conditions — “if X, stop and report” — instead of letting a small model improvise when reality doesn’t match the plan.

Closed loop:

• execute: dispatches a cheaper executor sub-agent in an isolated git worktree, hands over the plan, then reviews like a Tech Lead — re-runs every done criterion, checks scope compliance, reads the diff against intent. Verdict: approve (merge is always your call), send back for revision (max 2 rounds), or block and refine the plan.
• reconcile: verifies DONE plans still hold, investigates BLOCKED plans and rewrites around obstacles, refreshes drifted plans, retires findings fixed independently.
• --issues: publishes plans as GitHub issues.

Hard rules:

• Never modifies source code. The only writes go to plans/; executors edit only in disposable worktrees; merging is always yours.
• Never runs commands that would damage your working tree.
• Never reproduces secret values.
• Asked to implement? Declines and points to the plan (or offers execute).

Project: shadcn/improve https://github.com/shadcn/improve #AgentSkills #CodeAudit #LLMArchitecture

shadcn/improve

Source: https://github.com/shadcn/improve

improve

An agent skill that audits any codebase and writes implementation plans for other agents to execute.

The idea: use your most capable model for the part where intelligence compounds — understanding the codebase, judging what’s 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

npx skills add shadcn/improve

Works in any agent that supports Agent Skills (https://agentskills.io) format. The plans it writes are plain markdown, so any agent (or human) can pick them up.

Usage

/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 skip the audit, spec one thing
/improve review-plan critique and tighten an existing plan
/improve execute dispatch a cheaper executor, review its work
/improve reconcile refresh the backlog: verify, unblock, retire
/improve ... --issues also publish plans as GitHub issues

How to use

A typical first run, start to finish:

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 comes back with a findings table. Reply with the ones you want planned — “plan 1, 3 and 5”.
3. Plans land in plans/ — one file each, plus an index with the recommended order. Read them; they’re meant to be reviewed.
4. Hand a plan to any agent (“implement plans/001-*.md”), or let the skill run it: /improve execute 001. It dispatches a cheaper model in an isolated worktree, reviews the diff against the plan, and reports back with a verdict. Merging stays up to you.
5. Next session, run /improve reconcile to clean up the backlog: verify what landed, refresh what drifted, unblock what got stuck.

Before a PR, /improve branch does the same thing scoped to just what your branch changes.

Example

A run against shadcn/ui (https://github.com/shadcn-ui/ui) came back with findings like:

| # | Finding | Category | Effort | Confidence |
|---|------------------------------------------------|-----------|--------|------------|
| 1 | shadow-config duplicated in search.ts/view.ts, | tech-debt | M | HIGH |
|   | copies already drifted (TODO at search.ts:31) |           |        |            |
| 2 | O(n2) icon migration (migrate-icons.ts:168) | perf | S | HIGH |

…and rejected a few, with reasons recorded so they don’t come back next run:

- [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention, every CLI honors it. Not a finding.

Picking #1 produced this plan — current code excerpted, exact steps, the repo’s own test/lint commands as verification gates, and STOP conditions for when reality doesn’t match.

How it works

Recon. Maps the repo: stack, conventions, and the exact build/test/lint commands — these 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 aren’t re-flagged as findings, direction suggestions stay grounded in stated product intent, and plans speak the repo’s own vocabulary. Composes with any repo that already maintains these docs.

Audit. Fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction (feature suggestions — every one must cite evidence from the repo itself, no generic idea-slop). Every finding carries file:line evidence, impact, effort, and confidence.

Vet. Subagents over-report, so the advisor re-reads every cited location itself before showing you anything — false positives get dropped, wrong attributions get corrected, rejections get recorded.

Prioritize. Findings land in a table ordered by leverage (impact ÷ effort, weighted by confidence). You pick what becomes plans.

Plan. One file per selected finding, written into plans/ with an index, priority order, and dependency graph.

What makes the plans executable

Plans are written for the weakest plausible executor — a model that has never seen 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. The executor never has to judge whether it succeeded.
• Hard boundaries. Explicit out-of-scope lists, and STOP conditions — “if X, stop and report” — instead of letting a small model improvise when reality doesn’t match the plan.

Each plan also stamps the git commit it was written against, so executors run a mechanical drift check before touching anything.

Closing the loop

Plans aren’t fire-and-forget:

• execute <id> 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 that got fixed independently.
• --issues publishes plans as GitHub issues — 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 your 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