Source stays canonical
spec.md and plan.md are read-only to the extension. Every
artifact lands under product/ in the same feature directory. Regenerate
any time the source changes.
A Spec Kit extension
Turn your engineering spec into product artifacts stakeholders actually read.
Product Spec Extension reads the spec.md and plan.md you
already have and generates four audience-specific documents: a stakeholder summary, a
full product spec, a delivery plan, and a technical design. Each one ships with a
quality checklist. Your source files are never modified.
Install with Spec Kit
specify extension add product \
--from https://github.com/d0whc3r/spec-kit-product/releases/download/v2.2.0/product-2.2.0.zipWorks with zero configuration. Change the version in the URL to pin a release.
specify extension add product --force \
--from https://github.com/d0whc3r/spec-kit-product/releases/download/v2.2.0/product-2.2.0.zip
Run the install command again with --force to replace an installed
version. Your generated product/ files do not change.
- 3 commands
- Requires Spec Kit >= 0.12.17
- MIT licensed
- Writes in the language of your spec
- No em dashes, plain language
Why this exists
spec.md is written for engineers. Product managers, leadership, designers,
and cross-functional reviewers need the same information in a different shape. Rewriting
that by hand for every feature is busywork and drifts from the canonical spec. This
extension generates the audience-specific views for you, from the spec you already
wrote.
Built-in quality checklist
Every command updates a shared checklist.md. A failed Required item is
your signal to regenerate, so the output stays trustworthy.
Proven conventions
Output follows Working Backwards (PRFAQ), Jobs to Be Done, Gherkin BDD, and Lean PRD conventions, in plain language with a strict no em dash style. The plan and design views embed Mermaid diagrams that render only when they earn their place, never as decoration.
The commands
Each command stands alone and reads from a feature directory under
specs/. Stop at the level of detail your audience needs.
This page uses the slash-command names, such as /speckit.product.brief.
Skills agents, such as Claude Code, use hyphens instead:
/speckit-product-brief.
| Command | Reads | Writes | Audience |
|---|---|---|---|
/speckit.product.brief |
spec.md |
product/00-info.md, product/10-spec.md |
Any stakeholder, PMs, leadership |
/speckit.product.plan |
plan.md, spec.md |
product/20-plan.md |
PMs, engineering leads |
/speckit.product.design |
plan.md, spec.md, optional more |
product/30-design.md |
Tech leads, senior developers |
All three also update the shared product/checklist.md. None of them modify
spec.md, plan.md, or any other source file. Pass
--feature-dir specs/<dir> to target a specific feature instead of the
active one.
The commands accept a spec in any language and write in the language of its prose. Pass
--lang <language>, such as --lang zh-CN, to choose
another one.
Spec Kit offers each command as an optional hook. After
/speckit.specify and /speckit.clarify it offers
/speckit.product.brief. After /speckit.plan it offers
/speckit.product.plan, then /speckit.product.design.
See it in action
Spec Kit's spec.md and plan.md go in. Four audience-specific
artifacts come out, each with the open clarifications surfaced and the style rules
enforced. Below are two real, end-to-end examples, rendered straight from the files in
the
examples folder. Pick a feature, then a command to see what it wrote, and open the full file.
Input
spec.md
# Feature Specification: Per-Tenant API Rate Limiting
**Status**: Draft
## Clarifications
### Session 2026-05-29
- Q: At what share of the monthly quota should the dashboard "approaching
limit" warning appear? → A: 80% of the monthly quota.
- Q: What peak scale should the load tests target? → A: ~5,000
requests/sec aggregate across thousands of tenants.
## User Scenarios & Testing
### User Story 1 - Per-minute burst protection (Priority: P1)
A customer organization sends a sudden spike of API requests. The platform
caps how many requests that organization can make within any single minute.
Once the cap is reached, further requests are rejected with a clear 429
response and a Retry-After header.
Input
plan.md
# Implementation Plan: Per-Tenant API Rate Limiting
**Branch**: `001-tenant-rate-limiting` | **Spec**: spec.md
## Summary
Enforce two independent rate limits per customer organization: a per-minute
burst limit and a monthly request quota. Over-limit requests get a 429 with a
`Retry-After` header. Enforcement happens at an API gateway middleware that
checks two atomic counters in Redis; policy and audit trail live in
PostgreSQL.
## Technical Context
**Language/Version**: Python 3.12
**Primary Dependencies**: FastAPI, redis-py, SQLAlchemy + Alembic, Pydantic v2
**Storage**: Redis 7 for counters; PostgreSQL 16 for policy and audit trail
**Performance Goals**: rate-limit check adds < 5 ms p95; sustain 5k req/s
Output
product/00-info.md
# Product Info: Per-Tenant API Rate Limiting
## Overview
Per-Tenant API Rate Limiting gives every customer organization its own
request limits so that one organization's traffic cannot slow the service
for others. It pairs a short-term burst limit with a monthly quota and shows
each customer their own usage.
## What is Changing
- Each organization gets a per-minute burst limit and monthly quota.
- Over-limit requests return a clear refusal with a retry time.
- The dashboard shows used, remaining, reset date, and burst limit.
- The dashboard warns when usage reaches 80% of quota.
## Key Decisions
**Approaching-limit warning threshold**
The dashboard warns a customer once usage reaches 80% of the monthly quota.Three-sentence overview, short bullets, decisions surfaced for review. No implementation detail.
Output
product/10-spec.md
## Users
- **Customer developer**: Builds on the platform API. Cares about predictable, uninterrupted access.
- **Customer admin**: Watches their organization's usage. Wants to avoid surprise limits.
- **Support or operations staff**: Manage customer limits. Want to resolve requests fast.
## Problem (Job to Be Done)
> When I depend on a shared platform for my organization's work, I want to keep my request capacity fair and predictable, so I can rely on the service even when other customers spike.A Job to Be Done statement and named personas. The PRD voice the checklist enforces.
Output
product/20-plan.md
## Summary
This feature adds per-customer request limits to a shared service API. Each
customer organization gets a per-minute burst limit and a monthly request
quota, enforced at a single checkpoint every request passes through. The
problem and audience live in the spec; the plan covers approach and delivery.
## Goals and Non-Goals
**Goals**:
- Each organization is protected by its own per-minute and monthly limits.
- One organization's traffic never affects another's accepted requests.
- Over-limit callers get a clear response and a retry time.No file paths, no code, no time estimates. The voice a PM can read aloud.
Output
product/30-design.md
## Architectural Approach
The core of the design is an enforcement middleware placed at the front of
the request pipeline, after authentication and before application handlers.
It resolves the tenant, then asks the limiter for a decision. Because it sits
at a single choke point, no individual handler needs to know about limiting.
## Technical Constraints
- Counters must be atomic to stay within 1% accuracy under concurrency.
- Admin limit changes must take effect within one minute.
- Rate-limit check adds under 5 ms at p95 latency.Component-level detail. No code, no line-by-line implementation.
Output
product/checklist.md
# Product Quality Checklist: Per-Tenant API Rate Limiting
## Info (`product/00-info.md`)
- [x] Overview is four sentences or fewer
- [x] No em dash
- [x] No AI tells
- [x] No implementation detail
## Spec (`product/10-spec.md`)
- [x] Problem section contains a Job to Be Done statement
- [x] Use Cases follow Given/When/Then
- [ ] No AI tell filler phrasesAuto-validated items are checked; items that need a human eye stay unchecked.
Input
spec.md
# Feature Specification: Self-Serve Billing Usage Dashboard
**Status**: Draft
## User Scenarios & Testing
### User Story 1 - Current cost and projected bill (Priority: P1)
An organization admin opens the billing dashboard and immediately sees their
current plan, how much of their included allowance they have used this period,
and a projected total for the end of the period, including any projected
overage.
Input
plan.md
# Implementation Plan: Self-Serve Billing Usage Dashboard
**Branch**: `002-billing-usage-dashboard` | **Spec**: spec.md
## Summary
A read-oriented billing API aggregates from an existing metering source and a
durable store of plans, invoices, alert rules, and cached projections.
Usage-by-team and the account total come from one aggregation pass so the parts
always reconcile.
## Technical Context
**Performance Goals**: dashboard overview returns within 1 s p95
Output
product/00-info.md
# Product Info: Self-Serve Billing Usage Dashboard
## Overview
This feature gives organization admins a read-only billing dashboard for
current costs, usage, projected overage, and invoice history. It addresses
surprise bills by showing what is driving charges.
## What is Changing
- Admins see current usage against plan allowances.
- Projected overage appears before the bill closes.
- Charge changes are explained by team and dimension.
- Past invoices can be reviewed and exported.Three-sentence overview, short bullets, risks surfaced for review. No implementation detail.
Output
product/10-spec.md
## Users
- **Organization admin**: runs the account; wants no surprise bills.
- **Billing owner**: holds the billing role; tracks spend and overages closely.
- **Finance teammate**: reconciles invoices; needs exportable, accurate records.
## Problem (Job to Be Done)
> When I am responsible for my organization's bill, I want to understand and predict what we will owe, so I can avoid surprise charges and act before costs climb.A Job to Be Done statement and named personas. The PRD voice the checklist enforces.
Output
product/20-plan.md
## Summary
This feature gives organization admins a read-only billing dashboard that
shows the current plan, current-period usage, projected overage, invoice
history, team-level usage, and alert activity.
## Goals
- Show current plan and allowance usage.
- Separate included price from projected overage.
- Explain charge changes by team and dimension.
- Send one alert per threshold and period.No file paths, no code, no time estimates. The voice a PM can read aloud.
Output
product/30-design.md
## Architectural Approach
The dashboard adds a frontend page composed of cost overview, team usage,
alerts, invoice history, and empty-state components. The page calls four read
API surfaces plus an invoice export operation.
The API layer resolves the organization from the authenticated session and
gates access to admins or billing-role users. Operations delegate billing logic
to services rather than reading upstream systems directly.Component-level detail. No code, no line-by-line implementation.
Output
product/checklist.md
# Product Quality Checklist: Self-Serve Billing Usage Dashboard
## Info (`product/00-info.md`)
- [x] Overview is four sentences or fewer
- [x] No em dash
- [x] No implementation detail
## Spec (`product/10-spec.md`)
- [x] Problem section contains a Job to Be Done
- [x] Use Cases follow Given/When/Then
- [x] No AI tellsAuto-validated items are checked; items that need a human eye stay unchecked.
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.12.17 initialized (
specify init). Install directly from the latest release:specify extension add product \ --from https://github.com/d0whc3r/spec-kit-product/releases/download/v2.2.0/product-2.2.0.zipConfirm it registered:
cat .specify/extensions/.registry # 'product' entry present ls .specify/extensions/product # extension files presentSkills-based agents, such as Claude Code and Copilot, name the commands
/speckit-product-brief,/speckit-product-plan, and/speckit-product-design. Codex uses a$prefix, such as$speckit-product-brief. -
Create a feature
Run the Spec Kit core command and fill in the generated
spec.md. The product commands refuse to run on an unfilled spec./speckit.specify -
Generate your first artifacts
Run
/speckit.product.brieffirst. It writesproduct/00-info.md,product/10-spec.md, andproduct/checklist.md./speckit.product.brief -
Generate the full set
After you have a Spec Kit
plan.md(run/speckit.plan), add the plan and design views./speckit.product.plan /speckit.product.design
How it flows
Input flows from the Spec Kit core commands into this extension. No two commands write to the same output file.
Spec Kit core This extension
--------------- -----------------------------------------------
/speckit.specify --> spec.md --> /speckit.product.brief +-> product/00-info.md
\-> product/10-spec.md
/speckit.plan --> plan.md --> /speckit.product.plan -> product/20-plan.md
\---> /speckit.product.design -> product/30-design.md
All three also write to: product/checklist.md
The product/ folder is self-contained. Zip it, attach it to a doc, paste it
into a slide deck. No engineering scaffolding needs to travel with it.
Install help
If specify extension add product stops with the error below, this is the
fix. It is expected behavior, not a broken release.
The error you may see
Error: 'product' 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. Run
specify extension search product or
specify extension info product to see the entry, then install from the
release archive.
More refusal codes and fixes live in Troubleshooting.
Frequently asked questions
Why does specify extension add product fail?
The extension is listed in Spec Kit's community catalog, which is discovery only and
carries install_allowed: false. Spec Kit shows the extension but does
not install it from that catalog. Install directly with
--from <release-zip-url>. Full steps are in
install help.
Do I have to run all three commands?
No. Stop at the level of detail your audience needs. A change that needs stakeholder
buy-in and a full product spec is just
/speckit.product.brief. A feature in active build adds
plan and design.
Will it modify my spec.md or plan.md?
No. The source files are read-only to this extension. Every artifact lives under
product/ in the same feature directory. This is enforced by the command
body and the constitution.
What happens to [NEEDS CLARIFICATION] markers in spec.md?
They are surfaced in the generated output as open product questions, never silently resolved. The relevant artifact lists them under a "Key Decisions" or "Risks and Open Questions" section.
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 product. Otherwise rerun the direct install
with the newer release URL. Your generated product/*.md files are not
touched.
Does it work with a spec that is not in English?
Yes. The commands accept a spec in any language, or in a mix of languages, and write
each document in the dominant language of the spec prose. Headings, labels, and
Gherkin keywords are translated. Code, file names, and
[NEEDS CLARIFICATION] markers stay as they are. Pass
--lang <language> to choose the output language yourself.
Does this work in a brownfield codebase?
Yes. The product commands operate on a spec.md, so they work the same
way whether the spec describes a greenfield feature or an existing system. Produce
the spec.md however you like (for example with
/speckit.specify), then run the product commands against it.
More answers in the full FAQ.