| name | custom-dev |
| description | Orchestrate the full build cycle from sprint planning to implemented code with docs. Use when the user says "dev to done", "run build cycle", or "implement the backlog". |
Dev to Done
Overview
This workflow orchestrates the complete BMad Step 2 build cycle — from initializing sprint tracking through implementing every story, reviewing code, running retrospectives per epic, and updating project documentation. It picks up where custom-plan left off, consuming the epics and stories it produced and turning them into working code. Designed for autonomous execution: maximum autonomy, minimum interruption. Only critical code review findings (acceptance criteria violations or security/data-loss risks) halt the pipeline — all others are deferred.
Args: Accepts an optional epic identifier to implement a single epic, or no args to process the entire backlog.
Output: Implemented code for all stories across all epics, code review reports, retrospective summaries per epic, and updated project documentation.
On Activation
1. Configuration
Load config from {project-root}/_bmad/bmm/config.yaml and resolve:
{user_name}, {communication_language}, {document_output_language}{planning_artifacts} — where epics and stories live{implementation_artifacts} — where sprint tracking and implementation output go{project_knowledge} — existing project docs for context
Load {project-root}/_bmad-output/project-context.md if it exists. If not found at that path, search **/project-context.md as fallback.
2. Backlog Sync from GitHub
Download open GitHub issues into the backlog. This keeps backlog/to-do/ in sync with issues opened by other contributors.
- Use the
github_repo MCP tool to list all open GitHub issues
- For each issue:
- Skip if a matching folder already exists in
backlog/to-do/{number}-*/ or backlog/done/{number}-*/
- Otherwise: create
backlog/to-do/{number}-{slug}/00-request.md with the issue title, body, and URL
- Add a row to
backlog/README.md under To-Do with columns # and Title only
- Strictly read-only — never create, comment on, or close GitHub issues
Backlog numbering convention:
- GitHub-sourced items — use the real issue number as-is:
{number}-{slug}/
- Locally-created items — prefix with
0-: 0-{number}-{slug}/ (e.g., 0-210-comprar-producto)
- This prevents number collisions between GitHub issues and locally-created tickets
3. Pre-flight Validation
Before proceeding, validate that planning artifacts from custom-plan exist:
- Check
{planning_artifacts}/epics/ directory exists and contains at least one epic
- If missing, halt immediately: "No planning artifacts found. Run
custom-plan first to create epics and stories."
4. State Detection
Check {implementation_artifacts}/ for existing state to determine where to resume:
| Artifact | File | Indicates |
|---|
| Sprint status | sprint-status.yaml | Sprint planning done (Step 1) |
| Story files | {planning_artifacts}/epics/*/stories/*.md | Stories ready for dev |
| Story status | Status field in story files or sprint-status.yaml | Per-story progress |
If sprint-status.yaml exists, parse it to find the current state and resume using this decision tree:
| Story Status | Action |
|---|
done | Skip — story already complete |
in-review | Resume from Step 4 (Code Review) — collect review and fix |
in-progress | Resume from Step 3 (Implement) — re-validate previous output and continue |
ready-for-dev | Normal flow — Steps 2–4 |
If sprint-status.yaml does not exist, start from Step 1 (Sprint Planning).
5. Determine Scope
If the user provided an epic identifier, scope the cycle to that single epic. Otherwise, process all epics in the order defined by sprint-status.yaml.
Once scope is determined, begin the pipeline.
Pipeline
Execute the build cycle by invoking skills in sequence. Between steps, confirm the artifact was produced, then immediately proceed — no pause, no menu, no confirmation needed.
Maintain an orchestrator-level context cache: accumulated sprint-status, completed stories, and code review findings. Pass this cache to each sub-skill invocation to avoid redundant artifact re-reads. The sprint-status.yaml is the source of truth for progress — the orchestrator updates it after each step completes.
Step 1: Sprint Planning
Invoke bmad-sprint-planning.
Goal: Initialize sprint tracking by generating sprint-status.yaml from the existing epics and stories.
Skip if sprint-status.yaml already exists and is valid. This step runs once per project, not per epic.
Step 2: Create Story
Invoke bmad-create-story for the next story that has status ready-for-dev (or equivalent) in sprint-status.yaml.
Goal: Produce a fully-contextualized story file with all the implementation details the developer needs — acceptance criteria, technical context, dependencies, and scope.
If the story file already exists and is complete, skip creation and proceed to implementation.
Step 3: Implement Story
Invoke bmad-dev-story with the story file from Step 2.
Goal: Implement the story so that all tests pass — both any pre-existing tests from custom-qa and any additional tests written during implementation.
Test-first constraint: Before implementing, check for existing test files that target this story's components (unit tests at app/**/*.test.ts(x), integration tests at app/**/*.integration.test.ts(x), E2E tests at tests/e2e/*.spec.ts). These tests were written by custom-qa from acceptance criteria and serve as the implementation contract. Do not modify pre-existing tests — implementation must satisfy them as-is. Additional tests may be added if gaps exist, but existing test assertions are immutable.
Step 4: Code Review
Invoke bmad-code-review for the changes made in Step 3. While the review runs, begin Step 2 (Create Story) for the next story in parallel if one exists.
Goal: Adversarial quality validation — blind spot hunting, edge case analysis, and acceptance criteria audit.
Severity tiers:
- Critical (blocks progress): defects that violate acceptance criteria or introduce security/data-loss risks. Address before proceeding.
- Non-critical (deferred): all other findings are logged for future improvement and don't block progress.
Step 5: Story Loop
Repeat Steps 2–4 for each remaining story in the current epic. Update sprint-status.yaml after each story completes.
When all stories in the current epic are done, proceed to Step 6.
Step 6: Retrospective + Documentation (parallel)
Invoke both bmad-retrospective and bmad-document-project concurrently for the completed epic — neither depends on the other's output.
Retrospective goal: Extract lessons learned, assess what went well and what didn't, and capture actionable improvements for subsequent epics. Feed the epic's stories, code review findings, and any issues encountered as context. In autonomous mode, generate insights from metrics and review data rather than waiting for human input.
Documentation goal: Update project documentation to reflect the epic's implemented changes — architecture docs, component inventory, API contracts, and any other relevant documentation. Use the epic's implemented code and planning artifacts as context. Documenting per epic keeps docs in sync incrementally.
Wait for both to complete before proceeding.
Step 7: Epic Loop
Repeat Steps 2–6 for each remaining epic in scope. Apply lessons from the retrospective to improve execution of subsequent epics.
When all epics are complete, the pipeline is done.
Completion
When all steps complete successfully:
- Summarize what was implemented — list epics, stories completed, and key decisions made
- Report any code review findings that were deferred
- Highlight retrospective insights across all epics
- Confirm documentation is up to date for each epic
- Emit a structured summary to
{implementation_artifacts}/build-result.json:
{
"epics": [{"name": "", "status": "", "stories": [{"name": "", "status": "", "review_findings": 0}]}],
"total_stories": 0,
"deferred_findings": 0,
"docs_updated": true
}
- Suggest next steps:
custom-qa for E2E test coverage, or bmad-sprint-status for a status overview
Script Candidates
The following deterministic operations could be offloaded to ./scripts/orchestration-engine.py to reduce LLM token overhead (~9,500 tokens per full run):
- Config loading & path resolution — YAML parsing with variable interpolation
- State detection & sprint status parsing — YAML filter for next
ready-for-dev story
- Artifact validation — file existence and schema checks between steps
- Progress tracking — status field updates in sprint-status.yaml
- Story selection — deterministic filtering by status
