| name | bmad-create-story |
| description | Unified story creation and enrichment engine (story-spec v2). Produces implementation-ready stories with real-data confrontation (provider/DB/cloud), external research (docs/RFC/gotchas), structured NFRs (7 categories), binary security gate, observability requirements, deployment chain audit, impact analysis, BACs in Given/When/Then, TACs in EARS notation, INVEST self-check, out-of-scope register, risks/assumptions register, boundaries triple, and multi-validator review. Discovery mode creates a new tracker issue from conversational spec engineering; Enrichment mode loads full context (PRD, Architecture, UX, completed stories, git history) and enriches an existing Backlog issue. Use when 'create story', 'enrich story', 'spec story', 'write spec', 'nouvelle story', 'enrichir story', 'preparer story', 'creer story' is mentioned. |
| disable-model-invocation | true |
Create Story (v2)
Overview
Unified story creation and enrichment engine producing implementation-ready stories per the story-spec v2 schema (bmad-shared/spec-completeness-rule.md). The pipeline runs three evidence-gathering steps (access verification → real-data investigation → external research) before any spec content is written, then proceeds through code investigation, modeling, NFR / Security / Observability, audit, plan composition with EARS-formatted technical ACs, and a multi-validator review gate.
Discovery mode creates a new tracker issue from conversational spec engineering; Enrichment mode loads full context (PRD, Architecture, UX, completed stories, git history) and enriches an existing Backlog issue. Both modes share the 14-step pipeline.
Conventions
- Bare paths (e.g.
steps/step-01-init.md) resolve from the skill root.
{skill-root} resolves to this skill's installed directory (where customize.toml lives).{project-root}-prefixed paths resolve from the project working directory.{skill-name} resolves to the skill directory's basename.
On Activation
Step 1: Resolve the Workflow Block
Run: python3 ~/.claude/skills/bmad-shared/scripts/resolve_customization.py --skill {skill-root} --key workflow
If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
{skill-root}/customize.toml — defaults{project-root}/_bmad/custom/{skill-name}.toml — team overrides{project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides
Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.
Step 2: Execute Prepend Steps
Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.
Step 3: Load Persistent Facts
Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.
Step 4: Load Project Workflow Context
Resolve the main project root (worktree-aware): run MAIN_PROJECT_ROOT=$(dirname "$(git rev-parse --git-common-dir)").
Load {MAIN_PROJECT_ROOT}/.claude/workflow-context.md and resolve from its YAML frontmatter:
- Use
{user_name} for greeting
- Use
{communication_language} for all communications
- Use
{document_output_language} for output documents
- Use
{planning_artifacts} for output location and artifact scanning
- Use
{project_knowledge} for additional context scanning
If workflow-context.md is missing, ask the user for their name and preferred language, then continue.
Step 5: Greet the User
Greet {user_name}, speaking in {communication_language}. Be warm but efficient.
Step 6: Execute Append Steps
Execute each entry in {workflow.activation_steps_append} in order.
Activation complete. Read FULLY and follow ./workflow.md — load the file with the Read tool, do not summarise from memory, do not skip sections.
