A Spec Kit extension

The expensive model writes the spec prompt. The spec-kit lifecycle writes the code.

Improve Extension audits your codebase as a read-only senior advisor. It presents a leverage-ordered findings table with file:line evidence, and turns the findings you pick into self-contained spec prompts under specs/improves/ that the spec-kit lifecycle can process. It never modifies source code itself. The prompt is the product.

Install with Spec Kit
specify extension add improve \
  --from https://github.com/d0whc3r/spec-kit-improve/releases/download/v2.0.0/improve-2.0.0.zip

Works with zero configuration. Change the version in the URL to pin a release.

  • One command
  • Requires Spec Kit >= 0.12.17
  • MIT licensed
  • Never edits your source

Why this exists

Model intelligence is priced per token, and most of an implementation session spends those tokens on mechanical work. The part where a strong model earns its price is understanding a codebase, judging what matters, and specifying the change. This extension keeps the expensive model on that part and hands the execution to the spec-kit pipeline.

Read-only by contract

The advisor's only writes go to specs/improves/. It never edits source code and never runs commands that mutate your working tree. Ask it to implement something and it declines and points at the prompt; handing it to /speckit.specify (/speckit-specify in skills-based agents) is how it becomes code.

Findings with evidence

The audit covers nine categories: correctness, security, performance, tests, tech debt, dependencies, DX, docs, and direction. Every finding is vetted by re-reading the cited code before it reaches you, in a leverage-ordered table with file:line references.

Prompts built for spec-kit

Each spec prompt carries current-state code excerpts, numbered testable requirements, machine-checkable acceptance criteria, and hard scope boundaries. It stamps the commit it was written against in its frontmatter, so drift is detected before the prompt is processed.

One command

/speckit.improve.run runs the full audit-to-prompts workflow, or specs a single known change when you name it. From there you hand each prompt to /speckit.specify, and a later re-run keeps the backlog truthful between sessions. Skills-based agents, such as Claude Code and Copilot, name the command /speckit-improve-run. Codex names it $speckit-improve-run.

