BMAD Init — Workspace Scaffolder
Set up the planning workspace and choose the TRACK that scales the rest of the BMAD
planning workflows. This is a planning skill: it creates folders and seed
documents only. It never writes application code, runs tests, or builds anything.
What it produces
Under the configured output folder (default bmad-output/):
bmad-output/
├── config.yaml # project name, track, output paths, languages
├── decision-log.md # empty threaded decision log (grows across workflows)
├── project-context.md # the project "constitution" loaded by every later skill
└── stories/ # empty; future story files land here
config.yaml is the single source of truth other skills read to find the output
folder and the chosen track.
The three TRACKS (never numbered Levels)
| Track |
Story count |
Planning artifacts |
| Quick Flow |
1–15 stories |
tech-spec only |
| BMad Method |
10–50+ stories |
PRD + Architecture (+ optional UX) |
| Enterprise |
30+ stories |
PRD + Architecture + Security + DevOps planning |
The track is a planning-need decision, not a points/velocity decision. Story
count is a rough signal only; let scope, cross-team coordination, and risk drive the
call. A heuristic may suggest a default — the user always confirms.
Workflow
Check for an existing workspace. Glob for bmad-output/config.yaml (or a
custom output folder if the user names one). If it exists, read it and ask whether
to keep, re-run idempotently (safe — existing files are preserved), or change the
track. Do not clobber a populated decision-log.md or project-context.md.
Gather rough scope signals in conversation (don't interrogate):
- One-line project description.
- Roughly how many distinct pieces of work / stories? (ranges are fine)
- Multiple teams or just one builder?
- Hard compliance / security / infra requirements?
Suggest a track. Run the helper to print the three tracks and a suggested
default, then state your recommendation and ask the user to confirm or override:
bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-init/scripts/select-track.sh" --stories <N> --teams <one|many> --compliance <yes|no>
Heuristic the helper applies (you may reason past it):
- compliance/infra = yes, or 30+ stories → Enterprise
- 10+ stories, or PRD/architecture clearly needed → BMad Method
- otherwise → Quick Flow
Scaffold. Once the user confirms name + track, run:
bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-init/scripts/init-project.sh" \
--name "<project name>" \
--track <quick-flow|bmad-method|enterprise> \
--output "bmad-output"
The script is idempotent: it creates missing folders and seeds any missing
template files, but never overwrites decision-log.md or project-context.md
if they already contain content. It always (re)writes config.yaml.
Open the constitution. Walk the user through filling the first sections of
project-context.md (project goal, primary users, constraints, non-goals). This
is the document every downstream skill loads, so a few good sentences here pay off.
Record the track choice and rationale as the first entry in decision-log.md.
Hand off. Recommend the next planning step based on track:
- Quick Flow → tech-spec, then sprint-planning / story creation.
- BMad Method → product brief → PRD → architecture.
- Enterprise → product brief → PRD → architecture (+ security & DevOps planning).
Three intents
Guardrails
- No numbered Levels anywhere — only the three named tracks.
- No story points, velocity, burndown. Delivery is count-based (stories
remaining / completion rate). Story sizing target: small enough for one agent
session (~2–8h); split anything larger.
- This skill stops at scaffolding. It hands off to other planning skills; it never
implements, tests, lints, or builds.
See REFERENCE.md for the full config schema, track decision detail, and the
project-context section guide.
Part of the BMAD Planning & Orchestrator plugin — a Claude Code harness for the BMAD Method by the BMAD Code Organization (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of bmad-init. All methodology credit belongs to the BMAD Code Organization.
1---
2name: bmad-init
3description: |
4 Initialize a BMAD planning workspace: pick a scale-adaptive TRACK (Quick Flow /
5 BMad Method / Enterprise) interactively, then scaffold the output folder, a config
6 file, an empty decision-log.md, and a project-context.md "constitution". Use when
7 the user says "initialize BMAD", "set up BMAD", "start a new BMAD project",
8 "scaffold the planning workspace", "bmad init", "create the bmad config", or is
9 beginning planning and has no bmad-output/ folder yet. Also use when the user asks
10 "which track should I use?" or "what scale is my project?". This is the FIRST skill
11 to run before any other planning workflow (brief, PRD, architecture, stories).
12allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
13metadata:
14 source: https://skillmd.com/skills/aj-geddes/bmad-init
15---
16
17# BMAD Init — Workspace Scaffolder
18
19Set up the planning workspace and choose the TRACK that scales the rest of the BMAD
20planning workflows. This is a **planning** skill: it creates folders and seed
21documents only. It never writes application code, runs tests, or builds anything.
22
23## What it produces
24
25Under the configured output folder (default `bmad-output/`):
26
27```
28bmad-output/
29├── config.yaml # project name, track, output paths, languages
30├── decision-log.md # empty threaded decision log (grows across workflows)
31├── project-context.md # the project "constitution" loaded by every later skill
32└── stories/ # empty; future story files land here
33```
34
35`config.yaml` is the single source of truth other skills read to find the output
36folder and the chosen track.
37
38## The three TRACKS (never numbered Levels)
39
40| Track | Story count | Planning artifacts |
41|-------|-------------|--------------------|
42| **Quick Flow** | 1–15 stories | tech-spec only |
43| **BMad Method** | 10–50+ stories | PRD + Architecture (+ optional UX) |
44| **Enterprise** | 30+ stories | PRD + Architecture + Security + DevOps planning |
45
46The track is a **planning-need** decision, not a points/velocity decision. Story
47count is a rough signal only; let scope, cross-team coordination, and risk drive the
48call. A heuristic may suggest a default — **the user always confirms**.
49
50## Workflow
51
521. **Check for an existing workspace.** Glob for `bmad-output/config.yaml` (or a
53 custom output folder if the user names one). If it exists, read it and ask whether
54 to keep, re-run idempotently (safe — existing files are preserved), or change the
55 track. Do not clobber a populated decision-log.md or project-context.md.
56
572. **Gather rough scope signals** in conversation (don't interrogate):
58 - One-line project description.
59 - Roughly how many distinct pieces of work / stories? (ranges are fine)
60 - Multiple teams or just one builder?
61 - Hard compliance / security / infra requirements?
62
633. **Suggest a track.** Run the helper to print the three tracks and a suggested
64 default, then state your recommendation and **ask the user to confirm or override**:
65
66 ```bash
67 bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-init/scripts/select-track.sh" --stories <N> --teams <one|many> --compliance <yes|no>
68 ```
69
70 Heuristic the helper applies (you may reason past it):
71 - compliance/infra = yes, or 30+ stories → **Enterprise**
72 - 10+ stories, or PRD/architecture clearly needed → **BMad Method**
73 - otherwise → **Quick Flow**
74
754. **Scaffold.** Once the user confirms name + track, run:
76
77 ```bash
78 bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-init/scripts/init-project.sh" \
79 --name "<project name>" \
80 --track <quick-flow|bmad-method|enterprise> \
81 --output "bmad-output"
82 ```
83
84 The script is **idempotent**: it creates missing folders and seeds any missing
85 template files, but never overwrites `decision-log.md` or `project-context.md`
86 if they already contain content. It always (re)writes `config.yaml`.
87
885. **Open the constitution.** Walk the user through filling the first sections of
89 `project-context.md` (project goal, primary users, constraints, non-goals). This
90 is the document every downstream skill loads, so a few good sentences here pay off.
91 Record the track choice and rationale as the first entry in `decision-log.md`.
92
936. **Hand off.** Recommend the next planning step based on track:
94 - Quick Flow → tech-spec, then sprint-planning / story creation.
95 - BMad Method → product brief → PRD → architecture.
96 - Enterprise → product brief → PRD → architecture (+ security & DevOps planning).
97
98## Three intents
99
100- **Create** — fresh workspace (the common case).
101- **Update** — change the track or rename the project: edit `config.yaml` and append
102 the change to `decision-log.md` with a date and reason. Do not wipe other files.
103- **Validate** — confirm the workspace is well-formed:
104 ```bash
105 bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-init/scripts/init-project.sh" --validate --output "bmad-output"
106 ```
107
108## Guardrails
109
110- No numbered Levels anywhere — only the three named tracks.
111- No story points, velocity, burndown. Delivery is **count-based** (stories
112 remaining / completion rate). Story sizing target: small enough for one agent
113 session (~2–8h); split anything larger.
114- This skill stops at scaffolding. It hands off to other planning skills; it never
115 implements, tests, lints, or builds.
116
117See `REFERENCE.md` for the full config schema, track decision detail, and the
118project-context section guide.
119
120> ---
121> Part of the **BMAD Planning & Orchestrator** plugin — a Claude Code harness for the **BMAD Method** by the **BMAD Code Organization** (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of `bmad-init`. All methodology credit belongs to the BMAD Code Organization.