bmad-spec

Name: bmad-spec
Author: aj-geddes

467stars73forks

How to install bmad-spec?

aj-geddes/claude-code-bmad-skills/bmad-spec

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-spec

Installs into the current project.

Summary

Distills ANY messy input — brain dump, transcript, long PRD, stakeholder notes, feature request, voice memo — into a tight five-field SPEC.md kernel that any downstream planning skill can consume. The five fields are: Problem, Capabilities, Constraints, Non-Goals, Success Metrics

Files · 1

View on GitHub

SKILL.md

1	# BMAD Spec — Five-Field Kernel Distiller
2
3	Function: Accept messy, unstructured, or verbose input and produce a lean
4	`SPEC.md` kernel (five fields, no more) that anchors every downstream planning
5	workflow. This is a planning skill. It never writes application code, runs
6	tests, or builds anything.
7
8	## What it produces
9
10	A single file under the configured output folder (default `bmad-output/`):
11
12	```
13	bmad-output/
14	└── SPEC.md # the five-field kernel
15	```
16
17	The kernel is intentionally small — a SPEC is not a PRD, not a brief, not an
18	architecture doc. It is the shared definition of what is being built and why.
19	Every downstream skill (PRD, tech-spec, architecture) loads it as the ground
20	truth for scope.
21
22	## The five fields
23
24	\| Field \| Purpose \|
25	\|---\|---\|
26	\| Problem \| The one thing that hurts right now and why it matters \|
27	\| Capabilities \| What the solution must be able to do (outcome-framed) \|
28	\| Constraints \| Hard limits that are not negotiable (budget, tech, time, compliance) \|
29	\| Non-Goals \| Scope that is explicitly out — prevents creep and confusion \|
30	\| Success Metrics \| Observable signals that confirm the problem is solved \|
31
32	See `templates/spec.template.md` for the exact template with guidance and examples.
33
34	## Workflow
35
36	### 1. Ingest
37
38	Accept whatever the user hands over:
39	- Paste of raw text, notes, or a transcript
40	- A path to an existing file (`Read` it)
41	- Verbal description in the chat
42
43	If the input exceeds a few hundred words, briefly acknowledge what you received
44	before proceeding. Do not ask the user to reformat it — that is the skill's job.
45
46	### 2. Extract (silent analysis)
47
48	Read the input and locate signal for each field:
49	- Problem: What pain, gap, or failure state is described? Who experiences it?
50	- Capabilities: What outcomes or abilities are requested? Rephrase features
51	as capabilities ("users can …", "the system supports …").
52	- Constraints: What is fixed? Look for budget figures, tech mandates, deadlines,
53	regulatory mentions, team-size limits.
54	- Non-Goals: What is the input silent about that a reader might assume? What
55	is explicitly ruled out? What is deferred?
56	- Success Metrics: What does "done" or "working" look like? Numbers,
57	observable behaviors, thresholds.
58
59	### 3. Draft and present
60
61	Write a concise draft of all five fields and show it to the user in the chat
62	before writing to disk. Keep each field tight:
63	- Problem: 2–5 sentences max.
64	- Capabilities: 3–7 bullet points, outcome-framed.
65	- Constraints: 2–6 bullet points, hard limits only.
66	- Non-Goals: 2–6 bullet points, clear and unambiguous.
67	- Success Metrics: 2–5 bullet points, each with a measurable signal.
68
69	After presenting, ask one targeted question: "Does anything here need to change
70	before I write SPEC.md?"
71
72	### 4. Write
73
74	Once the user confirms (or revises), write `SPEC.md` using the template:
75
76	```
77	${CLAUDE_PLUGIN_ROOT}/skills/bmad-spec/templates/spec.template.md
78	```
79
80	Output path: `<outputFolder>/SPEC.md` (read `bmad-output/config.yaml` if it
81	exists to find the configured output folder; fall back to `bmad-output/`).
82
83	Append a new entry to `bmad-output/decision-log.md` (create it if absent):
84
85	```markdown
86	## SPEC created — <ISO date>
87	- Source: <one-line description of the input, e.g. "stakeholder brain dump">
88	- Key scope decision: <the single most important Non-Goal or Constraint>
89	```
90
91	### 5. Hand off
92
93	After writing, tell the user what the SPEC unlocks:
94	- Quick Flow track → hand off to `bmad-tech-spec` to turn the kernel into a
95	deployable spec.
96	- BMad Method / Enterprise track → hand off to `bmad-product-brief` or the
97	PM role (`bmad-prfaq`) for a full PRD.
98	- If no workspace exists yet, suggest running `/bmad-planning-orchestrator:bmad-init`
99	first to pick a track.
100
101	## Three intents
102
103	- Create — distill fresh input into a new `SPEC.md` (the common case).
104	- Update — the user has new information or changed scope. Read the existing
105	`SPEC.md`, apply the changes, present a diff-style summary, confirm, then
106	overwrite. Record the change in `decision-log.md`.
107	- Validate — review `SPEC.md` against the fiv