Command What it does Writes
/speckit.improve.run Full audit: recon, parallel category audit, vetted findings table, spec prompts for the findings you pick. Pass a change description instead to skip the audit and write a single prompt for just that change. A re-run dedupes against existing prompts and refreshes any that drifted. specs/improves/*.md

Modifiers compose: quick or deep set the effort, a category name (security, perf, tests, ...) focuses on one area, branch audits only what the current branch changes, next suggests feature direction, and --issues also publishes prompts as GitHub issues. For example: /speckit.improve.run quick security.

Each TODO prompt is a feature description for /speckit.specify: hand it the prompt body, then carry the generated spec through /speckit.clarify, /speckit.plan, /speckit.tasks, and /speckit.implement.

See it in action

A real audit of a TypeScript monorepo: a component registry CLI plus its documentation site. The advisor presented the findings table on the left; the file on the right is the spec prompt that landed in the target repo's specs/improves/ folder. Everything is rendered straight from the files in the examples folder. Pick a view, read the excerpt, and open the full version.

Audit output the findings table
## The findings table (what the audit presented)

After recon, a parallel category audit, and a vetting pass, the advisor
presented this leverage-ordered table:

| # | Finding | Category | Impact | Effort | Risk | Confidence |
| - | ------- | -------- | ------ | ------ | ---- | ---------- |
| 1 | Shadow-config resolution duplicated in `search.ts`/`view.ts`, copies already drifted | tech-debt | HIGH | M | LOW | HIGH |
| 2 | O(n^2) icon migration loop (`migrate-icons.ts:168`) | perf | MED | S | LOW | HIGH |
| 3 | Registry fetch swallows HTTP errors, CLI reports "0 components" instead of failing | bug | HIGH | S | LOW | HIGH |
| 4 | No characterization tests on the config resolver feeding findings 1 and 3 | tests | HIGH | M | LOW | HIGH |

...and rejected a few, with reasons recorded in the final report so they
don't come back next run.

Every finding cites the code it came from. You reply with the ones to plan, for example "plan 1, 3 and 4".

Output specs/improves/001-extract-shadow-config-resolution.md
---
status: TODO
priority: P1
effort: M
risk: LOW
category: tech-debt
depends: []
planned_at: 4f9c2e1
issue: ""
---

# Extract shared shadow-config resolution into one utility

Each prompt is self-indexing: the frontmatter carries status, priority, dependencies, and the commit it was planned against. There is no separate index file; commands discover the backlog by globbing specs/improves/*.md.

The snippets above are excerpts. Hit View full file to read the whole artifact rendered in place, or browse every file on the Examples page in the wiki.

Get started in five minutes

  1. Install the extension

    You need Spec Kit >= 0.12.17 initialized (specify init) and a git repository. Install directly from the latest release:

    specify extension add improve \
      --from https://github.com/d0whc3r/spec-kit-improve/releases/download/v2.0.0/improve-2.0.0.zip

    Confirm it registered:

    cat .specify/extensions/.registry   # 'improve' entry present
    ls .specify/extensions/improve      # extension files present

    Skills-based agents, such as Claude Code and Copilot, name the command /speckit-improve-run. Codex names it $speckit-improve-run.

  2. Run your first audit

    Run the audit in your Spec Kit-aware assistant. Add quick to keep it cheap, deep to cover every package and category.

    /speckit.improve.run
  3. Pick findings and read the prompts

    The audit ends with a leverage-ordered findings table. Reply with the ones you want planned. Spec prompts land under specs/improves/; read them, they are meant to be reviewed.

    plan 1, 3 and 4
  4. Hand off and re-run

    Hand a prompt's body to /speckit.specify, then carry the generated spec through the standard lifecycle (/speckit.clarify, /speckit.plan, /speckit.tasks, /speckit.implement). Next session, re-run /speckit.improve.run so the backlog stays truthful.

    /speckit.specify <body of extract-shadow-config-resolution.md>
    /speckit.improve.run

How it flows

Every command reads the repository and writes only under specs/improves/. Turning a prompt into code belongs to the spec-kit lifecycle, and merging is always your decision.

you                            the extension                          specs/improves/
---                            -------------                          ---------------

/speckit.improve.run          -->  recon -> audit -> vet -> confirm -->  <NNN>-<plan-name>.md (status TODO)
                                       (you pick the findings)

/speckit.improve.run <desc>   -->  recon -> targeted investigation  -->  <NNN>-<plan-name>.md (status TODO)

/speckit.improve.run (re-run) -->  dedupe + drift-refresh           -->  refreshed prompts (or REJECTED)

then hand off each TODO prompt to the spec-kit lifecycle:

/speckit.specify <prompt body> --> /speckit.clarify --> /speckit.plan --> /speckit.tasks --> /speckit.implement

Each prompt stamps the git commit it was written against in its planned_at frontmatter field, so a re-run detects drift mechanically before you hand a prompt off. Status values: TODO, DONE, REJECTED.

Install help

If specify extension add improve stops with the error below, this is the fix. It is expected behavior, not a broken release.

The error you may see

Error: 'improve' was found in the 'community' catalog, which is discovery-only
...
Don't flip such a catalog to install_allowed.

Spec Kit lists community extensions in a discovery-only catalog. That catalog has install_allowed: false, so Spec Kit does not install from it. Spec Kit also advises against changing that setting. Install from the release archive instead.

Install a release

Install straight from the release archive. Spec Kit asks you to confirm the source. Change the version in the URL to pin a release.

specify extension add improve \
  --from https://github.com/d0whc3r/spec-kit-improve/releases/download/v2.0.0/improve-2.0.0.zip

Community extensions are author-maintained, and Spec Kit does not review them. Review the source before you install.

Update to a newer release

Run the install command with the newer release URL and add --force to replace the installed version.

specify extension add improve --force \
  --from <newer-release-zip-url>

Your specs/ tree does not change.

More refusal codes and fixes live in Troubleshooting.

Frequently asked questions

Why does specify extension add improve fail?

The extension is listed in Spec Kit's community catalog, which is discovery only (install_allowed: false). The CLI shows it but does not install it. Install directly with --from <release-zip-url>. Full steps are in install help.

Will it modify my code?

No. The advisor's only writes go to specs/improves/, and it never runs commands that mutate your working tree. Code changes happen through the standard spec-kit lifecycle (/speckit.implement), which is always under your control. Ask the advisor to implement something directly and it declines and points at the prompt.

Who turns a prompt into code?

The spec-kit lifecycle. Hand a TODO prompt's body to /speckit.specify, which generates the feature spec, then carry it through /speckit.clarify (which resolves any gap the spec dropped), /speckit.plan, /speckit.tasks, and /speckit.implement. Prompts are also self-contained enough to hand to any agent or person, or to publish as GitHub issues.

Do I have to run the full audit every time?

No. Passing a change description to /speckit.improve.run skips the audit when you already know the change you want. /speckit.improve.run quick keeps a full audit cheap, and /speckit.improve.run branch scopes it to what your current branch changes, which is useful before a PR.

What if the code changed since a prompt was written?

Each prompt stamps the commit it was written against in its frontmatter, and a re-run of /speckit.improve.run runs a mechanical drift check before writing anything new. The re-run refreshes drifted prompts and marks REJECTED any finding that no longer holds. Re-run it before you hand a prompt to /speckit.specify.

What happens if the audit finds credentials?

It reports the file:line location and the credential type, never the value, and recommends rotation.

Does the extension run by itself?

No. The commands are Markdown prompts. They need a Spec Kit-aware assistant to resolve and execute them. The release zip is portable and has no runtime of its own.

How do I update the extension?

Rerun the direct install with the newer release URL and add --force. Your specs/ tree does not change.

More answers in the full FAQ.