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.
* fix: add CommonMark-compliant markdown formatting rules to workflow
Problem:
--------
BMAD generates markdown that violates CommonMark specification by omitting
required blank lines around lists, tables, and code blocks. While GitHub's
renderer (GFM) handles this gracefully, strict parsers like Mac Markdown.app
break completely, rendering lists as plain text and losing document structure.
Solution:
---------
Add 6 mandatory markdown formatting rules to workflow.xml (line 73) that
enforce proper spacing and consistency:
1. ALWAYS add blank line before and after bullet lists
2. ALWAYS add blank line before and after numbered lists
3. ALWAYS add blank line before and after tables
4. ALWAYS add blank line before and after code blocks
5. Use - for bullets consistently (not * or +)
6. Use language identifier for code fences
Impact:
-------
- Makes BMAD output CommonMark compliant
- Ensures compatibility with ALL markdown parsers, not just GitHub
- Follows industry best practices for professional documentation
- Future-proofs against stricter parser implementations
- Zero content changes - only formatting improved
Testing:
--------
Comprehensive three-phase testing completed:
- Phase 1: Synthetic test validating fix mechanism
- Phase 2: Fresh install end-to-end test (API Gateway project)
- Phase 3: GitHub validation with visual proof
Results: 1,112 lines of formatting improvements, 0 content changes,
100% CommonMark compliance achieved.
Test Evidence:
--------------
Complete test repository with before/after comparison, Mac Markdown.app
screenshot proving the issue, and comprehensive documentation:
https://github.com/jheyworth/bmad-markdown-formatting-test
See TEST.md for full documentation, test methodology, and evidence.
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Remove TEST.md per maintainer feedback
As requested by @bmadcode - the test documentation was useful during review but is not needed in the repository. Testing evidence remains documented in the PR description and external test repository.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
When preserving CSV rows from existing manifest files during module updates,
rows from older schema versions (without the 'standalone' column) were being
added to CSVs with new schema headers, causing "Invalid Record Length" errors
during parsing.
Added schema upgrade logic to detect old column structure and upgrade preserved
rows by adding missing columns with appropriate default values. This ensures all
CSV rows match the header column count, fixing installation errors.
Fixes column count mismatch in:
- workflow-manifest.csv (added standalone column)
- task-manifest.csv (added standalone column)
- tool-manifest.csv (added standalone column)
- agent-manifest.csv (schema validation for future-proofing)
Brian Madison
jheyworth