feat: transform tech-spec workflow into intelligent Quick Spec Flow for Level 0-1

This major enhancement revolutionizes the tech-spec workflow from a basic template-filling exercise into a context-aware, intelligent planning system for rapid development of bug fixes and small features.

## Tech-Spec Workflow Transformation (11 files)

### Core Workflow Intelligence (instructions.md)
- Add standalone mode with interactive level/field-type detection
- Implement brownfield convention detection and user confirmation
- Integrate WebSearch for current framework versions and starter templates
- Add comprehensive context discovery (stack, patterns, dependencies)
- Implement auto-validation with quality scoring (always runs)
- Add UX/UI considerations capture for user-facing changes
- Add test framework detection and pattern analysis
- Transform from batch generation to living document approach

### Comprehensive Tech-Spec Template (tech-spec-template.md)
- Expand from 8 to 23 sections for complete context
- Add Context section (available docs, project stack, existing structure)
- Add Development Context (conventions, test framework, existing code)
- Add UX/UI Considerations section
- Add Developer Resources (file paths, key locations, testing)
- Add Integration Points and Configuration Changes
- All sections populated via template-output tags during workflow

### Enhanced Story Generation
- Level 0 (instructions-level0-story.md): Extract from comprehensive tech-spec
- Level 1 (instructions-level1-stories.md): Add story sequence validation, AC quality checks
- User Story Template: Add Dev Agent Record sections for implementation tracking
- Epic Template: Complete rewrite with proper structure and variables

### Validation & Quality (checklist.md)
- Add context gathering completeness checks
- Add definitiveness validation (no "use X or Y" statements)
- Add brownfield integration quality scoring
- Add stack alignment verification
- Add implementation readiness assessment
- Auto-generates validation report with scores

### Configuration (workflow.yaml)
- Add runtime variables: project_level, project_type, development_context, change_type, field_type
- Enable standalone operation without workflow-status.yaml
- Support both workflow-init integration and quick-start mode

## Phase 4 Integration (3 files)

### Story Context Workflow
- Add tech_spec to input_file_patterns (recognizes as authoritative source)
- Update instructions to prioritize tech-spec for Level 0-1 projects
- Tech-spec provides brownfield analysis, framework details, existing patterns

### Create Story Workflow
- Add tech_spec to input_file_patterns
- Enable story generation from tech-spec (alternative to PRD)
- Supports both Quick Spec Flow and traditional BMM flow

## Documentation (2 new files)

### Quick Spec Flow Guide (docs/quick-spec-flow.md)
- Comprehensive 595-line guide for Level 0-1 rapid development
- Complete user journey examples (bug fix, small feature)
- Context discovery explanation (stack, brownfield, conventions)
- Auto-validation details and benefits
- Integration with Phase 4 workflows
- Comparison: Quick Spec vs Full BMM
- Real-world examples and best practices

### Scale Adaptive System (docs/scale-adaptive-system.md)
- Complete 950-line technical guide to BMad Method's 5-level system
- Key terminology: Analysis, Tech-Spec, Epic-Tech-Spec, Architecture
- Level 0-4 workflows, planning docs, and progression
- Brownfield emphasis: document-project required first
- Tech-spec (upfront, Level 0-1) vs epic-tech-spec (during implementation, Level 2-4)
- Architecture document replaces tech-spec at Level 2+ (scales with complexity)
- Retrospectives after each epic in multi-epic projects
- Workflow path configuration reference

### README Updates
- Add Quick Spec Flow announcement with benefits
- Link to Scale Adaptive System documentation
- Clarify when to use Quick Spec Flow vs Full BMM

## Key Features

### Context-Aware Intelligence
- Auto-detects project stack from package.json, requirements.txt, etc.
- Analyzes brownfield codebases using document-project output
- Detects code conventions and confirms with user before proceeding
- Uses WebSearch for up-to-date framework info and starter templates

### Brownfield Respect
- Detects existing patterns (code style, test framework, naming conventions)
- Asks user for confirmation before applying conventions
- Adapts to existing code vs forcing changes
- References document-project analysis for comprehensive context

### Auto-Validation
- Always runs (not optional)
- Validates context gathering, definitiveness, brownfield integration
- Scores tech-spec quality and implementation readiness
- Validates story sequence for Level 1 (no forward dependencies)

