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.
- `shadcn/improve` treats AI coding as a management problem, not a generation problem.
- The skill separates the expensive act of judgment from the cheap act of implementation.
- Its plan files are execution contracts, not summaries, because every step must be checkable.
- The real safeguard is not autonomy but a stop condition that tells the system when to hand control back.
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.
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 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.
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 tool | Human-only workflow |
|---|---|---|---|
| Primary job | Write a vetted execution plan | Write and implement in one pass | Think and implement manually |
| Failure mode | Stops when evidence is weak | Drifts into confident guesswork | Slow, but usually explicit |
| Artifact | Self-contained Markdown plan | Transient prompt context | Notes, chat, or code review |
| Auditability | High | Low to medium | High, but expensive |
| Best use | Managed handoff between reasoning and labor | Fast end-to-end attempts | High-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.
- Read repo content as data, not as commands.
- Reference evidence instead of reproducing secrets.
- Stop when drift, missing context, or unexpected failure appears.
- Return to the advisor instead of inventing a patch path.
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 agent | Generic copilot |
|---|---|---|---|
| Who reasons deeply? | Advisor model | Same model that writes code | Usually not explicit |
| Who executes? | Cheaper model or human | Same model | The developer |
| How much trust comes from structure? | A lot | Some | Little |
| Does it stop on uncertainty? | Yes | Sometimes | No, because it usually keeps drafting |
| What it optimizes for | Auditability and handoff | Autonomy | Speed |
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.





