69bf2bae1d
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> |
||
|---|---|---|
| .. | ||
| agents | ||
| tasks | ||
| workflows | ||
| config.yaml | ||