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/v0.9.0/product-0.9.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 product

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

Get started See an example Read the docs

4 commands
Requires Spec Kit >= 0.2.0
MIT licensed
No em dashes, plain English

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.

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.

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 English 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 four commands

Each command stands alone and reads from a feature directory under specs/. Stop at the level of detail your audience needs.

Command	Reads	Writes	Audience
`/speckit.product.info`	`spec.md`	`product/00-info.md`	Any stakeholder, non-technical
`/speckit.product.spec`	`spec.md`	`product/10-spec.md`	Product managers, 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 four 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.

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

## Problem Statement (Job to Be Done)

**Primary job**:

> When my organization depends on a shared service for its daily work, I
> want to keep steady access regardless of what other customers do, so I can
> serve my own users without interruption.

## Target Users and Personas

- **Customer organization developer**: Builds on our service. Cares about
  predictable, uninterrupted access.
- **Customer organization admin**: Manages the account. Cares about staying
  within plan limits.
- **Internal support staff**: Helps customers. Cares about resolving limit
  requests without engineering.

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. When a caller goes over a limit, the service refuses the request with
a clear reason and a retry time.

## Feature Context

**Problem**: One customer's traffic spike can degrade the shared service for
everyone, with no fair per-customer boundary.

**Quality bar**: Limits are enforced accurately under heavy concurrent load,
with changes and usage reflected within one minute.

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 three sentences or fewer
- [x] No em dash
- [x] No AI tells
- [x] No implementation detail

## Spec (`product/10-spec.md`)

- [x] Problem Statement contains a Job to Be Done statement
- [x] Use Cases follow Given/When/Then
- [ ] No AI tell filler phrases

Auto-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

## Problem Statement (Job to Be Done)

**Primary job**:

> When my organization is using a billed product during the month, I want to
> understand expected charges and their causes, so I can prevent surprises and
> explain costs before the invoice arrives.

## Target Users and Personas

- **Organization admin**: Owns account health and avoids billing surprises.
- **Billing manager**: Reviews invoices and reconciles costs for finance.
- **Team lead**: Explains why their team changed account usage.

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 three sentences or fewer
- [x] No em dash
- [x] No implementation detail

## Spec (`product/10-spec.md`)

- [x] Problem Statement contains a Job to Be Done
- [x] Use Cases follow Given/When/Then
- [x] No AI tells

Auto-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

Install directly from the latest release. This needs no catalog setup and is the recommended path:
```
specify extension add product \
  --from https://github.com/d0whc3r/spec-kit-product/releases/download/v0.9.0/product-0.9.0.zip
```
Confirm it registered:
```
cat .specify/extensions/.registry   # 'product' entry present
ls .specify/extensions/product      # extension files present
```
Prefer specify extension add product by name? That needs the community catalog approved first. See install help.
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 artifact

Run the lightest command first to validate direction. It writes product/00-info.md and product/checklist.md.
```
/speckit.product.info
```
Generate the full set

Once direction is confirmed, generate the spec. After you have a Spec Kit plan.md (run /speckit.plan), add the plan and design views.
```
/speckit.product.spec
/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.info   -> product/00-info.md
                            \--> /speckit.product.spec   -> product/10-spec.md

/speckit.plan --> plan.md --> /speckit.product.plan      -> product/20-plan.md
                        \---> /speckit.product.design    -> product/30-design.md

All four 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' is available in the 'community' catalog but installation
is not allowed from that catalog.

To enable installation, add 'product' 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 product \
  --from https://github.com/d0whc3r/spec-kit-product/releases/download/v0.9.0/product-0.9.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 product
specify extension update product

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 product 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.

Do I have to run all four commands?

No. Stop at the level of detail your audience needs. A small change that needs only stakeholder buy-in is just /speckit.product.info. A full feature definition is info plus spec. 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 Product 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 this work in a brownfield codebase?

Yes. The bundled brownfield extension helps reverse-engineer specs from existing code. Once you have a spec.md, the product commands work the same way.