Agent skill
bmad-workflow-orchestration-rules
BMAD workflow orchestration: When and how to use bmad_workflow and sprint-status tools to stay coordinated. Know the 4 core rules, usage patterns, and anti-patterns. Use when starting story development or transitioning between stories. Agent Behavior category skill.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/bmad-workflow-orchestration-rules
Metadata
Additional technical details for this skill
- category
- Agent Behavior
- priority
- high
- is built in
- YES
- session guardian id
- builtin_bmad_workflow_orchestration_rules
SKILL.md
BMAD Workflow Orchestration Rules
This skill documents when and how to use the bmad_workflow tool and sprint-status.yaml to keep your work coordinated with the broader team and project roadmap.
Core Orchestration Rules
The following 4 rules keep agents aligned and prevent duplicate or misdirected work:
Rule 1: Always Call suggest_next After Completing a Story
When: Immediately after a story is marked complete via bmad_workflow:complete_story
Why: The system needs to determine the next logical work unit. Manual searching is error-prone and wastes time.
How:
// After completing story 19-8
bmad_workflow({
action: 'suggest_next',
epicId: 'epic-19',
currentStoryId: '19-8-create-orchestration-skill',
});
Expected Response:
- Next actionable story (with preloaded context)
- Epic completion status
- Retrospective recommendation if epic is done
- Related story dependencies
Rule 2: Never Manually Look for Next Work
What NOT to do:
- ❌ Reading sprint-status.yaml manually to find incomplete stories
- ❌ Guessing which story should be next based on your intuition
- ❌ Picking a story that "seems important" without workflow guidance
Why: The workflow tool considers:
- Story dependencies and blocking relationships
- Epic progress and phase alignment
- Recommended implementation order
- Risk and complexity factors
- Current project phase
What TO do:
- ✅ Always use
bmad_workflow:suggest_next - ✅ Follow the recommended story it returns
- ✅ Use preloaded context for story understanding
- ✅ If you disagree with suggestion, escalate to sprint manager
Rule 3: When Directed to a Story, Always Use story_id Parameter
When: Loading a story file, understanding requirements, or starting development
Why: The story_id ensures proper context tracking and metrics collection
How:
// Load story 19-3 with full context
bmad_workflow({
action: 'get_item',
itemId: 'create-ceremony-skill', // story_id format
});
Used in:
- Accessing story file content
- Loading acceptance criteria
- Understanding epic context
- Preloading related skills
- Tracking story completion time
Rule 4: Before Marking Done, Validate with story-completion-ceremony Skill
When: Planning to call bmad_workflow:complete_story
Why: Incomplete work creates debt and blocks downstream stories
How:
- Review the story-completion-ceremony skill
- Follow its 7-step ceremony
- Gather validation evidence (tests, coverage, review status)
- Only then call complete_story with full evidence
bmad_workflow({
action: 'complete_story',
storyId: 'your-story-id',
validationEvidence: {
testsPassed: 25,
testsFailed: 0,
coveragePercent: 85,
codeReviewApproved: true,
notes: 'All AC verified, tests passing',
},
});
Usage Examples
Example 1: Complete a Story and Find Next Work
// Step 1: Verify with story-completion-ceremony skill
// (follow 7 steps)
// Step 2: Complete the story
const completeResult = await bmad_workflow({
action: 'complete_story',
storyId: '19-5-implement-context-preloading-service',
validationEvidence: {
testsPassed: 18,
testsFailed: 0,
coveragePercent: 89,
codeReviewApproved: true,
notes:
'Context service implemented and tested. Integration tests verify preloading of 8 skill types and story metadata.',
},
});
// Step 3: Get next work
const nextWork = await bmad_workflow({
action: 'suggest_next',
epicId: 'epic-19',
currentStoryId: '19-5-implement-context-preloading-service',
});
// Output expects:
// {
// nextStoryId: '19-4-update-dev-story-workflow',
// status: 'in-progress',
// epicProgress: '6/8 stories complete',
// preloadedContext: { ... },
// recommendation: 'Proceed with story 19-4 (no blocking issues)'
// }
Example 2: Handle Epic Completion Recommendation
const nextWork = await bmad_workflow({
action: 'suggest_next',
epicId: 'epic-19',
currentStoryId: '19-7-enhance-webview-story-actions',
});
// If all epic stories are done:
// {
// epicComplete: true,
// recommendation: 'run_retrospective',
// retrospectiveLocation: 'workflows/retrospective/workflow.yaml'
// }
// THEN: Trigger retrospective workflow
// DON'T: Start work on next epic manually
Example 3: Handle Retrospective Routing
When epic is complete and retrospective is recommended:
// After receiving 'run_retrospective' recommendation
const retrospective = await bmad_workflow({
action: 'suggest_next',
epicId: 'epic-19',
retrospectiveRequested: true,
});
// Executes retrospective workflow which:
// - Reviews epic outcomes vs. goals
// - Documents lessons learned
// - Updates team wiki with insights
// - Recommends improvements for next epic
// - Routes to next epic or sprint planning
Integration Points
Which Workflows Use These Tools
| Workflow | Uses | Decision Point |
|---|---|---|
dev-story |
complete_story, suggest_next |
After story completion |
code-review |
get_item (for context), complete_story (after approval) |
Story load + review approval |
retrospective |
suggest_next, get_item (for epic context) |
Epic completion |
sprint-status |
Query entire sprint (read-only) | Sprint planning |
Agent vs. System Decision Points
| Decision | Who Decides | Tool Used |
|---|---|---|
| Work is truly complete | Agent (via ceremony) | Validation evidence |
| What story is next | System (bmad_workflow) | suggest_next |
| Epic is complete | System (workflow logic) | Detected during suggest_next |
| When to do retrospective | System (recommend) | Sent in suggest_next response |
Handoff Protocol: Dev → Code Review → Done
┌─────────────────────────────────────────────────┐
│ Dev Agent (dev-story workflow) │
│ - Implement code │
│ - Write tests (≥80% coverage) │
│ - Run local tests (all passing) │
│ - Call: complete_story with evidence │
│ - Call: suggest_next → get code-review story │
│ - Mark: story as "in-review" status │
└──────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Code Review Agent (code-review workflow) │
│ - Review code quality across 5 facets │
│ - Approve or request changes │
│ - If approved: mark story "review-approved" │
│ - Call: complete_story (review_approved=true) │
│ - Call: suggest_next (find next story) │
└──────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Story → DONE │
│ Status updated in sprint-status.yaml │
│ Work awaits next epic phase │
└─────────────────────────────────────────────────┘
Anti-Patterns (What NOT To Do)
❌ Anti-Pattern 1: Not Following suggest_next Results
Wrong:
// System recommends story 19-4
// But you decide to work on 19-7 because "it's more interesting"
await startWorkOn('19-7-enhance-webview-story-actions');
Why it breaks:
- Story 19-7 blocks on 19-1 and 19-2 (missing dependencies)
- You'll waste time on work that can't be completed
- The system made recommendations based on dependency analysis
Right:
// System recommends 19-4 → accept it
const next = await suggest_next('epic-19', currentStory);
// Returns: '19-4-update-dev-story-workflow'
await implementStory(next.storyId); // Always
❌ Anti-Pattern 2: Skipping Validation Steps
Wrong:
// Stories complete but ceremony was skipped
await complete_story({
storyId: '19-5',
validationEvidence: {}, // Empty! No tests run!
});
Why it breaks:
- Downstream stories inherit technical debt
- Code reviews fail later (rework needed)
- Quality standards erode
Right:
// Follow all 7 steps
// - Verify AC: ✅
// - Write tests: ✅ (25 tests added)
// - Run tests: ✅ (all passing)
// - Edge cases: ✅ (tested null, empty, max cases)
// - Code review: ✅ (peer approved)
// - Update status: ✅ (sprint-status.yaml updated)
// - Call tool: ✅ (with full evidence)
await complete_story({
storyId: '19-5',
validationEvidence: {
testsPassed: 25,
testsFailed: 0,
coveragePercent: 87,
codeReviewApproved: true,
notes: 'Full ceremony complete',
},
});
❌ Anti-Pattern 3: Manually Updating sprint-status Without Tools
Wrong:
# Direct edit to sprint-status.yaml
19-4-update-dev-story-workflow: done # Manual change!
Why it breaks:
- No validation evidence captured
- Metrics are inaccurate (time, effort tracking)
- Blocks epic orchestration (system doesn't know it's complete)
- Retrospective can't analyze real data
Right:
// Use the tool which updates status AND captures evidence
await bmad_workflow({
action: 'complete_story',
storyId: '19-4-update-dev-story-workflow',
validationEvidence: {
/* full evidence */
},
});
// System automatically updates sprint-status.yaml
❌ Anti-Pattern 4: Ignoring Blocking Dependencies
Wrong:
// You start story 19-7 before 19-1 and 19-2 are complete
await startWorkOn('19-7-enhance-webview-story-actions');
// Gets stuck: can't implement webview without the tool enhancements!
Why it breaks:
- You'll implement features that conflict with tool changes
- Work gets thrown away or requires major rework
- Frustration and wasted effort
Right:
// Always ask suggest_next
const next = await suggest_next('epic-19', currentStory);
// Returns: '19-4' (which depends on 19-1 and 19-2)
// Only 19-4 is returned because 19-1 and 19-2 are already done
// System prevents blocking scenarios
❌ Anti-Pattern 5: Running Retrospective Mid-Epic
Wrong:
// After story 19-3 completes, trigger retrospective
await runRetrospective('epic-19'); // Epic is only 3/8 done!
Why it breaks:
- Retrospective is meant for completed epics
- Stopping mid-epic loses momentum
- Insights are incomplete (haven't finished the work)
- Next epic planning won't have full context
Right:
// Only when suggest_next says epicComplete: true
const next = await suggest_next('epic-19', lastStory);
if (next.epicComplete) {
// Now safe to retrospect
console.log(next.recommendation); // 'run_retrospective'
}
Related Skills
- story-completion-ceremony: The 7-step validation process before calling complete_story
- code-review-mode: Self-review checklist for code quality
- test-driven-development: Write tests before code
- always-plan-first: Plan changes before implementation
- explain-decisions: Document your reasoning for code choices
- use-sub-agents: When to delegate work to other agents
Real-World Examples from SessionGuardian
Complete Example: Story 19-5 Implementation Lifecycle
🟦 START: receive suggest_next → story 19-5
🔧 PHASE 1: Development
- Read story file (19-5-implement-context-preloading-service.md)
- Load preloaded context (dependencies, related skills)
- Implement StoryContextPreloadingService
- Write 18 unit tests
- Run tests (all pass)
- Coverage: 89%
✅ PHASE 2: Completion Ceremony
- Verify all 4 AC: ✅
- Tests + coverage: ✅ (18 tests, 89%)
- Edge cases: ✅ (null, empty, max limits)
- Self-review: ✅
- Update sprint-status.yaml: ✅
📋 PHASE 3: Call complete_story
bmad_workflow({
action: 'complete_story',
storyId: '19-5-implement-context-preloading-service',
validationEvidence: {
testsPassed: 18,
testsFailed: 0,
coveragePercent: 89,
codeReviewApproved: true,
notes: 'Implements 3 public methods + 2 private helpers. Preloads skills and story metadata based on epic context.'
}
});
🎯 PHASE 4: Get next work
const next = await suggest_next('epic-19', '19-5');
// Returns: {
// nextStoryId: '19-4-update-dev-story-workflow',
// status: 'ready',
// description: 'Now that context service exists,...'
// }
➡️ PHASE 5: Continue with 19-4
How to Recognize When You're NOT Following Orchestration Rules
You'll notice:
- Failing tests in stories that depend on YOUR changes
- Asking "what should I work on next?" repeatedly
- Manual edits to sprint-status.yaml
- Rework because dependencies weren't obvious
- Confusion about which stories are truly complete
Integration with session_guardian
Use Session Guardian to request confirmation before:
- Marking a story as complete (especially code stories)
- Escalating a blocked story to sprint manager
- Deviating from suggest_next recommendation
session_guardian({
title: 'Story Completion Request',
question:
'✅ Story 19-5: Implementation complete. Validation evidence gathered. Ready to mark complete?',
// User confirms → proceed with complete_story
// User declines → address issues, rerun ceremony
});
Troubleshooting
"suggest_next says work on story X but it seems blocked"
Solution: Return to suggest_next response and check blockedBy field. Escalate to sprint manager if true blocking issue exists.
"I disagree with the suggested story"
Solution: Check the recommendation reason in suggest_next response. If it doesn't match your context, escalate to sprint manager rather than choosing different work.
"Sprint-status.yaml is out of sync with actual completion"
Solution: Always use bmad_workflow:complete_story instead of manual edits. It keeps status synchronized.
"Retrospective triggered too early"
Solution: This only happens if suggest_next says epicComplete=true. Check if all stories are actually done in sprint-status.yaml.
Summary
Remember these 4 core rules:
- ✅ Always call suggest_next after completing a story
- ✅ Never manually search for next work
- ✅ Use story_id parameter when working with stories
- ✅ Validate with ceremony skill before calling complete_story
The orchestration system works when agents follow these rules. Breaking them creates debt, confusion, and delays.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?