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/<spec>/improve/ 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/v1.0.0/improve-1.0.0.zip

Works with zero configuration. This is the most reliable path and the same one you use to pin a version.

specify extension catalog add \
  https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json \
  --name community --install-allowed
specify extension add improve

Prefer installing and updating by name? Approve the community catalog once, then add and update resolve improve automatically. See install help for why this is needed.

Get started See an example Read the docs

One command
Requires Spec Kit >= 0.2.0
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/<spec>/improve/. 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 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 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.

Command	What it does	Writes
`/speckit.improve`	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/<spec>/improve/*.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 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/ tree, scoped under specs/registry-cli/improve/. 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/registry-cli/improve/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/*/improve/*.md.

Output specs/registry-cli/improve/extract-shadow-config-resolution.md

# Extract shared shadow-config resolution into one utility

## Objective

The logic that resolves a component's shadow registry configuration is
implemented twice: once in `search.ts` and once in `view.ts`. The copies
have already drifted: `search.ts` handles the `registries` override map
while `view.ts` does not. One shared utility removes the class of bug.

## Detailed instructions

### Requirements

- R1: A single utility `resolveShadowConfig(config: Config)` exists in
  `packages/cli/src/utils/resolve-shadow-config.ts`.
- R2: Both `search.ts` and `view.ts` call the utility instead of
  resolving inline.

### Acceptance criteria

- [ ] `pnpm --filter cli typecheck` exits 0
- [ ] `grep -rn "mergeRegistries" packages/cli/src/commands/` returns
      no matches (logic lives only in the utility)

An objective /speckit.specify can derive user scenarios from, numbered testable requirements, machine-checkable acceptance criteria, and a hard out-of-scope list: written for a consumer with zero prior context.

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

Install the extension

You need Spec Kit >= 0.2.0 initialized (specify init) and a git repository. Install directly from the latest release; this needs no catalog setup and is the recommended path:
```
specify extension add improve \
  --from https://github.com/d0whc3r/spec-kit-improve/releases/download/v1.0.0/improve-1.0.0.zip
```
Confirm it registered:
```
cat .specify/extensions/.registry   # 'improve' entry present
ls .specify/extensions/improve      # extension files present
```
Prefer specify extension add improve by name? That needs the community catalog approved first. See install help.
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
```
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/<spec>/improve/; read them, they are meant to be reviewed.
```
plan 1, 3 and 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 so the backlog stays truthful.
```
/speckit.specify <body of extract-shadow-config-resolution.md>
/speckit.improve
```

How it flows

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

you                            the extension                          specs/<spec>/improve/
---                            -------------                          ---------------------

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

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

/speckit.improve (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' is available in the 'community' catalog but installation
is not allowed from that catalog.

To enable installation, add 'improve' to an approved catalog
(install_allowed: true) in .specify/extension-catalogs.yml.

Spec Kit ships the community catalog as discovery only. It carries install_allowed: false by design, so the CLI can list community extensions but will not install one until you opt in. You have two ways to opt in.

Option A: Direct install (recommended)

Install straight from the release archive. No catalog config, always works, and it is the only way to pin a specific version.

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

To update later, run the same command with a newer version URL.

Option B: Approve the community catalog

Do this once if you want to install and update by name. It adds the catalog with install_allowed: true to .specify/extension-catalogs.yml.

specify extension catalog add \
  https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json \
  --name community --install-allowed

specify extension add improve
specify extension update improve

Community extensions are author-maintained and not reviewed by Spec Kit. Review the source before approving a catalog.

More refusal codes and fixes live in Troubleshooting.

Frequently asked questions

Why does specify extension add improve fail?

The extension lives in Spec Kit's community catalog, which is discovery only and carries install_allowed: false. The CLI can list it but will not install until you opt in. Either install directly with --from <release-zip-url>, or approve the community catalog once. Full steps are in install help.

Will it modify my code?

No. The advisor's only writes go to specs/<spec>/improve/, 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 skips the audit when you already know the change you want. /speckit.improve quick keeps a full audit cheap, and /speckit.improve 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 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?

If you approved the community catalog, run specify extension update improve. Otherwise rerun the direct install with the newer release URL. Your specs/ tree is not touched.