julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
173 lines
8.4 KiB
Markdown
173 lines
8.4 KiB
Markdown
---
|
|
name: story-automator
|
|
version: "1.12.0"
|
|
description: "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)"
|
|
web_bundle: true
|
|
configPath: '{project-root}/_bmad/bmm/config.yaml'
|
|
stateHelper: './scripts/story-automator'
|
|
outputFolder: '{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:
|
|
```bash
|
|
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`
|