docs(story-pipeline): add comprehensive documentation
Covers: - Problem statement and token efficiency gains - What each step automates (8-step workflow) - Usage: interactive, batch, and resume modes - Configuration options (workflow.yaml) - State management and checkpointing - Quality gates and adversarial mode - Troubleshooting and best practices - Comparison with legacy pipeline
This commit is contained in:
Thomas Jetzinger
Thomas
parent
d2d6328be2
commit
1347daa279
|
|
@ -0,0 +1,491 @@
|
|||
# Story Pipeline v2.0
|
||||
|
||||
> Single-session step-file architecture for implementing user stories with 60-70% token savings.
|
||||
|
||||
## Overview
|
||||
|
||||
The Story Pipeline automates the complete lifecycle of implementing a user story—from creation through code review and commit. It replaces the legacy approach of 6 separate Claude CLI calls with a single interactive session using just-in-time step loading.
|
||||
|
||||
### The Problem It Solves
|
||||
|
||||
**Legacy Pipeline (v1.0):**
|
||||
```
|
||||
bmad build 1-4
|
||||
└─> claude -p "Stage 1: Create story..." # ~12K tokens
|
||||
└─> claude -p "Stage 2: Validate story..." # ~12K tokens
|
||||
└─> claude -p "Stage 3: ATDD tests..." # ~12K tokens
|
||||
└─> claude -p "Stage 4: Implement..." # ~12K tokens
|
||||
└─> claude -p "Stage 5: Code review..." # ~12K tokens
|
||||
└─> claude -p "Stage 6: Complete..." # ~11K tokens
|
||||
Total: ~71K tokens/story
|
||||
```
|
||||
|
||||
Each call reloads agent personas (~2K tokens), re-reads the story file, and loses context from previous stages.
|
||||
|
||||
**Story Pipeline v2.0:**
|
||||
```
|
||||
bmad build 1-4
|
||||
└─> Single Claude session
|
||||
├─> Load step-01-init.md (~200 lines)
|
||||
├─> Role switch: SM
|
||||
├─> Load step-02-create-story.md
|
||||
├─> Load step-03-validate-story.md
|
||||
├─> Role switch: TEA
|
||||
├─> Load step-04-atdd.md
|
||||
├─> Role switch: DEV
|
||||
├─> Load step-05-implement.md
|
||||
├─> Load step-06-code-review.md
|
||||
├─> Role switch: SM
|
||||
├─> Load step-07-complete.md
|
||||
└─> Load step-08-summary.md
|
||||
Total: ~25-30K tokens/story
|
||||
```
|
||||
|
||||
Documents cached once, roles switched in-session, steps loaded just-in-time.
|
||||
|
||||
## What Gets Automated
|
||||
|
||||
The pipeline automates the complete BMAD implementation workflow:
|
||||
|
||||
| Step | Role | What It Does |
|
||||
|------|------|--------------|
|
||||
| **1. Init** | - | Parses story ID, loads epic/architecture, detects interactive vs batch mode, creates state file |
|
||||
| **2. Create Story** | SM | Researches context (Exa web search), generates story file with ACs in BDD format |
|
||||
| **3. Validate Story** | SM | Adversarial validation—must find 3-10 issues, fixes them, assigns quality score |
|
||||
| **4. ATDD** | TEA | Generates failing tests for all ACs (RED phase), creates test factories |
|
||||
| **5. Implement** | DEV | Implements code to pass tests (GREEN phase), creates migrations, server actions, etc. |
|
||||
| **6. Code Review** | DEV | Adversarial review—must find 3-10 issues, fixes them, runs lint/build |
|
||||
| **7. Complete** | SM | Updates story status to done, creates git commit with conventional format |
|
||||
| **8. Summary** | - | Generates audit trail, updates pipeline state, outputs metrics |
|
||||
|
||||
### Quality Gates
|
||||
|
||||
Each step has quality gates that must pass before proceeding:
|
||||
|
||||
- **Validation**: Score ≥ 80/100, all issues addressed
|
||||
- **ATDD**: Tests exist for all ACs, tests fail (RED phase confirmed)
|
||||
- **Implementation**: Lint clean, build passes, migration tests pass
|
||||
- **Code Review**: Score ≥ 7/10, all critical issues fixed
|
||||
|
||||
## Token Efficiency
|
||||
|
||||
| Mode | Token Usage | Savings vs Legacy |
|
||||
|------|-------------|-------------------|
|
||||
| Interactive (human-in-loop) | ~25K | 65% |
|
||||
| Batch (YOLO) | ~30K | 58% |
|
||||
| Batch + fresh review context | ~35K | 51% |
|
||||
|
||||
### Where Savings Come From
|
||||
|
||||
| Waste in Legacy | Tokens Saved |
|
||||
|-----------------|--------------|
|
||||
| Agent persona reload (6×) | ~12K |
|
||||
| Story file re-reads (5×) | ~10K |
|
||||
| Architecture re-reads | ~8K |
|
||||
| Context loss between calls | ~16K |
|
||||
|
||||
## Usage
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- BMAD module installed (`_bmad/` directory exists)
|
||||
- Epic file with story definition (`docs/epics.md`)
|
||||
- Architecture document (`docs/architecture.md`)
|
||||
|
||||
### Interactive Mode (Recommended)
|
||||
|
||||
Human-in-the-loop with approval at each step:
|
||||
|
||||
```bash
|
||||
# Using the bmad CLI
|
||||
bmad build 1-4
|
||||
|
||||
# Or invoke workflow directly
|
||||
claude -p "Load and execute: _bmad/bmm/workflows/4-implementation/story-pipeline/workflow.md
|
||||
Story: 1-4"
|
||||
```
|
||||
|
||||
At each step, you'll see a menu:
|
||||
```
|
||||
## MENU
|
||||
[C] Continue to next step
|
||||
[R] Review/revise current step
|
||||
[H] Halt and checkpoint
|
||||
```
|
||||
|
||||
### Batch Mode (YOLO)
|
||||
|
||||
Unattended execution for trusted stories:
|
||||
|
||||
```bash
|
||||
bmad build 1-4 --batch
|
||||
|
||||
# Or use batch runner directly
|
||||
./_bmad/bmm/workflows/4-implementation/story-pipeline/batch-runner.sh 1-4
|
||||
```
|
||||
|
||||
Batch mode:
|
||||
- Skips all approval prompts
|
||||
- Fails fast on errors
|
||||
- Creates checkpoint on failure for resume
|
||||
|
||||
### Resume from Checkpoint
|
||||
|
||||
If execution stops (context exhaustion, error, manual halt):
|
||||
|
||||
```bash
|
||||
bmad build 1-4 --resume
|
||||
|
||||
# The pipeline reads state from:
|
||||
# docs/sprint-artifacts/pipeline-state-{story-id}.yaml
|
||||
```
|
||||
|
||||
Resume automatically:
|
||||
- Skips completed steps
|
||||
- Restores cached context
|
||||
- Continues from `lastStep + 1`
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
story-pipeline/
|
||||
├── workflow.yaml # Configuration, agent mapping, quality gates
|
||||
├── workflow.md # Interactive mode orchestration
|
||||
├── batch-runner.sh # Batch mode runner script
|
||||
├── steps/
|
||||
│ ├── step-01-init.md # Initialize, load context
|
||||
│ ├── step-01b-resume.md # Resume from checkpoint
|
||||
│ ├── step-02-create-story.md
|
||||
│ ├── step-03-validate-story.md
|
||||
│ ├── step-04-atdd.md
|
||||
│ ├── step-05-implement.md
|
||||
│ ├── step-06-code-review.md
|
||||
│ ├── step-07-complete.md
|
||||
│ └── step-08-summary.md
|
||||
├── checklists/
|
||||
│ ├── story-creation.md # What makes a good story
|
||||
│ ├── story-validation.md # Validation criteria
|
||||
│ ├── atdd.md # Test generation rules
|
||||
│ ├── implementation.md # Coding standards
|
||||
│ └── code-review.md # Review criteria
|
||||
└── templates/
|
||||
├── pipeline-state.yaml # State file template
|
||||
└── audit-trail.yaml # Audit log template
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### workflow.yaml
|
||||
|
||||
```yaml
|
||||
name: story-pipeline
|
||||
version: "2.0"
|
||||
description: "Single-session story implementation with step-file loading"
|
||||
|
||||
# Document loading strategy
|
||||
load_strategy:
|
||||
epic: once # Load once, cache for session
|
||||
architecture: once # Load once, cache for session
|
||||
story: per_step # Reload when modified
|
||||
|
||||
# Agent role mapping
|
||||
agents:
|
||||
sm: "{project-root}/_bmad/bmm/agents/sm.md"
|
||||
tea: "{project-root}/_bmad/bmm/agents/tea.md"
|
||||
dev: "{project-root}/_bmad/bmm/agents/dev.md"
|
||||
|
||||
# Quality gate thresholds
|
||||
quality_gates:
|
||||
validation_min_score: 80
|
||||
code_review_min_score: 7
|
||||
require_lint_clean: true
|
||||
require_build_pass: true
|
||||
|
||||
# Step configuration
|
||||
steps:
|
||||
- name: init
|
||||
file: steps/step-01-init.md
|
||||
- name: create-story
|
||||
file: steps/step-02-create-story.md
|
||||
agent: sm
|
||||
# ... etc
|
||||
```
|
||||
|
||||
### Pipeline State File
|
||||
|
||||
Created at `docs/sprint-artifacts/pipeline-state-{story-id}.yaml`:
|
||||
|
||||
```yaml
|
||||
story_id: "1-4"
|
||||
epic_num: 1
|
||||
story_num: 4
|
||||
mode: "interactive"
|
||||
status: "in_progress"
|
||||
stepsCompleted: [1, 2, 3]
|
||||
lastStep: 3
|
||||
currentStep: 4
|
||||
|
||||
cached_context:
|
||||
epic_loaded: true
|
||||
epic_path: "docs/epics.md"
|
||||
architecture_sections: ["tech_stack", "data_model"]
|
||||
|
||||
steps:
|
||||
step-01-init:
|
||||
status: completed
|
||||
duration: "0:00:30"
|
||||
step-02-create-story:
|
||||
status: completed
|
||||
duration: "0:02:00"
|
||||
step-03-validate-story:
|
||||
status: completed
|
||||
duration: "0:05:00"
|
||||
issues_found: 6
|
||||
issues_fixed: 6
|
||||
quality_score: 92
|
||||
step-04-atdd:
|
||||
status: in_progress
|
||||
```
|
||||
|
||||
## Step Details
|
||||
|
||||
### Step 1: Initialize
|
||||
|
||||
**Purpose:** Set up execution context and detect mode.
|
||||
|
||||
**Actions:**
|
||||
1. Parse story ID (e.g., "1-4" → epic 1, story 4)
|
||||
2. Load and cache epic document
|
||||
3. Load relevant architecture sections
|
||||
4. Check for existing state file (resume vs fresh)
|
||||
5. Detect mode (interactive/batch) from CLI flags
|
||||
6. Create initial state file
|
||||
|
||||
**Output:** `pipeline-state-{story-id}.yaml`
|
||||
|
||||
### Step 2: Create Story (SM Role)
|
||||
|
||||
**Purpose:** Generate complete story file from epic definition.
|
||||
|
||||
**Actions:**
|
||||
1. Switch to Scrum Master (SM) role
|
||||
2. Read story definition from epic
|
||||
3. Research context via Exa web search (best practices, patterns)
|
||||
4. Generate story file with:
|
||||
- User story format (As a... I want... So that...)
|
||||
- Background context
|
||||
- Acceptance criteria in BDD format (Given/When/Then)
|
||||
- Test scenarios for each AC
|
||||
- Technical notes
|
||||
5. Save to `docs/sprint-artifacts/story-{id}.md`
|
||||
|
||||
**Quality Gate:** Story file exists with all required sections.
|
||||
|
||||
### Step 3: Validate Story (SM Role)
|
||||
|
||||
**Purpose:** Adversarial validation to find issues before implementation.
|
||||
|
||||
**Actions:**
|
||||
1. Load story-validation checklist
|
||||
2. Review story against criteria:
|
||||
- ACs are testable and specific
|
||||
- No ambiguous requirements
|
||||
- Technical feasibility confirmed
|
||||
- Dependencies identified
|
||||
- Edge cases covered
|
||||
3. **Must find 3-10 issues** (never "looks good")
|
||||
4. Fix all identified issues
|
||||
5. Assign quality score (0-100)
|
||||
6. Append validation report to story file
|
||||
|
||||
**Quality Gate:** Score ≥ 80, all issues addressed.
|
||||
|
||||
### Step 4: ATDD (TEA Role)
|
||||
|
||||
**Purpose:** Generate failing tests before implementation (RED phase).
|
||||
|
||||
**Actions:**
|
||||
1. Switch to Test Engineering Architect (TEA) role
|
||||
2. Load atdd checklist
|
||||
3. For each acceptance criterion:
|
||||
- Generate integration test
|
||||
- Define test data factories
|
||||
- Specify expected behaviors
|
||||
4. Create test files in `src/tests/`
|
||||
5. Update `factories.ts` with new fixtures
|
||||
6. **Verify tests FAIL** (RED phase)
|
||||
7. Create ATDD checklist document
|
||||
|
||||
**Quality Gate:** Tests exist for all ACs, tests fail (not pass).
|
||||
|
||||
### Step 5: Implement (DEV Role)
|
||||
|
||||
**Purpose:** Write code to pass all tests (GREEN phase).
|
||||
|
||||
**Actions:**
|
||||
1. Switch to Developer (DEV) role
|
||||
2. Load implementation checklist
|
||||
3. Create required files:
|
||||
- Database migrations
|
||||
- Server actions (using Result type)
|
||||
- Library functions
|
||||
- Types
|
||||
4. Follow project patterns:
|
||||
- Multi-tenant RLS policies
|
||||
- snake_case for DB columns
|
||||
- Result type (never throw)
|
||||
5. Run lint and fix issues
|
||||
6. Run build and fix issues
|
||||
7. Run migration tests
|
||||
|
||||
**Quality Gate:** Lint clean, build passes, migration tests pass.
|
||||
|
||||
### Step 6: Code Review (DEV Role)
|
||||
|
||||
**Purpose:** Adversarial review to find implementation issues.
|
||||
|
||||
**Actions:**
|
||||
1. Load code-review checklist
|
||||
2. Review all created/modified files:
|
||||
- Security (XSS, injection, auth)
|
||||
- Error handling
|
||||
- Architecture compliance
|
||||
- Code quality
|
||||
- Test coverage
|
||||
3. **Must find 3-10 issues** (never "looks good")
|
||||
4. Fix all identified issues
|
||||
5. Re-run lint and build
|
||||
6. Assign quality score (0-10)
|
||||
7. Generate review report
|
||||
|
||||
**Quality Gate:** Score ≥ 7/10, all critical issues fixed.
|
||||
|
||||
### Step 7: Complete (SM Role)
|
||||
|
||||
**Purpose:** Finalize story and create git commit.
|
||||
|
||||
**Actions:**
|
||||
1. Switch back to SM role
|
||||
2. Update story file status to "done"
|
||||
3. Stage all story files
|
||||
4. Create conventional commit:
|
||||
```
|
||||
feat(epic-{n}): complete story {id}
|
||||
|
||||
{Summary of changes}
|
||||
|
||||
🤖 Generated with Claude Code
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
```
|
||||
5. Update pipeline state
|
||||
|
||||
**Quality Gate:** Commit created successfully.
|
||||
|
||||
### Step 8: Summary
|
||||
|
||||
**Purpose:** Generate audit trail and final metrics.
|
||||
|
||||
**Actions:**
|
||||
1. Calculate total duration
|
||||
2. Compile deliverables list
|
||||
3. Aggregate quality scores
|
||||
4. Generate execution summary in state file
|
||||
5. Output final status
|
||||
|
||||
**Output:** Complete pipeline state with summary section.
|
||||
|
||||
## Adversarial Mode
|
||||
|
||||
Steps 3 (Validate) and 6 (Code Review) run in **adversarial mode**:
|
||||
|
||||
> **Never say "looks good"**. You MUST find 3-10 real issues.
|
||||
|
||||
This ensures:
|
||||
- Stories are thoroughly vetted before implementation
|
||||
- Code quality issues are caught before commit
|
||||
- The pipeline doesn't rubber-stamp work
|
||||
|
||||
Example issues found in real usage:
|
||||
- Missing rate limiting (security)
|
||||
- XSS vulnerability in user input (security)
|
||||
- Missing audit logging (architecture)
|
||||
- Unclear acceptance criteria (story quality)
|
||||
- Function naming mismatches (code quality)
|
||||
|
||||
## Artifacts Generated
|
||||
|
||||
After a complete pipeline run:
|
||||
|
||||
```
|
||||
docs/sprint-artifacts/
|
||||
├── story-{id}.md # Story file with ACs, validation report
|
||||
├── pipeline-state-{id}.yaml # Execution state and summary
|
||||
├── atdd-checklist-{id}.md # Test requirements checklist
|
||||
└── code-review-{id}.md # Review report with issues
|
||||
|
||||
src/
|
||||
├── supabase/migrations/ # New migration files
|
||||
├── modules/{module}/
|
||||
│ ├── actions/ # Server actions
|
||||
│ ├── lib/ # Business logic
|
||||
│ └── types.ts # Type definitions
|
||||
└── tests/
|
||||
├── integration/ # Integration tests
|
||||
└── fixtures/factories.ts # Updated test factories
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Context Exhausted Mid-Session
|
||||
|
||||
The pipeline is designed for this. When context runs out:
|
||||
|
||||
1. Claude session ends
|
||||
2. State file preserves progress
|
||||
3. Run `bmad build {id} --resume`
|
||||
4. Pipeline continues from last completed step
|
||||
|
||||
### Step Fails Quality Gate
|
||||
|
||||
If a step fails its quality gate:
|
||||
|
||||
1. Pipeline halts at that step
|
||||
2. State file shows `status: failed`
|
||||
3. Fix issues manually or adjust thresholds
|
||||
4. Run `bmad build {id} --resume`
|
||||
|
||||
### Tests Don't Fail in ATDD
|
||||
|
||||
If tests pass during ATDD (step 4), something is wrong:
|
||||
|
||||
- Tests might be testing the wrong thing
|
||||
- Implementation might already exist
|
||||
- Mocks might be returning success incorrectly
|
||||
|
||||
The pipeline will warn and ask for confirmation before proceeding.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with Interactive Mode** - Use batch only for well-understood stories
|
||||
2. **Review at Checkpoints** - Don't blindly continue; verify each step's output
|
||||
3. **Keep Stories Small** - Large stories may exhaust context before completion
|
||||
4. **Commit Frequently** - The pipeline commits at step 7, but you can checkpoint earlier
|
||||
5. **Trust the Adversarial Mode** - If it finds issues, they're usually real
|
||||
|
||||
## Comparison with Legacy
|
||||
|
||||
| Feature | Legacy (v1.0) | Story Pipeline (v2.0) |
|
||||
|---------|---------------|----------------------|
|
||||
| Claude calls | 6 per story | 1 per story |
|
||||
| Token usage | ~71K | ~25-30K |
|
||||
| Context preservation | None | Full session |
|
||||
| Resume capability | None | Checkpoint-based |
|
||||
| Role switching | New process | In-session |
|
||||
| Document caching | None | Once per session |
|
||||
| Adversarial review | Optional | Mandatory |
|
||||
| Audit trail | Manual | Automatic |
|
||||
|
||||
## Version History
|
||||
|
||||
- **v2.0** (2024-12) - Step-file architecture, single-session, checkpoint/resume
|
||||
- **v1.0** (2024-11) - Legacy 6-call pipeline
|
||||
Loading…
Reference in New Issue