The name is the whole thesis: brownfield, not greenfield. A Claude Code plugin that specifies a change to a running system, not a new project from a blank slate.
Two steps inside Claude Code and the plugin is available. After init it samples your code once and writes down the conventions. Then, per change, three commands.
View on GitHub ↗/plugin marketplace add yknnv/brownspec
/plugin install brownspec@brownspec
/brownspec:init # once per repo
/brownspec:spec "" # interview → spec.md
/brownspec:design # blast radius → design.md
/brownspec:tasks # deployable at every step → tasks.md init, edit .brownspec/policies.md by hand — that file is the part the plugin is forbidden to write for youSpec-driven development has converged on three artifacts — requirements, design, tasks — and it converged on them for good reasons. What the tooling assumes is a blank repository: describe what you want, get a spec, generate code.
Then you open the actual repository, and there are sixty services, consumers you did not write, and a change that has to ship without breaking any of them.
The same three artifacts, but for a codebase that already exists. What happens around them is different:
The premise is small: a spec takes five minutes to fix. Code the agent has already written does not.
Every phase appends to a file after every answer. Interrupt and come back later — that is the intended flow.
Six questions, not a forty-field form: the plugin asks only what your repository cannot answer for it. Plus the policies the change touches.
What the change touches: files, public contracts, consumers, migrations, rollback. With provenance — where in the code the conclusion came from.
Ordered steps, each deployable on its own. No "don't deploy for a month and then ship it all in one big release".
If you are starting a new project, use Spec Kit or Kiro. Brownspec's entire first phase is reading code that does not exist yet.
| Greenfield assumed | Reads your conventions | Blast radius | Regulatory profiles | |
|---|---|---|---|---|
| GitHub Spec Kit | yes | no | no | no |
| Kiro (spec mode) | partly | no | no | no |
| Brownspec | no | yes | yes, with provenance | yes, opt-in |
Brownspec skills fire when you ask for a spec. They do not fire when you say "just implement this" — and that is how most work actually arrives.
If you want spec-first to be the default rather than something you remember, say so in CLAUDE.md:
/brownspec:spec → /brownspec:design → /brownspec:tasks, and what is just "do it".## Specs
A change that touches a public contract, a database
schema, or more than one module goes through Brownspec
before any code:
/brownspec:spec → /brownspec:design → /brownspec:tasks,
then implement from tasks.md.
Below that bar — a bug fix, a copy change, a refactor
inside one module — write the code.
If the request is "just do it" and the change is above
the bar, do not start. Say a spec is needed and name
the command.Only public regulations ship with the plugin. Nothing is enabled by default.
The profile policies/ru/152-fz-pdn.md: seven rules on personal data under Russian law. Each is a trigger the spec phase can match, a requirement, and the facts a spec must therefore state.
GDPR is next. Once it is ready, it ships the same way.
A profile applies only once you list it under profiles: in your own policies.md. Until you do, the plugin behaves as though the profile did not exist: no prompts, no sections in the spec, no mention in the output.
Brownspec routes, it does not certify. The output is "this change touches PDN-03, so the spec must therefore state these facts". Whether the implementation actually meets the law is a call for your DPO or your lawyer, not for the plugin.
design.md?conventions.md and policies.md separate files?conventions.md is generated and overwritten freely by the plugin. policies.md is written by people — security, architecture — and is never touched by the plugin. Mixing the two means one regeneration silently deletes a security control and leaves a plausible-looking document behind./brownspec:init, list the profile you need under profiles: in your .brownspec/policies.md — e.g. ru/152-fz-pdn. Until you list it, the plugin behaves as though the profile did not exist: no prompts, no sections in the spec, no mention in the output. Brownspec routes, it does not certify — it points at articles, it does not replace a lawyer./plugin marketplace add yknnv/brownspec, then /plugin install brownspec@brownspec. Once per repo: /brownspec:init — the plugin samples the code and writes conventions.md. Then per change: /brownspec:spec "" → /brownspec:design → /brownspec:tasks. Every phase writes to disk after every answer, so an interview survives an interrupted session.