Skip to content

Commit 0115c03

Browse files
mnriemCopilot
mnriem
and
Copilot
committed
docs(concepts): document the spec-of-specs feature breakdown approach (#3423)
Add a dedicated "Spec of Specs" concept page describing how to decompose a large feature into a roadmap of smaller, independently-specified sub-features using the existing Spec Kit flow. Covers the roadmap pass, the roadmap artifact template, specifying each sub-feature, bidirectional sub-spec/roadmap linking, keeping them in sync, a worked example, and optional automation. Link the new page from the "Handling Complex Features" decomposition section and add it to the docs table of contents. Closes #3423 Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f236bc38-a7c6-4063-a79c-6ba81aa685b5
1 parent 8db7228 commit 0115c03

3 files changed

Lines changed: 180 additions & 4 deletions

File tree

‎docs/concepts/complex-features.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,10 +63,14 @@ independently specified sub-features. Each sub-feature gets its own
6363
`spec.md`, `plan.md`, and `tasks.md`, and runs through its own
6464
specify/plan/tasks/implement cycle.
6565

66-
This is the "spec of specs" approach: the first iteration breaks a massive
67-
feature into smaller, self-contained specs that can each be implemented without
68-
overwhelming the model. It adds the most overhead, so reserve it for features
69-
that are too large to handle any other way.
66+
This is the "spec of specs" approach: a first pass breaks a massive feature into
67+
smaller, self-contained specs that can each be implemented without overwhelming the
68+
model. It adds the most overhead, so reserve it for features that are too large to
69+
handle any other way.
70+
71+
See [Spec of Specs](spec-of-specs.md) for the full procedure — how to run the
72+
roadmap pass, structure the roadmap artifact, link sub-specs back to it, and a worked
73+
example.
7074

7175
## Which Approach to Choose
7276

‎docs/concepts/spec-of-specs.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Spec of Specs
2+
3+
When a feature is too large to run through a single
4+
`/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`
5+
cycle without the model losing track mid-implementation, you can break it into a
6+
**roadmap** of smaller, independently-specified sub-features. This is the "spec of
7+
specs" approach: one up-front pass decomposes a massive feature into self-contained
8+
specs, and each of those runs through its own specify/plan/tasks/implement cycle.
9+
10+
> **When to reach for this.** Decomposition adds the most overhead of any strategy
11+
> in [Handling Complex Features](complex-features.md). Use it **only when the lighter
12+
> options there are insufficient** — first try limiting how many tasks run per
13+
> `/speckit.implement` invocation, then sub-agent delegation, then a combination.
14+
> Reach for a spec of specs only when even a single phase is too large to handle in
15+
> one run.
16+
17+
The rest of this page describes *how* to do it with the tools you already have. No
18+
new commands or extensions are required.
19+
20+
## The roadmap pass
21+
22+
Before writing any sub-spec, do a single decomposition pass to produce a roadmap.
23+
Treat this as a lightweight planning conversation with your agent, not a full spec:
24+
25+
1. **State the whole feature.** Describe the large feature (the "epic") in a
26+
sentence or two so the agent has the full picture up front.
27+
2. **Identify independent slices.** Ask the agent to propose a small set of
28+
sub-features that each deliver a coherent piece of the epic and can be specified
29+
on their own. Aim for slices that are independently testable — implementing just
30+
one should leave you with something demonstrable.
31+
3. **Draw the boundaries.** For each slice, write one line of intent and an explicit
32+
scope boundary (what is in, what is deferred to a sibling slice). Sharp
33+
boundaries are what keep each sub-spec small enough to fit in context.
34+
4. **Order by dependency.** Note which slices depend on others and sequence them so
35+
prerequisites come first. Slices with no dependency on each other can be built in
36+
any order (or in parallel).
37+
5. **Record the result as a roadmap.** Capture the slices in a durable roadmap file
38+
(below) so every later sub-spec can point back to it.
39+
40+
The roadmap is deliberately shallow: it names and orders the sub-features but does
41+
**not** design them. The design happens when each slice runs through its own
42+
`/speckit.specify`.
43+
44+
## The roadmap artifact
45+
46+
The roadmap is an ordinary Markdown file you author and keep under version control —
47+
there is no special tooling behind it. Put it where the sub-specs can find it:
48+
49+
- For a feature-scoped epic: `specs/<epic-slug>/roadmap.md`.
50+
- For a larger, cross-cutting epic: a top-level `ROADMAP.md`.
51+
52+
Each roadmap entry carries a stable id (used later for linking), a name, its intent,
53+
its scope boundary, its dependencies, a status, and — once the sub-spec exists — a
54+
link to it. A minimal template:
55+
56+
```markdown
57+
# Roadmap: <epic name>
58+
59+
<One or two sentences: what the epic is and why it is being decomposed.>
60+
61+
**Status legend**: planned · in-progress · done
62+
63+
| ID | Sub-feature | Intent | Scope boundary | Depends on | Status | Sub-spec |
64+
|----|-------------|--------|----------------|-----------|--------|----------|
65+
| R1 | <name> | <one line> | <in / deferred> | — | planned | — |
66+
| R2 | <name> | <one line> | <in / deferred> | R1 | planned | — |
67+
| R3 | <name> | <one line> | <in / deferred> | R1 | planned | — |
68+
```
69+
70+
Keep the `ID` column immutable once a sub-spec references it — it is the anchor for
71+
traceability. Fill in the `Sub-spec` column with the path to each sub-feature's spec
72+
directory as you create it, and update `Status` as work progresses.
73+
74+
## Specifying each sub-feature
75+
76+
With the roadmap in hand, work through the entries one at a time using the normal
77+
Spec Kit flow — nothing new to learn:
78+
79+
1. Pick the next roadmap entry whose dependencies are already `done` (or have none).
80+
2. Run `/speckit.specify` for just that slice, describing only its intent and scope
81+
from the roadmap entry. Because the slice is bounded, its spec, plan, and tasks
82+
stay well within the context window.
83+
3. Run `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` for that slice as
84+
usual.
85+
4. Mark the roadmap entry `done` and move to the next one.
86+
87+
Each slice is a complete, independent Spec Kit feature with its own
88+
`spec.md`/`plan.md`/`tasks.md`. The roadmap is what ties them together.
89+
90+
## Linking sub-specs to the roadmap
91+
92+
To keep scope and intent from drifting across separate runs, every sub-spec
93+
references its roadmap entry, and the roadmap links back — a simple, greppable,
94+
bidirectional convention:
95+
96+
- **Sub-spec → roadmap.** In the sub-feature's `spec.md`, name the parent roadmap
97+
and entry id in the `Input` / summary line, for example:
98+
99+
```markdown
100+
**Input**: Parent roadmap: `specs/<epic>/roadmap.md` → entry **R3**. <feature description>
101+
```
102+
103+
- **Roadmap → sub-spec.** In the roadmap table, set the entry's `Sub-spec` column to
104+
the sub-feature's directory, e.g. `specs/<epic>-part-3/`.
105+
106+
Because both directions are plain text, you can trace any sub-spec back to its place
107+
in the epic (and find its siblings) with a quick search — no tooling, no metadata
108+
schema.
109+
110+
## Keeping the roadmap and sub-specs in sync
111+
112+
The roadmap is a living document. As you learn more, keep it and the sub-specs
113+
aligned:
114+
115+
- **Roadmap first, then reconcile.** When scope shifts, update the roadmap entry
116+
first, then update any sub-specs it affects. The roadmap is the source of truth for
117+
how the epic is divided.
118+
- **Respect dependencies and ordering.** If a slice depends on another, build the
119+
prerequisite first and cross-reference the dependent sub-spec so the relationship
120+
is visible from both sides.
121+
- **Recurse when a slice is still too big.** If a sub-feature turns out to be too
122+
large to specify in one cycle, give it its own roadmap and decompose it further —
123+
the same approach applies one level down. Recursion adds overhead, so only go as
124+
deep as the context problem actually requires.
125+
126+
## Worked example
127+
128+
Suppose the epic is **"Add a self-service billing portal"** — far too large for a
129+
single cycle. The roadmap pass breaks it into three independently-specifiable
130+
slices.
131+
132+
`specs/billing-portal/roadmap.md`:
133+
134+
```markdown
135+
# Roadmap: Self-service billing portal
136+
137+
Let customers view invoices, manage payment methods, and change plans without
138+
contacting support. Too large for one cycle, so it is split into independent slices.
139+
140+
**Status legend**: planned · in-progress · done
141+
142+
| ID | Sub-feature | Intent | Scope boundary | Depends on | Status | Sub-spec |
143+
|----|--------------------|------------------------------------------|---------------------------------------------|-----------|---------|----------|
144+
| R1 | Invoice history | Customers view and download past invoices | Read-only; no payment actions | — | done | specs/billing-invoices/ |
145+
| R2 | Payment methods | Add, remove, and set a default card | No plan changes; assumes invoices exist | R1 | in-progress | specs/billing-payment-methods/ |
146+
| R3 | Plan changes | Upgrade/downgrade the subscription plan | Uses R2's default payment method | R1, R2 | planned | — |
147+
```
148+
149+
Each slice is then specified on its own. For example, the **R2** sub-feature's
150+
`spec.md` opens with a back-reference:
151+
152+
```markdown
153+
# Feature Specification: Billing — payment methods
154+
155+
**Input**: Parent roadmap: `specs/billing-portal/roadmap.md` → entry **R2**.
156+
Let customers add, remove, and set a default payment method in the billing portal.
157+
```
158+
159+
From here a reader can trace **R2** back to the roadmap, see that it depends on
160+
**R1** (invoice history, already `done`), and see that **R3** (plan changes) is
161+
waiting on it. Building R1, then R2, then R3 keeps every run small while the roadmap
162+
preserves the shape of the whole epic.
163+
164+
## For automation (optional)
165+
166+
If you would rather automate roadmap capture and consistency checks than maintain
167+
the file by hand, the community-maintained
168+
[Spec Roadmap extension](https://github.com/srobroek/speckit-roadmap) explores that
169+
direction. It is a third-party extension and is not required — the manual convention
170+
above is enough on its own.

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@
5555
href: concepts/spec-persistence.md
5656
- name: Handling Complex Features
5757
href: concepts/complex-features.md
58+
- name: Spec of Specs
59+
href: concepts/spec-of-specs.md
5860

5961
# Development workflows
6062
- name: Development

0 commit comments

Comments
 (0)