improve README

The project's README from github.com/shadcn/improve. As one markdown file: README.md.

improve

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

The idea: use your most capable model for the part where intelligence compounds — understanding the codebase, judging what's worth doing, writing the spec — and hand execution to cheaper models. The skill never implements anything itself. The plan is the product.

you          →  /improve                    (expensive model, advises)
plans/       →  001-fix-n-plus-one.md       (self-contained specs)
other agent  →  implements, tests, ships    (cheap model, executes)

Install

npx skills add shadcn/improve

Works in any agent that supports Agent Skills format. The plans it writes are plain markdown, so any agent (or human) can pick them up.

Usage

/improve                        full audit → prioritized findings → plans
/improve quick                  cheap pass: hotspots, top findings only
/improve deep                   exhaustive: every package, every category
/improve security               focused audit (also: perf, tests, bugs, ...)
/improve branch                 audit only what the current branch changes
/improve next                   feature suggestions — where to take the project
/improve plan <description>     skip the audit, spec one thing
/improve review-plan <file>     critique and tighten an existing plan
/improve execute <plan>         dispatch a cheaper executor, review its work
/improve reconcile              refresh the backlog: verify, unblock, retire
/improve ... --issues           also publish plans as GitHub issues

How to use

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, audits it, and comes back with a findings table. Reply with the ones you want planned — "plan 1, 3 and 5".
  3. Plans land in plans/ — one file each, plus an index with the recommended order. Read them; they're meant to be reviewed.
  4. Hand a plan to any agent ("implement plans/001-*.md"), or let the skill run it: /improve execute 001. It dispatches a cheaper model in an isolated worktree, reviews the diff against the plan, and reports back with a verdict. Merging stays up to you.
  5. Next session, run /improve reconcile to clean up the backlog: verify what landed, refresh what drifted, unblock what got stuck.

Before a PR, /improve branch does the same thing scoped to just what your branch changes.

Example

A run against shadcn/ui came back with findings like:

| # | Finding                                        | Category  | Effort | Confidence |
|---|------------------------------------------------|-----------|--------|------------|
| 1 | shadow-config duplicated in search.ts/view.ts, | tech-debt | M      | HIGH       |
|   | copies already drifted (TODO at search.ts:31)  |           |        |            |
| 2 | O(n²) icon migration (migrate-icons.ts:168)    | perf      | S      | HIGH       |

…and rejected a few, with reasons recorded so they don't come back next run:

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

Picking #1 produced this plan — current code excerpted, exact steps, the repo's own test/lint commands as verification gates, and STOP conditions for when reality doesn't match.

How it works

Recon. Maps the repo: stack, conventions, and the exact build/test/lint commands — these become verification gates in every plan. It also ingests intent and design docs when present — ADRs (docs/adr/), PRDs, CONTEXT.md, DESIGN.md, PRODUCT.md — so decided tradeoffs aren't re-flagged as findings, direction suggestions stay grounded in stated product intent, and plans speak the repo's own vocabulary. Composes with any repo that already maintains these docs.

Audit. Fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction (feature suggestions — every one must cite evidence from the repo itself, no generic idea-slop). Every finding carries file:line evidence, impact, effort, and confidence.

Vet. Subagents over-report, so the advisor re-reads every cited location itself before showing you anything — false positives get dropped, wrong attributions get corrected, rejections get recorded.

Prioritize. Findings land in a table ordered by leverage (impact ÷ effort, weighted by confidence). You pick what becomes plans.

Plan. One file per selected finding, written into plans/ with an index, priority order, and dependency graph.

What makes the plans executable

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

Each plan also stamps the git commit it was written against, so executors run a mechanical drift check before touching anything.

Closing the loop

Plans aren't fire-and-forget:

Hard rules

License

MIT © shadcn

improve (shadcn/improve)

Searching Database…

9.2K ·GitHub
Improve
Что это?Это скилл для агента, который проводит аудит любой кодовой базы и пишет планы внедрения, которые выполняют другие, более дешёвые модели, — дорогая модель думает, дешёвые печатают.
Это отдельное приложение или то, что я загружаю в своего кодинг-агента?Это Agent Skill — простой markdown-файл скилла, загружаемый в любого агента с поддержкой формата Agent Skills, а не отдельный устанавливаемый инструмент.
Как запустить его на своём репозитории?Откройте агента внутри репозитория и запустите /improve (или /improve quick для более дешёвого прохода); он составит карту и аудит репозитория, а затем вернёт таблицу находок, из которой вы выбираете пункты для генерации планов в plans/.
Какие агенты могут запускать этот скилл?Загрузить его может любой кодинг-агент, реализующий формат Agent Skills; поскольку результат — простой markdown, полученные планы смогут подхватить любой агент или человек.
Трогает ли он вообще мой исходный код?Нет — он пишет только в plans/, никогда не изменяет вашу рабочую копию, и даже выполнение происходит в одноразовом git worktree, который вам ещё предстоит смержить самому.
Какие области охватывает аудит?Он запускает параллельные сабагенты по девяти категориям: корректность, безопасность, производительность, покрытие тестами, техдолг, зависимости и миграции, DX, документация и направление (предложения фич, которые обязаны ссылаться на доказательства из репозитория).
Как планы делают выполнимыми для более слабых моделей?Планы самодостаточны: со встроенными фрагментами кода и точными командами, машинно-проверяемыми верификационными воротами и жёсткими условиями STOP, чтобы меньшая модель-исполнитель никогда не импровизировала.
Что происходит при запуске /improve execute?Он порождает более дешёвого сабагента-исполнителя в изолированном git worktree для реализации плана, затем проверяет diff по плану как тимлид и возвращает вердикт: approve, возврат на доработку или block.
Раскрывает ли он мои секреты при аудите?Нет — он никогда не воспроизводит значения секретов; в находках фиксируются только расположение и типы учётных данных, и всегда рекомендуется их ротация.
What are similar projects?pi-shadow-mind, reclaim-code-entropy, pstack, Coding-Agent-Skills, oh-my-subagents, repowise, DualForge-Workflow, pstack-claude
Which topics is it in?planning, code-quality, code-review, static-analysis, agent-skill, workflow, orchestration, multi-agent, documentation, coding-agent, markdown, productivity
Creator
shadcn
Size
<0.1 MB
Stars
9.2K
Updated
CommitSep 12
Age
4mo
Commits · 90 Days