bmad-init

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

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

1. 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?

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

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

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

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

• Create — fresh workspace (the common case).
• Update — change the track or rename the project: edit config.yaml and append

the change to decision-log.md with a date and reason. Do not wipe other files.

• Validate — confirm the workspace is well-formed:

  bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-init/scripts/init-project.sh" --validate --output "bmad-output"

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.