The Planner-Executor Pattern for AI Coding (with shadcn/improve)

Most AI coding sessions send every task to one model. The same expensive frontier model that understands your codebase also writes the mechanical edits. The planner-executor pattern separates these two jobs, sending planning to a capable model that audits the codebase and writes self-contained implementation plans, while execution goes to a cheaper model. shadcn/improve is a one-command Claude Code skill that implements this pattern. This guide covers how the pattern works, how to install and run shadcn/improve, and when the split is worth doing.

The cost problem with using one model for everything

Claude Fable 5 costs $10/MTok input and $50/MTok output. Claude Haiku 4.5 costs $1/MTok input and $5/MTok output, a 10x gap on both sides. In a typical coding session, most tokens go to mechanical execution (reading files, applying edits, running verification commands). Only the planning phase requires the reasoning capacity you are paying for with a frontier model.

Routing execution to Haiku 4.5 while keeping planning on Fable 5 can cut per-session costs significantly for any non-trivial codebase audit.

What the planner-executor pattern is

The pattern splits reasoning into two phases. The plan phase generates a fixed sequence of actions before seeing any untrusted data. The execution phase runs that sequence, where tool outputs can shape parameters but cannot change which tools run or what gets implemented.

This separation protects control-flow integrity (untrusted content from the codebase cannot redirect the agent into unintended operations) and concentrates the expensive reasoning into one bounded pass.

How planning improves task completion rates

Planning before execution improves tool use accuracy from 72% to 94% (Parisien et al., 2024, "Deliberation Before Action: Language Models with Tool Use"). It also improves task completion rates by 40–70% and reduces hallucinations by around 60%.

Boris Cherny (Anthropic) on Claude Code plan mode: "Plan mode can 2-3x success rates pretty easily if you align on the plan first." As models improve, the boundary shifts: "The boundary changes with every model... newer models are more intelligent so the boundary of what you need plan mode for got pushed out."

The Research-Plan-Implement workflow

Pasi Huuhka (Microsoft Azure MVP, Feb 2026) describes a scaled version of the pattern where small tasks go straight to the coding agent, medium tasks add a planning pass, and larger or riskier work follows the full research → plan → implement flow. The key insight is where most of the thinking should happen: "This is probably the cheapest point in the whole process to catch misunderstandings... I would much rather spend the extra few minutes in the planning stage than later do a half-implementation, realize the feature shape was wrong, and start steering it back."

shadcn/improve: a planner-executor skill for Claude Code

shadcn/improve is a Claude Code skill by shadcn, released June 10 2026, MIT license. It audits any codebase and writes implementation plans for other agents to execute. The skill never implements anything itself. The only files it creates or modifies live under plans/ in the repo root.

How to install shadcn/improve

npx skills add shadcn/improve

Works in any agent that supports Agent Skills format. Plans are plain markdown, so any agent or human can pick them up.

Hard rules the skill enforces:

• Never modifies source code. Writes go to plans/ only; executors edit in disposable worktrees.
• Never runs commands that mutate your working tree.
• Never reproduces secret values — credential locations and types only.
• If asked to implement directly, it declines and points at the plan.

How to run a full audit

A typical first run, start to finish:

1. Open your agent in the repo and run /improve (or /improve quick to keep it cheap).
2. It maps the repo and audits it, then returns a vetted findings table. Reply with which ones you want planned: "plan 1, 3 and 5".
3. Plans land in plans/, one file per finding, plus an index with the recommended order. They are meant to be read and reviewed before execution.
4. Hand a plan to any agent (implement plans/001-*.md), or let the skill dispatch an executor by running /improve execute 001. It runs a cheaper model in an isolated worktree, reviews the diff, and reports a verdict. Merging is always your decision.
5. Next session, run /improve reconcile to process the backlog. It verifies what landed, refreshes what drifted, and unblocks what is stuck.

Here is what a vetted findings table looks like, from the README's shadcn/ui example:

Rejected findings are recorded with reasons so they don't resurface next run:

- [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention,
  every CLI honors it. Not a finding.

What the nine audit categories cover

The audit fans out parallel subagents across nine categories: correctness/bugs, security, performance, test coverage, tech debt and architecture, dependencies and migrations, DX and tooling, docs, and direction (feature suggestions). The Recon phase runs first. It reads the repo's README, CLAUDE.md/AGENTS.md, CI config, and directory structure, then identifies the exact build/test/lint commands, which become verification gates in every plan.

Audit depth options

What the generated plans look like

Plans are written for the weakest plausible executor, a model that has never seen the advisor session and may be much smaller. Three properties make them executable:

• Self-contained. All context is inlined: exact file paths, current-state code excerpts, repo conventions with an exemplar file, verified commands. No references to "as discussed above."
• Verification gates. Every step ends with a command and its expected output. Done criteria are machine-checkable. The executor never has to judge whether it succeeded.
• Hard boundaries. Explicit out-of-scope lists and STOP conditions — "if X, stop and report" — instead of letting a small model improvise when reality doesn't match the plan.

Each plan stamps the git commit it was written against, so the executor runs a mechanical drift check before touching anything. Plans land in plans/ with an index covering priority order, dependency graph, and status.

Executing and closing the loop

/improve execute <plan> spawns a cheaper executor subagent in an isolated git worktree, hands it the plan, and then reviews the result like a tech lead, re-running every done criterion, checking scope compliance, and reading the diff against intent. It returns one of three verdicts: approve (merging stays your call), send back for revision (max 2 rounds), or block and refine the plan.

/improve reconcile processes what happened since last session. It verifies DONE plans still hold, investigates BLOCKED ones and rewrites around the obstacle, refreshes drifted plans, and retires findings that got fixed independently.

/improve ... --issues publishes plans as GitHub issues with the same self-contained body, so any agent or human can pick them up where work already lives.

All shadcn/improve subcommands

When to use the planner-executor split

The split pays off when the task is large enough that planning takes a small fraction of total session time, and when the implementation can be fully specified before execution starts. Good fits include auditing an unfamiliar codebase, recurring review workflows, and any session where you expect multiple rounds of execution across a known action set.

Skip it for real-time chat and single-turn tasks where decomposition takes longer than just executing, for latency-sensitive work where the plan-execute round trip adds meaningful delay, and for tasks where requirements are unclear until you start. In that last case, the interleaved loop is better because feedback from execution shapes the next decision.

Huuhka's principle applies regardless of model tier: "One thing I don't do is generate a plan and then treat it as a decorative artifact. I read the plans. I discuss them with the planning agent. I answer the open questions." The plan is a real handoff artifact. Its quality determines whether the executor succeeds or drifts.

Summary

The planner-executor pattern works because planning requires judgment and codebase understanding, while execution requires reliable instruction-following. shadcn/improve packages this as a single install with a five-step workflow (audit, vet, plan, execute, reconcile). The 10x price gap between Fable 5 and Haiku 4.5 makes the model split economically meaningful for any non-trivial session, and the plan files are plain markdown that any agent or human can act on independently.