People who liked this also viewed

6 picks

Type

bmad-spec

467stars73forks

View on GitHub

How to install bmad-spec?

aj-geddes/claude-code-bmad-skills/bmad-spec

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-spec

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# BMAD Spec — Five-Field Kernel Distiller
2
3	Function: Accept messy, unstructured, or verbose input and produce a lean
4	`SPEC.md` kernel (five fields, no more) that anchors every downstream planning
5	workflow. This is a planning skill. It never writes application code, runs
6	tests, or builds anything.
7
8	## What it produces
9
10	A single file under the configured output folder (default `bmad-output/`):
11
12	```
13	bmad-output/
14	└── SPEC.md # the five-field kernel
15	```
16
17	The kernel is intentionally small — a SPEC is not a PRD, not a brief, not an
18	architecture doc. It is the shared definition of what is being built and why.
19	Every downstream skill (PRD, tech-spec, architecture) loads it as the ground
20	truth for scope.
21
22	## The five fields
23
24	\| Field \| Purpose \|
25	\|---\|---\|
26	\| Problem \| The one thing that hurts right now and why it matters \|
27	\| Capabilities \| What the solution must be able to do (outcome-framed) \|
28	\| Constraints \| Hard limits that are not negotiable (budget, tech, time, compliance) \|
29	\| Non-Goals \| Scope that is explicitly out — prevents creep and confusion \|
30	\| Success Metrics \| Observable signals that confirm the problem is solved \|
31
32	See `templates/spec.template.md` for the exact template with guidance and examples.
33
34	## Workflow
35
36	### 1. Ingest
37
38	Accept whatever the user hands over:
39	- Paste of raw text, notes, or a transcript
40	- A path to an existing file (`Read` it)
41	- Verbal description in the chat
42
43	If the input exceeds a few hundred words, briefly acknowledge what you received
44	before proceeding. Do not ask the user to reformat it — that is the skill's job.
45
46	### 2. Extract (silent analysis)
47
48	Read the input and locate signal for each field:
49	- Problem: What pain, gap, or failure state is described? Who experiences it?
50	- Capabilities: What outcomes or abilities are requested? Rephrase features
51	as capabilities ("users can …", "the system supports …").
52	- Constraints: What is fixed? Look for budget figures, tech mandates, deadlines,
53	regulatory mentions, team-size limits.
54	- Non-Goals: What is the input silent about that a reader might assume? What
55	is explicitly ruled out? What is deferred?
56	- Success Metrics: What does "done" or "working" look like? Numbers,
57	observable behaviors, thresholds.
58
59	### 3. Draft and present
60
61	Write a concise draft of all five fields and show it to the user in the chat
62	before writing to disk. Keep each field tight:
63	- Problem: 2–5 sentences max.
64	- Capabilities: 3–7 bullet points, outcome-framed.
65	- Constraints: 2–6 bullet points, hard limits only.
66	- Non-Goals: 2–6 bullet points, clear and unambiguous.
67	- Success Metrics: 2–5 bullet points, each with a measurable signal.
68
69	After presenting, ask one targeted question: "Does anything here need to change
70	before I write SPEC.md?"
71
72	### 4. Write
73
74	Once the user confirms (or revises), write `SPEC.md` using the template:
75
76	```
77	${CLAUDE_PLUGIN_ROOT}/skills/bmad-spec/templates/spec.template.md
78	```
79
80	Output path: `<outputFolder>/SPEC.md` (read `bmad-output/config.yaml` if it
81	exists to find the configured output folder; fall back to `bmad-output/`).
82
83	Append a new entry to `bmad-output/decision-log.md` (create it if absent):
84
85	```markdown
86	## SPEC created — <ISO date>
87	- Source: <one-line description of the input, e.g. "stakeholder brain dump">
88	- Key scope decision: <the single most important Non-Goal or Constraint>
89	```
90
91	### 5. Hand off
92
93	After writing, tell the user what the SPEC unlocks:
94	- Quick Flow track → hand off to `bmad-tech-spec` to turn the kernel into a
95	deployable spec.
96	- BMad Method / Enterprise track → hand off to `bmad-product-brief` or the
97	PM role (`bmad-prfaq`) for a full PRD.
98	- If no workspace exists yet, suggest running `/bmad-planning-orchestrator:bmad-init`
99	first to pick a track.
100
101	## Three intents
102
103	- Create — distill fresh input into a new `SPEC.md` (the common case).
104	- Update — the user has new information or changed scope. Read the existing
105	`SPEC.md`, apply the changes, present a diff-style summary, confirm, then
106	overwrite. Record the change in `decision-log.md`.
107	- Validate — review `SPEC.md` against the fiv

People who liked this also viewed

6 picks

Type