Quick Dev New Preview Workflow

Goal: Turn user intent into a hardened, reviewable artifact.

CRITICAL: If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.

Conventions

• Bare paths (e.g. template.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root} is the nearest folder containing _bmad/, starting at the project working directory and moving up through its parents.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-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:

1. {skill-root}/customize.toml — defaults
2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides
3. {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 Config

Load config from {project-root}/_bmad/gds/config.yaml and resolve:

• user_name
• communication_language
• implementation_artifacts

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

READY FOR DEVELOPMENT STANDARD

A specification is "Ready for Development" when:

• Actionable: Every task has a file path and specific action.
• Logical: Tasks ordered by dependency.
• Testable: All ACs use Given/When/Then.
• Complete: No placeholders or TBDs.

SCOPE STANDARD

A specification should target a single user-facing goal within 900–1600 tokens:

• Single goal: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 top-level independent shippable deliverables — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
  • Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
  • Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
• 900–1600 tokens: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
• Neither limit is a gate. Both are proposals with user override.

WORKFLOW ARCHITECTURE

This uses step-file architecture for disciplined execution:

• Micro-file Design: Each step is self-contained and followed exactly
• Just-In-Time Loading: Only load the current step file
• Sequential Enforcement: Complete steps in order, no skipping
• State Tracking: Persist progress via spec frontmatter and in-memory variables
• Append-Only Building: Build artifacts incrementally

Step Processing Rules

1. READ COMPLETELY: Read the entire step file before acting
2. FOLLOW SEQUENCE: Execute sections in order
3. WAIT FOR INPUT: Halt at checkpoints and wait for human
4. LOAD NEXT: When directed, read fully and follow the next step file

Critical Rules (NO EXCEPTIONS)

• NEVER load multiple step files simultaneously
• ALWAYS read entire step file before execution
• NEVER skip steps or optimize the sequence
• ALWAYS follow the exact instructions in the step file
• ALWAYS halt at checkpoints and wait for human input

INITIALIZATION SEQUENCE

1. Configuration Loading

Load and read full config from {main_config} and resolve:

• project_name, planning_artifacts, implementation_artifacts, user_name
• communication_language, document_output_language, game_dev_experience
• date as system-generated current datetime
• sprint_status = {implementation_artifacts}/sprint-status.yaml
• project_context = **/project-context.md (load if exists)
• CLAUDE.md / memory files (load if exist)

YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}.

2. First Step Execution

Read fully and follow: ./step-01-clarify-and-route.md to begin the workflow.