shadcn/improve: Agentic Code Review with Divide and Conquer¶
Source: shadcn/improve \ Date Published: 2026 \ Author/Org: shadcn
TL;DR¶
shadcn/improve is an MIT-licensed open-source tool that implements a novel agentic pipeline for codebase improvement. The core philosophy: "The plan is the product." Use your most capable (and expensive) model to deeply audit a codebase and write detailed plans, then hand off mechanical execution to cheaper models. The pipeline has five stages: Recon (maps the repository structure) → Audit (parallel subagents across 9 categories: correctness, security, performance, test coverage, tech debt, dependencies, developer experience, documentation, and direction) → Vet (re-reads every cited location and drops false positives) → Prioritize (ranks by leverage = impact/effort) → Plan (one file per finding in a plans/ directory). Plans are self-contained for the weakest plausible executor — with exact steps, repo test commands as verification gates, explicit STOP conditions, and git commit drift checks.
The Philosophy: The Plan Is the Product¶
shadcn/improve inverts the typical AI coding workflow. Instead of having an LLM write code directly (with all the attendant risks of hallucination, missed context, and inconsistent style), the tool separates planning from execution. The expensive model does what it does best — understanding context, identifying problems, and reasoning about tradeoffs. The cheap model does what it does best — following precise instructions.
This separation of concerns yields two benefits: 1. Cost efficiency: The expensive model runs once per audit; the cheap model runs many times across individual fixes. 2. Verifiability: Plans can be reviewed, modified, or rejected before any code changes are made.
The Pipeline¶
1. Recon¶
The first stage maps the repository: directory structure, key files, configuration, dependencies, test setup, and build system. This creates a shared context that subsequent stages reference.
2. Audit¶
Parallel subagents examine the codebase across nine dimensions:
| Category | Focus |
|---|---|
| Correctness | Logic errors, edge cases, race conditions |
| Security | Injection, auth flaws, sensitive data exposure |
| Performance | Slow paths, N+1 queries, memory leaks |
| Test Coverage | Gaps, weak assertions, untested paths |
| Tech Debt | Dead code, duplicated logic, anti-patterns |
| Dependencies | Outdated, vulnerable, or unnecessary packages |
| DX | Build times, error messages, dev loop friction |
| Documentation | Missing, misleading, or stale docs |
| Direction | Architectural drift, future-proofing |
3. Vet¶
A critical quality gate: the vet stage re-reads every cited location in the codebase, verifying that the audit findings are real. False positives are dropped. This dramatically improves the signal-to-noise ratio.
4. Prioritize¶
Remaining findings are ranked by leverage = impact / effort. High-impact, low-effort fixes float to the top. This prevents the team from getting bogged down in marginal improvements.
5. Plan¶
Each finding gets a self-contained plan file in plans/. Plans are written for the weakest plausible executor — they include:
- Exact file paths and line numbers
- Step-by-step instructions for the change
- The repo's own test commands as verification gates
- Explicit STOP conditions (what to do if a step fails)
- Git commit drift checks (detect if the codebase has changed since the plan was written)
Key Takeaways¶
- shadcn/improve separates planning (expensive model) from execution (cheap model), making the process cost-efficient and verifiable.
- "The plan is the product" — the core insight is that reasoning and context understanding is the expensive part; mechanical code changes are cheap.
- The pipeline has five stages: Recon → Audit (9 categories in parallel) → Vet (drop false positives) → Prioritize (by leverage) → Plan (one file per finding).
- Plans are self-contained for the weakest plausible executor, with exact steps, test commands as verification gates, STOP conditions, and drift checks.
- The vet stage is critical — re-reading every cited location eliminates false positives and maintains trust in the system.
- MIT-licensed and designed to work with any LLM provider capable of following structured instructions.