### Living Document Approach
- Write to tech-spec continuously during discovery
- Progressive refinement vs batch generation
- Template variables populated via template-output tags in real-time

## Breaking Changes

None - all changes are additive and backward compatible.

## Impact

This transformation enables:
- Bug fixes and small features implemented in minutes vs hours
- Automatic stack detection and brownfield analysis
- Respect for existing conventions and patterns
- Current best practices via WebSearch integration
- Comprehensive context that can replace story-context for simple efforts
- Seamless integration with Phase 4 implementation workflows

Quick Spec Flow now provides a **true fast path from idea to implementation** for Level 0-1 projects while maintaining quality through auto-validation and comprehensive context gathering.
This commit is contained in:
Brian Madison
2025-11-02 08:17:23 -06:00
parent 3d4ea5ffd2
commit 8a00f8ad70
14 changed files with 3342 additions and 222 deletions

View File

@@ -1,11 +1,13 @@
# Tech-Spec Workflow Validation Checklist
**Purpose**: Validate tech-spec workflow outputs are definitive, complete, and implementation-ready.
**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.
**Scope**: Levels 0-1 software projects
**Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)
**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
---
## 1. Output Files Exist
@@ -14,38 +16,107 @@
- [ ] Story file(s) created in dev_story_location
- Level 0: 1 story file (story-{slug}.md)
- Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md)
- [ ] bmm-workflow-status.md updated to Phase 4
- [ ] No unfilled {{template_variables}}
- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
- [ ] No unfilled {{template_variables}} in any files
---
## 2. Tech-Spec Definitiveness (CRITICAL)
## 2. Context Gathering (NEW - CRITICAL)
### Document Discovery
- [ ] **Existing documents loaded**: Product brief, research docs found and incorporated (if they exist)
- [ ] **Document-project output**: Checked for {output_folder}/docs/index.md (brownfield codebase map)
- [ ] **Sharded documents**: If sharded versions found, ALL sections loaded and synthesized
- [ ] **Context summary**: loaded_documents_summary lists all sources used
### Project Stack Detection
- [ ] **Setup files identified**: package.json, requirements.txt, or equivalent found and parsed
- [ ] **Framework detected**: Exact framework name and version captured (e.g., "Express 4.18.2")
- [ ] **Dependencies extracted**: All production dependencies with specific versions
- [ ] **Dev tools identified**: TypeScript, Jest, ESLint, pytest, etc. with versions
- [ ] **Scripts documented**: Available npm/pip/etc scripts identified
- [ ] **Stack summary**: project_stack_summary is complete and accurate
### Brownfield Analysis (if applicable)
- [ ] **Directory structure**: Main code directories identified and documented
- [ ] **Code patterns**: Dominant patterns identified (class-based, functional, MVC, etc.)
- [ ] **Naming conventions**: Existing conventions documented (camelCase, snake_case, etc.)
- [ ] **Key modules**: Important existing modules/services identified
- [ ] **Testing patterns**: Test framework and patterns documented
- [ ] **Structure summary**: existing_structure_summary is comprehensive
---
## 3. Tech-Spec Definitiveness (CRITICAL)
### No Ambiguity Allowed
- [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include"
- [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions
- ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2"
- ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2 (from package.json)"
- ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston"
- [ ] **Definitive decisions**: Every technical choice is final, not a proposal
- [ ] **Stack-aligned**: Decisions reference detected project stack
### Implementation Clarity
- [ ] Source tree shows EXACT file paths (not "somewhere in src/")
- [ ] Each file marked as create/modify/delete
- [ ] Technical approach describes SPECIFIC implementation
- [ ] Implementation stack has complete toolchain with versions
- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions
- ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method"
- ❌ BAD: "Update some files in the services folder"
- [ ] **Technical approach**: Describes SPECIFIC implementation using detected stack
- [ ] **Existing patterns**: Documents brownfield patterns to follow (if applicable)
- [ ] **Integration points**: Specific modules, APIs, services identified
---
## 3. Story Quality
## 4. Context-Rich Content (NEW)
### Context Section
- [ ] **Available Documents**: Lists all loaded documents
- [ ] **Project Stack**: Complete framework and dependency information
- [ ] **Existing Codebase Structure**: Brownfield analysis or greenfield notation
### The Change Section
- [ ] **Problem Statement**: Clear, specific problem definition
- [ ] **Proposed Solution**: Concrete solution approach
- [ ] **Scope In/Out**: Clear boundaries defined
### Development Context Section
- [ ] **Relevant Existing Code**: References to specific files and line numbers (brownfield)
- [ ] **Framework Dependencies**: Complete list with exact versions from project
- [ ] **Internal Dependencies**: Internal modules listed
- [ ] **Configuration Changes**: Specific config file updates identified
### Developer Resources Section
- [ ] **File Paths Reference**: Complete list of all files involved
- [ ] **Key Code Locations**: Functions, classes, modules with file:line references
- [ ] **Testing Locations**: Specific test directories and patterns
- [ ] **Documentation Updates**: Docs that need updating identified
---
## 5. Story Quality
### Story Format
- [ ] All stories use "As a [role], I want [capability], so that [benefit]" format
- [ ] Each story has numbered acceptance criteria
- [ ] Tasks reference AC numbers: (AC: #1), (AC: #2)
- [ ] Dev Notes section links back to tech-spec.md
- [ ] Dev Notes section links to tech-spec.md
### Story Context Integration (NEW)
- [ ] **Tech-Spec Reference**: Story explicitly references tech-spec.md as primary context
- [ ] **Dev Agent Record**: Includes all required sections (Context Reference, Agent Model, etc.)
- [ ] **Test Results section**: Placeholder ready for dev execution
- [ ] **Review Notes section**: Placeholder ready for code review
### Story Sequencing (If Level 1)
@@ -56,38 +127,66 @@
### Coverage
- [ ] Story acceptance criteria derived from tech-spec testing section
- [ ] Story acceptance criteria derived from tech-spec
- [ ] Story tasks map to tech-spec implementation guide
- [ ] Files in stories match tech-spec source tree
- [ ] Key code references align with tech-spec Developer Resources
---
## 4. Workflow Status Integration
## 6. Epic Quality (Level 1 Only)
- [ ] bmm-workflow-status.md shows current_phase = "4-Implementation"
- [ ] Phase 2 ("2-Plan") marked complete
- [ ] First story in TODO section, others in BACKLOG (if Level 1)
- [ ] Next action clear (review story, run story-ready)
- [ ] **Epic title**: User-focused outcome (not implementation detail)
- [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
- [ ] **Epic goal**: Clear purpose and value statement
- [ ] **Epic scope**: Boundaries clearly defined
- [ ] **Success criteria**: Measurable outcomes
- [ ] **Story map**: Visual representation of epic → stories
- [ ] **Implementation sequence**: Logical story ordering with dependencies
- [ ] **Tech-spec reference**: Links back to tech-spec.md
---
## 5. Readiness for Implementation
## 7. Workflow Status Integration
- [ ] Developer can start coding from tech-spec alone
- [ ] All technical questions answered definitively
- [ ] Testing approach clear and verifiable
- [ ] Deployment strategy documented
- [ ] bmm-workflow-status.yaml updated (if exists)
- [ ] Current phase reflects tech-spec completion
- [ ] Progress percentage updated appropriately
- [ ] Next workflow clearly identified
---
## 6. Critical Failures (Auto-Fail)
## 8. Implementation Readiness (NEW - ENHANCED)
### Can Developer Start Immediately?
- [ ] **All context available**: Brownfield analysis + stack details + existing patterns
- [ ] **No research needed**: Developer doesn't need to hunt for framework versions or patterns
- [ ] **Specific file paths**: Developer knows exactly which files to create/modify
- [ ] **Code references**: Can find similar code to reference (brownfield)
- [ ] **Testing clear**: Knows what to test and how
- [ ] **Deployment documented**: Knows how to deploy and rollback
### Tech-Spec Replaces Story-Context?
- [ ] **Comprehensive enough**: Contains all info typically in story-context XML
- [ ] **Brownfield analysis**: If applicable, includes codebase reconnaissance
- [ ] **Framework specifics**: Exact versions and usage patterns
- [ ] **Pattern guidance**: Shows examples of existing patterns to follow
---
## 9. Critical Failures (Auto-Fail)
- [ ]**Non-definitive technical decisions** (any "option A or B" or vague choices)
- [ ]**Missing versions** (framework/library without specific version)
- [ ]**Stories don't match template** (incompatible with story-context/dev-story workflows)
- [ ]**Missing tech-spec sections** (required section missing from tech-spec.md)
- [ ]**Context not gathered** (didn't check for document-project, setup files, etc.)
- [ ]**Stack mismatch** (decisions don't align with detected project stack)
- [ ]**Stories don't match template** (missing Dev Agent Record sections)
- [ ]**Missing tech-spec sections** (required section missing from enhanced template)
- [ ]**Stories have forward dependencies** (would break sequential implementation)
- [ ]**Vague source tree** (file changes not specific)
- [ ]**Vague source tree** (file changes not specific with actions)
- [ ]**No brownfield analysis** (when document-project output exists but wasn't used)
---
@@ -95,13 +194,21 @@
**Document any findings:**
- Definitiveness score: [All definitive / Some ambiguity / Significant ambiguity]
- Strengths:
- Issues to address:
- Recommended actions:
- **Context Gathering Score**: [Comprehensive / Partial / Insufficient]
- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity]
- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing]
- **Stack Alignment**: [Perfect / Good / Partial / None]
## **Strengths:**
## **Issues to address:**
## **Recommended actions:**
**Ready for implementation?** [Yes / No - explain]
**Can skip story-context?** [Yes - tech-spec is comprehensive / No - additional context needed / N/A]
---
_Adapt based on Level 0 vs Level 1. Focus on definitiveness above all else._
_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._

View File

@@ -1,11 +1,58 @@
# {{project_name}} - Epic Breakdown
## Epic Overview
{{epic_overview}}
**Date:** {{date}}
**Project Level:** {{project_level}}
---
## Epic Details
## Epic: {{epic_title}}
{{epic_details}}
**Slug:** {{epic_slug}}
### Goal
{{epic_goal}}
### Scope
{{epic_scope}}
### Success Criteria
{{epic_success_criteria}}
### Dependencies
{{epic_dependencies}}
---
## Story Map
{{story_map}}
---
## Story Summaries
{{story_summaries}}
---
## Implementation Timeline
**Total Story Points:** {{total_points}}
**Estimated Timeline:** {{estimated_timeline}}
---
## Implementation Sequence
{{implementation_sequence}}
---
## Tech-Spec Reference
See [tech-spec.md](../tech-spec.md) for complete technical implementation details.

View File

@@ -10,12 +10,23 @@
<step n="1" goal="Load tech spec and extract the change">
<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
<action>Extract dev_story_location from config (where stories are stored)</action>
<action>Extract the problem statement from "Technical Approach" section</action>
<action>Extract the scope from "Source Tree Structure" section</action>
<action>Extract time estimate from "Implementation Guide" or technical details</action>
<action>Extract acceptance criteria from "Testing Approach" section</action>
<action>Extract from the ENHANCED tech-spec structure:
- Problem statement from "The Change → Problem Statement" section
- Solution overview from "The Change → Proposed Solution" section
- Scope from "The Change → Scope" section
- Source tree from "Implementation Details → Source Tree Changes" section
- Time estimate from "Implementation Guide → Implementation Steps" section
- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
- Framework dependencies from "Development Context → Framework/Libraries" section
- Existing code references from "Development Context → Relevant Existing Code" section
- File paths from "Developer Resources → File Paths Reference" section
- Key code locations from "Developer Resources → Key Code Locations" section
- Testing locations from "Developer Resources → Testing Locations" section
</action>
</step>
@@ -76,9 +87,18 @@
**Dev Notes:**
- Extract technical constraints from tech-spec
- Include file paths from "Source Tree Structure"
- Include file paths from "Developer Resources → File Paths Reference"
- Include existing code references from "Development Context → Relevant Existing Code"
- Reference architecture patterns if applicable
- Cite tech-spec sections for implementation details
- Note dependencies (internal and external)
**NEW: Comprehensive Context**
Since tech-spec is now context-rich, populate all new template fields:
- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points"
- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
</guidelines>
<action>Initialize story file using user_story_template</action>
@@ -94,6 +114,8 @@
<template-output file="{story_path}">test_locations</template-output>
<template-output file="{story_path}">story_points</template-output>
<template-output file="{story_path}">time_estimate</template-output>
<template-output file="{story_path}">dependencies</template-output>
<template-output file="{story_path}">existing_code_references</template-output>
<template-output file="{story_path}">architecture_references</template-output>
</step>
@@ -135,29 +157,40 @@
**Story Location:** `{story_path}`
**Next Steps (choose one path):**
**Next Steps:**
**Option A - Full Context (Recommended for complex changes):**
**🎯 RECOMMENDED - Direct to Development (Level 0):**
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
2. Run story-context workflow
3. Then load DEV agent and run dev-story workflow
Since the tech-spec is now CONTEXT-RICH with:
**Option B - Direct to Dev (For simple, well-understood changes):**
- ✅ Brownfield codebase analysis (if applicable)
- ✅ Framework and library details with exact versions
- ✅ Existing patterns and code references
- ✅ Complete file paths and integration points
**You can skip story-context and go straight to dev!**
1. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
2. Run dev-story workflow (will auto-discover story)
3. Begin implementation
2. Run `dev-story` workflow
3. Begin implementation immediately
**Option B - Generate Additional Context (optional):**
Only needed for extremely complex scenarios:
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
2. Run `story-context` workflow (generates additional XML context)
3. Then load DEV agent and run `dev-story` workflow
**Progress Tracking:**
- All decisions logged in: `bmm-workflow-status.md`
- All decisions logged in: `bmm-workflow-status.yaml`
- Next action clearly identified
<ask>Ready to proceed? Choose your path:
1. Generate story context (Option A - recommended)
2. Go directly to dev-story implementation (Option B - faster)
1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
2. Generate additional story context (for complex edge cases)
3. Exit for now
Select option (1-3):</ask>

View File

@@ -11,12 +11,23 @@
<step n="1" goal="Load tech spec and extract implementation tasks">
<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
<action>Extract dev_story_location from config (where stories are stored)</action>
<action>Identify all implementation tasks from the "Implementation Guide" section</action>
<action>Identify the overall feature goal from "Technical Approach" section</action>
<action>Extract time estimates for each implementation phase</action>
<action>Identify any dependencies between implementation tasks</action>
<action>Extract from the ENHANCED tech-spec structure:
- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
- Implementation tasks from "Implementation Guide → Implementation Steps"
- Time estimates from "Implementation Guide → Implementation Steps"
- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
- Source tree from "Implementation Details → Source Tree Changes"
- Framework dependencies from "Development Context → Framework/Libraries"
- Existing code references from "Development Context → Relevant Existing Code"
- File paths from "Developer Resources → File Paths Reference"
- Key code locations from "Developer Resources → Key Code Locations"
- Testing locations from "Developer Resources → Testing Locations"
- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
</action>
</step>
@@ -60,6 +71,9 @@
<action>Initialize epics.md summary document using epics_template</action>
<action>Also capture project_level for the epic template</action>
<template-output file="{output_folder}/epics.md">project_level</template-output>
<template-output file="{output_folder}/epics.md">epic_title</template-output>
<template-output file="{output_folder}/epics.md">epic_slug</template-output>
<template-output file="{output_folder}/epics.md">epic_goal</template-output>
@@ -113,6 +127,25 @@
- Include technical acceptance criteria from tech spec tasks
- Link back to tech spec sections for implementation details
**CRITICAL: Acceptance Criteria Must Be:**
1. **Numbered** - AC #1, AC #2, AC #3, etc.
2. **Specific** - No vague statements like "works well" or "is fast"
3. **Testable** - Can be verified objectively
4. **Complete** - Covers all success conditions
5. **Independent** - Each AC tests one thing
6. **Format**: Use Given/When/Then when applicable
**Good AC Examples:**
✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds
✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message
✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage
**Bad AC Examples:**
❌ "User can create account" (too vague)
❌ "System performs well" (not measurable)
❌ "Works correctly" (not specific)
**Story Point Estimation:**
- 1 point = < 1 day (2-4 hours)
@@ -134,7 +167,14 @@
- Acceptance Criteria: Numbered list from tech spec
- Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
- Dev Notes: Technical summary, project structure notes, references
- Dev Agent Record: Empty sections for context workflow to populate
- Dev Agent Record: Empty sections (tech-spec provides context)
**NEW: Comprehensive Context Fields**
Since tech-spec is context-rich, populate ALL template fields:
- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
</guidelines>
<for-each story="1 to story_count">
@@ -149,10 +189,12 @@
- acceptance_criteria: Specific, measurable criteria from tech spec
- tasks_subtasks: Implementation tasks with AC references
- technical_summary: High-level approach, key decisions
- files_to_modify: List of files that will change
- test_locations: Where tests will be added
- files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
- test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
- story_points: Estimated effort (1/2/3/5)
- time_estimate: Days/hours estimate
- dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
- existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
- architecture_references: Links to tech-spec.md sections
</template-output>
</for-each>
@@ -161,12 +203,35 @@
</step>
<step n="5" goal="Create story map and implementation sequence">
<step n="5" goal="Create story map and implementation sequence with dependency validation">
<action>Generate visual story map showing epic → stories hierarchy</action>
<critical>Stories MUST be ordered so earlier stories don't depend on later ones</critical>
<critical>Each story must have CLEAR, TESTABLE acceptance criteria</critical>
<action>Analyze dependencies between stories:
**Dependency Rules:**
1. Infrastructure/setup → Feature implementation → Testing/polish
2. Database changes → API changes → UI changes
3. Backend services → Frontend components
4. Core functionality → Enhancement features
5. No story can depend on a later story!
**Validate Story Sequence:**
For each story N, check:
- Does it require anything from Story N+1, N+2, etc.? ❌ INVALID
- Does it only use things from Story 1...N-1? ✅ VALID
- Can it be implemented independently or using only prior stories? ✅ VALID
If invalid dependencies found, REORDER stories!
</action>
<action>Generate visual story map showing epic → stories hierarchy with dependencies</action>
<action>Calculate total story points across all stories</action>
<action>Estimate timeline based on total points (1-2 points per day typical)</action>
<action>Define implementation sequence considering dependencies</action>
<action>Define implementation sequence with explicit dependency notes</action>
<example>
## Story Map
@@ -174,7 +239,10 @@
```
Epic: Icon Reliability
├── Story 1: Build Icon Infrastructure (3 points)
│ Dependencies: None (foundational work)
└── Story 2: Test and Deploy Icons (2 points)
Dependencies: Story 1 (requires infrastructure)
```
**Total Story Points:** 5
@@ -183,8 +251,15 @@ Epic: Icon Reliability
## Implementation Sequence
1. **Story 1** → Build icon infrastructure (setup, download, configure)
- Dependencies: None
- Deliverable: Icon files downloaded, organized, accessible
2. **Story 2** → Test and deploy (depends on Story 1)
</example>
- Dependencies: Story 1 must be complete
- Deliverable: Icons verified, tested, deployed to production
**Dependency Validation:** ✅ Valid sequence - no forward dependencies
</example>
<template-output file="{output_folder}/epics.md">story_summaries</template-output>
<template-output file="{output_folder}/epics.md">story_map</template-output>
@@ -214,12 +289,90 @@ Epic: Icon Reliability
</step>
<step n="7" goal="Finalize and provide user guidance">
<step n="7" goal="Auto-validate story quality and sequence">
<action>Confirm all stories map to tech spec implementation tasks</action>
<critical>Auto-run validation - NOT optional!</critical>
<action>Running automatic story validation...</action>
<action>**Validate Story Sequence (CRITICAL):**
For each story, check:
1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required!
2. Are dependencies clearly documented? ✅ PASS
3. Can stories be implemented in order 1→2→3? ✅ PASS
If sequence validation FAILS:
- Identify the problem dependencies
- Propose new ordering
- Ask user to confirm reordering
</action>
<action>**Validate Acceptance Criteria Quality:**
For each story's AC, check:
1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required
2. Is it specific and testable? ✅ Required
3. Does it use Given/When/Then or equivalent? ✅ Recommended
4. Are all success conditions covered? ✅ Required
Count vague AC (contains "works", "good", "fast", "well"):
- 0 vague AC: ✅ EXCELLENT
- 1-2 vague AC: ⚠️ WARNING - Should improve
- 3+ vague AC: ❌ FAIL - Must improve
</action>
<action>**Validate Story Completeness:**
1. Do all stories map to tech spec tasks? ✅ Required
2. Do story points align with tech spec estimates? ✅ Recommended
3. Are dependencies clearly noted? ✅ Required
4. Does each story have testable AC? ✅ Required
</action>
<action>Generate validation report</action>
<check if="sequence validation fails OR AC quality fails">
<output>❌ **Story Validation Failed:**
{{issues_found}}
**Recommended Fixes:**
{{recommended_fixes}}
Shall I fix these issues? (yes/no)</output>
<ask>Apply fixes? (yes/no)</ask>
<check if="yes">
<action>Apply fixes (reorder stories, rewrite vague AC, add missing details)</action>
<action>Re-validate</action>
<output>✅ Validation passed after fixes!</output>
</check>
</check>
<check if="validation passes">
<output>✅ **Story Validation Passed!**
**Sequence:** ✅ Valid (no forward dependencies)
**AC Quality:** ✅ All specific and testable
**Completeness:** ✅ All tech spec tasks covered
**Dependencies:** ✅ Clearly documented
Stories are implementation-ready!</output>
</check>
</step>
<step n="8" goal="Finalize and provide user guidance">
<action>Confirm all validation passed</action>
<action>Verify total story points align with tech spec time estimates</action>
<action>Verify stories are properly sequenced with dependencies noted</action>
<action>Confirm all stories have measurable acceptance criteria</action>
<action>Confirm epic and stories are complete</action>
**Level 1 Planning Complete!**
@@ -242,33 +395,53 @@ Epic: Icon Reliability
**Next Steps - Iterative Implementation:**
**🎯 RECOMMENDED - Direct to Development (Level 1):**
Since the tech-spec is now CONTEXT-RICH with:
- ✅ Brownfield codebase analysis (if applicable)
- ✅ Framework and library details with exact versions
- ✅ Existing patterns and code references
- ✅ Complete file paths and integration points
- ✅ Dependencies clearly mapped
**You can skip story-context for most Level 1 stories!**
**1. Start with Story 1:**
a. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
b. Run story-context workflow (select story-{epic_slug}-1.md)
c. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
d. Run dev-story workflow to implement story 1
a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
c. Tech-spec provides all context needed
d. Implement story 1
**2. After Story 1 Complete:**
- Repeat process for story-{epic_slug}-2.md
- Story context will auto-reference completed story 1
- Repeat for story-{epic_slug}-2.md
- Reference completed story 1 in your work
**3. After Story 2 Complete:**
{{#if story_3}}
- Repeat process for story-{epic_slug}-3.md
- Repeat for story-{epic_slug}-3.md
{{/if}}
- Level 1 feature complete!
**Option B - Generate Additional Context (optional):**
Only needed for extremely complex multi-story dependencies:
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
2. Run `story-context` workflow for complex stories
3. Then load DEV agent and run `dev-story`
**Progress Tracking:**
- All decisions logged in: `bmm-workflow-status.md`
- All decisions logged in: `bmm-workflow-status.yaml`
- Next action clearly identified
<ask>Ready to proceed? Choose your path:
1. Generate context for story 1 (recommended - run story-context)
2. Go directly to dev-story for story 1 (faster)
1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
2. Generate additional story context first (for complex dependencies)
3. Exit for now
Select option (1-3):</ask>

View File

@@ -3,21 +3,97 @@
**Author:** {{user_name}}
**Date:** {{date}}
**Project Level:** {{project_level}}
**Project Type:** {{project_type}}
**Change Type:** {{change_type}}
**Development Context:** {{development_context}}
---
## Source Tree Structure
## Context
{{source_tree}}
### Available Documents
{{loaded_documents_summary}}
### Project Stack
{{project_stack_summary}}
### Existing Codebase Structure
{{existing_structure_summary}}
---
## Technical Approach
## The Change
### Problem Statement
{{problem_statement}}
### Proposed Solution
{{solution_overview}}
### Scope
**In Scope:**
{{scope_in}}
**Out of Scope:**
{{scope_out}}
---
## Implementation Details
### Source Tree Changes
{{source_tree_changes}}
### Technical Approach
{{technical_approach}}
### Existing Patterns to Follow
{{existing_patterns}}
### Integration Points
{{integration_points}}
---
## Development Context
### Relevant Existing Code
{{existing_code_references}}
### Dependencies
**Framework/Libraries:**
{{framework_dependencies}}
**Internal Modules:**
{{internal_dependencies}}
### Configuration Changes
{{configuration_changes}}
### Existing Conventions (Brownfield)
{{existing_conventions}}
### Test Framework & Standards
{{test_framework_info}}
---
## Implementation Stack
@@ -40,7 +116,47 @@
## Implementation Guide
{{implementation_guide}}
### Setup Steps
{{setup_steps}}
### Implementation Steps
{{implementation_steps}}
### Testing Strategy
{{testing_strategy}}
### Acceptance Criteria
{{acceptance_criteria}}
---
## Developer Resources
### File Paths Reference
{{file_paths_complete}}
### Key Code Locations
{{key_code_locations}}
### Testing Locations
{{testing_locations}}
### Documentation to Update
{{documentation_updates}}
---
## UX/UI Considerations
{{ux_ui_considerations}}
---
@@ -52,4 +168,14 @@
## Deployment Strategy
{{deployment_strategy}}
### Deployment Steps
{{deployment_steps}}
### Rollback Plan
{{rollback_plan}}
### Monitoring
{{monitoring_approach}}

View File

@@ -22,22 +22,43 @@ so that {{benefit}}.
{{technical_summary}}
### Tech-Spec Reference
**Full details:** See [tech-spec.md](../tech-spec.md)
The tech-spec contains comprehensive context including:
- Brownfield codebase analysis (if applicable)
- Framework and library details with versions
- Existing patterns to follow
- Integration points and dependencies
- Complete implementation guidance
### Project Structure Notes
- Files to modify: {{files_to_modify}}
- Expected test locations: {{test_locations}}
- Estimated effort: {{story_points}} story points ({{time_estimate}})
- **Files to modify:** {{files_to_modify}}
- **Expected test locations:** {{test_locations}}
- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
- **Dependencies:** {{dependencies}}
### Key Code References
{{existing_code_references}}
### References
- **Tech Spec:** See tech-spec.md for detailed implementation
- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document
- **Architecture:** {{architecture_references}}
---
## Dev Agent Record
### Context Reference
<!-- Path(s) to story context XML will be added here by context workflow -->
**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance
<!-- Additional context XML paths will be added here if story-context workflow is run -->
### Agent Model Used
@@ -54,3 +75,13 @@ so that {{benefit}}.
### File List
<!-- Will be populated during dev-story execution -->
### Test Results
<!-- Will be populated during dev-story execution -->
---
## Review Notes
<!-- Will be populated during code review -->

View File

@@ -13,6 +13,13 @@ document_output_language: "{config_source}:document_output_language"
user_skill_level: "{config_source}:user_skill_level"
date: system-generated
# Runtime variables (captured during workflow execution)
project_level: runtime-captured
project_type: runtime-captured
development_context: runtime-captured
change_type: runtime-captured
field_type: runtime-captured
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec"
instructions: "{installed_path}/instructions.md"

View File

@@ -52,6 +52,9 @@ input_file_patterns:
whole: "{output_folder}/*prd*.md"
sharded: "{output_folder}/*prd*/index.md"
tech_spec:
whole: "{output_folder}/tech-spec.md"
architecture:
whole: "{output_folder}/*architecture*.md"
sharded: "{output_folder}/*architecture*/index.md"

View File

@@ -120,7 +120,8 @@ All stories are either still in backlog or already marked ready/in-progress/done
<step n="2" goal="Collect relevant documentation">
<action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
<action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
<action>Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
<action>Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
<action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
<template-output file="{default_output_file}">
Add artifacts.docs entries with {path, title, section, snippet}:

View File

@@ -31,6 +31,9 @@ input_file_patterns:
whole: "{output_folder}/*prd*.md"
sharded: "{output_folder}/*prd*/index.md"
tech_spec:
whole: "{output_folder}/tech-spec.md"
architecture:
whole: "{output_folder}/*architecture*.md"
sharded: "{output_folder}/*architecture*/index.md"