improve

Product Introduction

1. Definition: Improve (shadcn/improve) is an open-source developer tool and AI agent skill designed to optimize AI-driven coding workflows. Operating within environments that support the Agent Skills format, it utilizes high-intelligence, expensive frontier models exclusively for codebase auditing, architectural analysis, and precision specification writing, while delegating mechanical implementation tasks to cheaper, less capable execution models.

2. Core Value Proposition: Improve addresses the escalating operational costs and context-window inefficiencies of running smart AI coding agents continuously. By separating high-level strategic reasoning from low-level code execution, it significantly reduces API costs for engineering teams scaling AI-assisted development. It establishes a sustainable workflow where expensive models act as technical leads—generating self-contained implementation plans—and cheaper execution models handle writing, testing, and shipping code.

Main Features

1. Multi-Category Codebase Auditing: Improve fans out parallel subagents to conduct comprehensive audits across nine distinct categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, developer experience (DX), documentation, and feature direction. The advisor phase vets all raw subagent findings by re-reading cited code locations to eliminate false positives, calculate leverage ratios (impact divided by effort, weighted by confidence), and record explicit rejections to prevent recurring flags.

2. Self-Contained Implementation Plan Generation: The tool writes markdown-based specification files into a local plans/ directory, complete with an execution index and dependency graph. Every plan is meticulously engineered for execution by weaker models, featuring inlined context, exact file paths, current-state code excerpts, repository-specific verification commands (such as build, lint, and test scripts), and explicit hard boundaries including out-of-scope lists and actionable "STOP conditions" for environmental drift.

3. Isolated Execution and Lifecycle Reconciliation: Improve includes built-in orchestration commands like /improve execute, which dispatches a cheaper executor model inside an isolated git worktree, reviews the resulting diff against the original plan, and evaluates done criteria. Additionally, the /improve reconcile command maintains backlog hygiene by verifying completed plans, rewriting blocked paths, refreshing drifted specifications, and retiring independently resolved findings.

Problems Solved

1. Pain Point: The primary challenge addressed by Improve is the prohibitive economic cost of relying exclusively on frontier large language models (LLMs) for end-to-end coding tasks, compounded by the degradation of code quality when smaller models attempt complex architectural reasoning without structured guidance.

2. Target Audience: Full-stack software engineers, engineering managers, DevOps teams, and technical leads scaling AI development workflows across complex repositories who require deterministic, verifiable execution from automated coding agents.

3. Use Cases: Essential scenarios include auditing large-scale legacy codebases for hidden performance bottlenecks (such as N+1 database queries), running scoped codebase checks against active git branches before opening pull requests, generating secure migration plans for deprecated dependencies, and publishing structured architectural specifications directly to GitHub issues for asynchronous team or agent execution.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros: Drastically reduces LLM token expenditure by restricting smart model usage to planning phases; ensures high execution reliability via self-contained markdown specifications and machine-checkable verification gates; operates safely by never mutating working trees directly or executing write operations outside disposable git worktrees.
   • Cons: Relies heavily on the host agent environment supporting the Agent Skills format; requires upfront repository context (such as architecture decision records or product documentation) for optimal output grounding; does not autonomously merge code changes, leaving final merge responsibilities to human engineers.

2. Key Alternatives & Differentiation:

   • Alternative 1 (Standard AI Coding Assistants like GitHub Copilot or Cursor Chat): While standard assistants execute tasks end-to-end using a single model tier—often driving up costs and causing loss of context on large tasks—Improve implements a decoupled, multi-model delegation pipeline that separates high-level technical direction from mechanical execution.
   • Alternative 2 (Traditional Static Analysis Tools like SonarQube or ESLint): Traditional linters rely on static rule sets and often generate overwhelming noise; Improve leverages contextual AI reasoning to evaluate architectural trade-offs, weigh effort against business impact, and generate plain-language execution specs tailored to the specific codebase conventions.

Frequently Asked Questions (FAQ)

1. What is the primary architectural difference between Improve and traditional AI coding agents? Improve strictly separates the reasoning phase from the execution phase. It uses your most expensive, highly capable AI model solely to analyze the codebase, audit code quality, and write deterministic implementation plans, while dispatching cheaper models to execute those plans in isolated git worktrees.

2. Does Improve automatically modify source code or commit changes to my repository? No. Improve has strict hard rules prohibiting it from modifying source code directly or running commands that mutate your working tree. All generated outputs are written exclusively as markdown files in the plans/ directory, and actual implementation is handled by secondary executors or human developers.

3. How do the generated implementation plans ensure success with cheaper execution models? Plans are self-contained with all necessary context inlined, including exact file paths, current code snippets, repository conventions, and specific verification commands. They also include strict "STOP conditions" and machine-checkable done criteria so smaller models do not have to guess or improvise when encountering unexpected states.

4. Can I use Improve with existing project documentation and architectural decisions? Yes. Improve automatically ingests existing repository intent and design documentation—such as architecture decision records (docs/adr/), PRDs, CONTEXT.md, and DESIGN.md files—to ensure its audits and suggestions respect established product trade-offs and project vocabulary.