shadcn/improve: Code Review Using Best Models and Planning Low-Cost Model Execution

Leveraging Top Models for Auditing and Planning, Cheaper Models for Execution

shadcn/improve’s core idea is to exploit the strengths of different AI models: the most powerful model understands the codebase deeply, identifies valuable improvements, and drafts detailed action plans. These plans are written in plain Markdown, easily readable by any AI or human agent.

Execution is delegated to less expensive models that do not directly modify source code but operate within isolated git worktrees. After execution, the results are compared against the plan, and a report is generated. The final merge decision is left to the user.

Detailed Workflow and Comprehensive Auditing Categories

Users trigger the process by issuing commands (e.g., /improve) via their agent connected to the repository. The system maps the repo’s structure and produces an audit with a findings table. Users select which findings to generate plans for.

The audit covers categories like correctness, security, performance, test coverage, technical debt, dependencies and migrations, developer experience, documentation, and product direction suggestions. Each finding includes file and line evidence, impact, effort, and confidence.

Subagents vet findings by re-reading cited code locations to remove false positives and correct attributions, ensuring high quality of reported findings.

Plans Designed for Independent, Verifiable Execution

Each plan is crafted for the weakest plausible executor — a model unfamiliar with prior context. It contains self-contained context including exact file paths, code excerpts, and repo conventions.

Verification gates accompany every execution step with expected command outputs, allowing automated success/failure checks. Hard stop conditions halt execution if reality deviates from the plan and report the issue.

Plans are stamped with the git commit they target, enabling drift checks before any modifications are attempted.