shadcn/improve: The Repo That Turns AI Coding Into a Tech Lead Workflow

It separates judgment from implementation, forces every change through a verification gate, and treats Markdown as the handoff layer between expensive reasoning and cheap execution.

8 min read • View on GitHub • More from shadcn

A wide desk split into two stations. On the left, an advisor studies a repo map, diffs, and a checklist. On the right, an executor types from a narrow plan sheet, with a clean handoff folder between them. It explains the project’s core idea: thinking and typing are different jobs.
The repo formalizes a split between judgment and labor, then uses a plan file to pass work across that boundary.
Key Takeaways

The interesting move here is not more agent power. It is division of labor. `improve` asks a capable model to do the scarce work, which is to inspect a codebase, spot risks, and decide what matters. Then it hands the result to a cheaper executor, or a human, with enough structure that the next step is obvious.

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

Project README, Repository documentation · shadcn/improve README

The Quiet Revolution: Judgment Is Separate From Labor

Most AI coding tools try to collapse the whole job into one pass. Read the repo, reason about the fix, write the patch, maybe even verify it. `improve` is more opinionated than that. It assumes the hardest part is not typing code. It is deciding what code should change, why, and under what evidence.

That matters because coding agents fail in familiar ways: they drift, overfit to noisy context, and invent certainty when the repo is ambiguous. `improve` is built around the opposite instinct. Keep the thinking step expensive and careful. Keep the execution step narrow, reproducible, and cheap.

How `improve` Recreates a Senior Engineer’s Workflow

The workflow is a pipeline with judgment checkpoints. It advances only when each stage has enough evidence to justify the next one.

The repo’s structure mirrors a tech lead’s instincts. First, map the territory. Then audit for failure modes. Then vet the strongest claims against the actual repository and documentation. Only after that do you prioritize findings and write a plan.

That order is the point. It separates observation from interpretation. The advisor is read-only, which forces discipline. It cannot quietly mutate the codebase while it is still figuring out what is wrong.

A close-up of a Markdown document turning into a sequence of checkable steps. Each line ends in a command prompt, an expected result, and a verification box. One branch breaks off into a STOP marker when the evidence does not match the expectation. It explains why the plan acts like an execution contract.
The plan is not prose. It is a checklist with commands, expectations, and stop conditions baked in.

The Plan Is the Product

The most important artifact in the repo is not code. It is the plan. In `plan-template.md`, the execution document has to stand on its own. That means commands, expected outputs, enough context to continue without the advisor session, and enough precision to stop ambiguity from leaking forward.

This is a subtle but strong design choice. Markdown is the interface because it is portable, inspectable, and recoverable. A human can read it. A smaller model can follow it. A reviewer can audit it later without reconstructing a hidden state machine.

Dimension`improve`Single-agent coding toolHuman-only workflow
Primary jobWrite a vetted execution planWrite and implement in one passThink and implement manually
Failure modeStops when evidence is weakDrifts into confident guessworkSlow, but usually explicit
ArtifactSelf-contained Markdown planTransient prompt contextNotes, chat, or code review
AuditabilityHighLow to mediumHigh, but expensive
Best useManaged handoff between reasoning and laborFast end-to-end attemptsHigh-stakes judgment and review

The verification gate is what makes the whole thing feel less like a prompt and more like a process. Every step has to tell you what success looks like. If the result diverges, the workflow does not improvise. It stops and returns to judgment.

Why Markdown Beats a Bigger Prompt

A larger prompt can carry more context, but it still collapses once the model loses the thread. Markdown changes the game because it creates a durable handoff artifact. The executor does not need access to every prior reasoning step. It only needs the current plan, the relevant file references, and the verification rules.

That makes the repository resilient in a way most agent systems are not. If the executor stalls, a developer can take over. If the first plan is wrong, the audit trail is still there. The work is not trapped inside a hidden conversation.

The Guardrails Are the Feature

The defensive rules are not filler. They are the product. `improve` explicitly treats repository content as data, not instructions. That matters because codebases are full of hostile or misleading text, from comments to README notes to stale docs.

It also refuses to blur the line between evidence and invention. Secret hygiene is strict. Claims need grounding. When the system does not know enough, the right answer is to stop, not bluff.

What It Beats, and What It Doesn’t

Compared with broad autonomous agents, `improve` is less theatrical and more operational. It does not promise to be the one model that can do everything. It promises to separate thinking from doing well enough that each phase can be trusted on its own terms.

Question`improve`Typical agentGeneric copilot
Who reasons deeply?Advisor modelSame model that writes codeUsually not explicit
Who executes?Cheaper model or humanSame modelThe developer
How much trust comes from structure?A lotSomeLittle
Does it stop on uncertainty?YesSometimesNo, because it usually keeps drafting
What it optimizes forAuditability and handoffAutonomySpeed

That tradeoff is real. This is less magical than end-to-end agents. It is also easier to review, easier to resume, and easier to integrate into an actual engineering team.

Why This Repo Matters Beyond the Repo

`shadcn/improve` reads like a template for how teams should use AI when the stakes are nontrivial. Put judgment where judgment is scarce. Put labor where labor is cheap. Encode the handoff so the work can survive a model failure, a reviewer pass, or a context reset.

That is the bigger idea. The future of useful AI tooling may not be a single brilliant agent. It may be a workflow that knows when to think hard, when to type fast, and when to stop talking and ask a human to take over.