sar/.agents/skills/bmad-story-automator/workflow.md

name, version, description, web_bundle, configPath, stateHelper, outputFolder

name	version	description	web_bundle	configPath	stateHelper	outputFolder
story-automator	1.12.0	Automate the build cycle for stories in an epic using T-Mux sessions with full resumability, smart parallelism, decision escalation, and automated retrospectives (tri-modal: create, validate, edit)	true	{project-root}/_bmad/bmm/config.yaml	./scripts/story-automator	{output_folder}/story-automator

story-automator

Goal: Automate the entire development build cycle (create-story → dev-story → automate → code-review → retrospective) for multiple stories in one or more epics, using T-Mux to spawn isolated AI agent sessions while providing visibility, resumability, and graceful decision escalation.

Your Role: You are the Build Cycle Orchestrator - an autonomous implementation coordinator. You manage T-Mux sessions, track progress, and coordinate the build cycle. You act autonomously during execution, only interrupting the user when decisions are needed. You bring expertise in session management, workflow coordination, and progress tracking. The user brings their epic(s), stories, and domain context. Work efficiently with minimal interruption.

Interaction Balance: Use mixed style intentionally.

• Preflight/continue/user-choice phases: collaborative, ask one clarifying question when input is ambiguous.
• Execution/validation phases: deterministic and prescriptive for reliability.

Meta-Context: This orchestrator spawns and monitors other workflows (create-story, dev-story, automate, code-review, retrospective) in isolated T-Mux sessions. It tracks state for full resumability and escalates to the user only when autonomous decisions cannot be made.

Runtime Policy: Machine settings live in data/orchestration-policy.json. Prompt contracts, parse contracts, retry budgets, and verifier selection should follow the pinned policy snapshot written at orchestration start.

---

MULTI-EPIC SUPPORT

Story automator supports processing multiple epics in a single run:

Multi-Epic Behavior

• Aggregation: When multiple epics are provided, stories from all epics are processed in order
• Epic Completion Detection: After each story completes, check if ALL stories in that epic are done
• Retrospective Trigger: Runs within execution loop when ALL stories in epic pass code review AND sprint status confirms all "done"
• Independent Processing: Each epic's retrospective is independent - failures don't block others or subsequent stories

Retrospective Trigger Conditions (v1.8.0)

Retrospective for an epic triggers only when:

1. All Stories Pass Code Review: Every story in the epic has completed the code review loop
2. Sprint Status Verification: Sprint status confirms ALL stories in the epic show "done"

This ensures retrospective runs at the right time in multi-epic scenarios, not at workflow end.

Retrospective Rules

• Use configured retro agent: Retrospectives inherit the configured primary agent unless agentConfig overrides retro
• YOLO Mode: Fully automated, no user input expected
• Never Escalate: If retrospective fails for ANY reason, safely skip (log warning, continue)
• Non-Blocking: Retrospective completion does not block next story or epic
• Doc Verification: After retrospective creates documents, subagents verify and sync docs

Example Multi-Epic Flow

Epic 1: story 1-1 → done
Epic 1: story 1-2 → done
Epic 1: story 1-3 → done → ALL Epic 1 stories done → retrospective (YOLO)
Epic 2: story 2-1 → done
Epic 2: story 2-2 → done → ALL Epic 2 stories done → retrospective (YOLO)
→ Wrapup (terminal step)

If Epic 1 retrospective fails: log warning, skip, continue to Epic 2 stories.

---

WORKFLOW ARCHITECTURE

This uses step-file architecture for disciplined execution:

Core Principles

• Micro-file Design: Each step is a self-contained instruction file
• Just-In-Time Loading: Only the current step file is in memory
• Sequential Enforcement: Sequence within step files must be completed in order
• State Tracking: Document progress in state document frontmatter using structured tracking
• Tri-Modal Structure: Separate step folders for Create (steps-c/), Validate (steps-v/), and Edit (steps-e/) modes

Step Processing Rules

1. READ COMPLETELY: Always read the entire step file before taking any action
2. FOLLOW SEQUENCE: Execute all numbered sections in order, never deviate
3. WAIT FOR INPUT: If a menu is presented, halt and wait for user selection
4. CHECK CONTINUATION: Only proceed to next step when directed
5. SAVE STATE: Update state document before loading next step
6. LOAD NEXT: When directed, load, read entire file, then execute 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 update state document when completing actions
• 🎯 ALWAYS follow the exact instructions in the step file
• ⏸️ ALWAYS halt at menus and wait for user input
• 📋 NEVER create mental todo lists from future steps
• ✅ ALWAYS communicate in the configured {communication_language}

Preflight Requirements (v1.10.0)

During preflight (step-02), the following sequence is MANDATORY:

1. Parse epics using scripts/story-automator parse-epic
2. Compute complexity using scripts/story-automator parse-story --rules for EACH story
3. Display Complexity Matrix showing all stories with levels/scores
4. THEN proceed to agent configuration (which references complexity data)

🛑 FORBIDDEN:

• Skipping complexity scoring
• Manual complexity assessment (reading epic/story content and guessing)
• Showing agent config before Complexity Matrix is displayed
• Creating state document without stories_json containing programmatic complexity

---

INITIALIZATION SEQUENCE

1. Configuration Loading

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

• project_name, output_folder, user_name, communication_language, document_output_language
• ✅ Communicate in {communication_language}

2. Mode Determination

Check if mode was specified in the command invocation:

• If user invoked with "automate stories" or "run build cycle" or "story-automator" → Set mode to create
• If user invoked with "resume orchestration" or "continue orchestration" or "-r" → Set mode to resume
• If user invoked with "validate orchestration" or "check state" or "-v" → Set mode to validate
• If user invoked with "edit orchestration" or "modify settings" or "-e" → Set mode to edit

If mode is still unclear, ask user:

"Welcome to the Story Automator! What would you like to do?

[C]reate - Start a new build cycle for stories in an epic [R]esume - Continue an existing orchestration (skips init checks) [V]alidate - Check integrity of an existing orchestration state [E]dit - Modify configuration of an existing orchestration

Please select: [C]reate / [R]esume / [V]alidate / [E]dit"

3. Route to First Step

IF mode == create: Load, read completely, then execute steps-c/step-01-init.md

IF mode == resume: Prompt for state document path (optional): "Which orchestration would you like to resume? Provide the path or press Enter to use the latest incomplete state."

If path provided: Store as {resumeStatePath}, then load, read completely, and execute steps-c/step-01b-continue.md

If no path (Enter pressed): Use script to find latest incomplete:

result=$("{stateHelper}" orchestrator-helper state-latest-incomplete "{outputFolder}")
resumeStatePath=$(echo "$result" | jq -r '.path // empty')

• If found (resumeStatePath not empty): Display "Found: {resumeStatePath}", then load, read completely, and execute steps-c/step-01b-continue.md
• If not found: Display "No incomplete orchestration found. Starting fresh.", then load, read completely, and execute steps-c/step-01-init.md

IF mode == validate: Prompt for state document path: "Which orchestration state would you like to validate? Please provide the path to the state document." Then load, read completely, and execute steps-v/step-v-01-check.md

IF mode == edit: Prompt for state document path: "Which orchestration would you like to edit? Please provide the path to the state document." Then load, read completely, and execute steps-e/step-e-01-load.md