Implements user-requested semaphore/worker pool pattern for maximum parallelization efficiency.
OLD Pattern (Inefficient):
- Split stories into batches of N
- Spawn N agents for batch 1
- Wait for ALL N to finish (idle time if some finish early)
- Spawn N agents for batch 2
- Wait for ALL N to finish
- Repeat until done
NEW Semaphore Pattern (Efficient):
- Initialize pool with N worker slots
- Fill all N slots with first N stories
- Poll workers continuously (non-blocking)
- As soon as ANY worker completes → immediately refill that slot
- Maintain constant N concurrent agents until queue empty
- Zero idle time, maximum throughput
Benefits:
- 20-40% faster completion (eliminates batch synchronization delays)
- Constant utilization of all worker slots
- More predictable completion times
- Better resource efficiency
Implementation Details:
- run_in_background: true for Task agents (non-blocking spawns)
- TaskOutput(block=false) for polling without waiting
- Worker pool state tracking (active_workers map)
- Immediate slot refill on completion
- Live progress dashboard every 30 seconds
- Graceful handling of failures (continue_on_failure support)
Files Modified:
- batch-super-dev/instructions.md: Rewrote Step 4-Parallel with semaphore logic
- batch-super-dev/README.md: Updated to v1.3.0, documented semaphore pattern
- docs/HOW-TO-VALIDATE-SPRINT-STATUS.md: Explained semaphore vs batch patterns
- src/modules/cis/module.yaml: Auto-formatted by prettier
User Experience:
- Same concurrency selection (2, 4, or all stories)
- Same sequential vs parallel choice
- Now with continuous worker pool instead of batch synchronization
- Real-time visibility: "Worker 3 completed → immediately refilled"
Implements requirements #1 and #2: stronger enforcement + progress tracking
REQUIREMENT #1: Stronger Enforcement
- dev-story Step 8 now MANDATES sprint-status.yaml update after EVERY task
- Previously: Updated only at story start (step 4) and end (step 9)
- Now: Updated after EACH task completion with CRITICAL + HALT enforcement
- Validation: Re-reads file to verify update persisted, HALTs on failure
REQUIREMENT #2: Progress Tracking
- Extended sprint-status.yaml format with inline progress comments
- Format: "story-key: in-progress # X/Y tasks (Z%)"
- Real-time visibility into story progress without opening story files
- Automatically updated by dev-story and batch-super-dev reconciliation
Progress Comment Format:
- in-progress: "# 3/10 tasks (30%)"
- review: "# 10/10 tasks (100%) - awaiting review"
- done: "# ✅ COMPLETED: Brief summary"
Benefits:
- Sprint-status.yaml becomes a real-time progress dashboard
- No need to open individual story files to check progress
- Immediate visibility when stories stall (same % for days)
- Enables better sprint planning and resource allocation
Files Modified:
- dev-story/instructions.xml (BMM + BMGD): Added mandatory task-level updates
- sprint-status/instructions.md (BMM + BMGD): Added progress parsing/display
- batch-super-dev/step-4.5-reconcile-story-status.md: Added progress to reconciliation
- docs/HOW-TO-VALIDATE-SPRINT-STATUS.md: Documented new format and enforcement
Breaking Change: None (backward compatible with old format)
- Old entries without progress comments still work
- New entries automatically add progress
- Gradual migration as stories are worked
- Remove autonomous-epic workflow from BMM and BMGD modules
- Remove agent menu entries for autonomous-epic
- Update workflow references to use batch-super-dev
- Add README-changes.md documenting fork customizations
- Remove outdated SPRINT-STATUS-SYNC-GUIDE.md
batch-super-dev is the superior approach with proactive story
validation, auto-creation of missing stories, and smart reconciliation.
* feat(docs): add Diataxis folder structure and update sidebar styling
- Create tutorials, how-to, explanation, reference directories with subdirectories
- Add index.md files for each main Diataxis section
- Update homepage with Diataxis card navigation layout
- Implement clean React Native-inspired sidebar styling
- Convert sidebar to autogenerated for both Diataxis and legacy sections
- Update docusaurus config with dark mode default and navbar changes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(docs): migrate Phase 1 files to Diataxis structure
Move 21 files to new locations:
- Tutorials: quick-start guides, agent creation guide
- How-To: installation, customization, workflows
- Explanation: core concepts, features, game-dev, builder
- Reference: merged glossary from BMM and BMGD
Also:
- Copy images to new locations
- Update internal links via migration script (73 links updated)
- Build verified successfully
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): add category labels for sidebar folders
Add _category_.json files to control display labels and position
for autogenerated sidebar categories.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* style(docs): improve welcome page and visual styling
- Rewrite index.md with React Native-inspired welcoming layout
- Add Diataxis section cards with descriptions
- Remove sidebar separator, add spacing instead
- Increase navbar padding with responsive breakpoints
- Add rounded admonitions without left border bar
- Use system font stack for better readability
- Add lighter chevron styling in sidebar
- Constrain max-width to 1600px for wide viewports
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use baseUrl in meta tag paths for correct deployment URLs
* feat(docs): complete Phase 2 - split files and fix broken links
Phase 2 of Diataxis migration:
- Split 16 large legacy files into 42+ focused documents
- Created FAQ section with 7 topic-specific files
- Created brownfield how-to guides (3 files)
- Created workflow how-to guides (15+ files)
- Created architecture explanation files (3 files)
- Created TEA/testing explanation files
- Moved remaining legacy module files to proper Diataxis locations
Link fixes:
- Fixed ~50 broken internal links across documentation
- Updated relative paths for new file locations
- Created missing index files for installation, advanced tutorials
- Simplified TOC anchors to fix Docusaurus warnings
Cleanup:
- Removed legacy sidebar entries for deleted folders
- Deleted duplicate and empty placeholder files
- Moved workflow diagram assets to tutorials/images
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(build): use file glob instead of sidebar parsing for llms-full.txt
Replace brittle sidebar.js regex parsing with recursive file glob.
The old approach captured non-file strings like 'autogenerated' and
category labels, resulting in only 5 files being processed.
Now correctly processes all 86+ markdown files (~95k tokens).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(seo): use absolute URLs in AI meta tags for agent discoverability
AI web-browsing agents couldn't follow relative paths in meta tags due to
URL security restrictions. Changed llms-full.txt and llms.txt meta tag
URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor(docs): recategorize misplaced files per Diataxis analysis
Phase 2.5 categorization fixes based on post-migration analysis:
Moved to correct Diataxis categories:
- tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md)
- tutorials/brownfield-onboarding.md → how-to/brownfield/index.md
- reference/faq/* (8 files) → explanation/faq/
- reference/agents/barry-quick-flow.md → explanation/agents/
- reference/agents/bmgd-agents.md → explanation/game-dev/agents.md
Created:
- explanation/agents/index.md
Fixed all broken internal links (14 total)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(docs): add Getting Started tutorial and simplify build script
- Add comprehensive Getting Started tutorial with installation as Step 1
- Simplify build-docs.js to read directly from docs/ (no consolidation)
- Remove backup/restore dance that could corrupt docs folder on build failure
- Remove ~150 lines of unused consolidation code
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(css): use fixed width layout to prevent content shifting
Apply React Native docs approach: set both width and max-width at
largest breakpoint (1400px) so content area maintains consistent
size regardless of content length. Switches to fluid 100% below
1416px breakpoint.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor(docs): restructure tutorials with renamed entry point
- Rename index.md to bmad-tutorial.md for clearer navigation
- Remove redundant tutorials/index.md
- Update sidebar and config references
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(docs): add tutorial style guide and AI agent announcement bar
- Add docs/_contributing/ with tutorial style guide
- Reformat quick-start-bmm.md and bmad-tutorial.md per style guide
- Remove horizontal separators, add strategic admonitions
- Add persistent announcement bar for AI agents directing to llms-full.txt
- Fix footer broken link to tutorials
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(docs): add markdown demo page and UI refinements
- Add comprehensive markdown-demo.md for style testing
- Remove doc category links from navbar (use sidebar instead)
- Remove card buttons from welcome page
- Add dark mode styling for announcement bar
- Clean up index.md card layout
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(docs): apply unified tutorial style and update references
- Reformat create-custom-agent.md to follow tutorial style guide
- Update tutorial-style.md with complete unified structure
- Update all internal references to renamed tutorial files
- Remove obsolete advanced/index.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor(docs): migrate from Docusaurus to Astro+Starlight
Replace Docusaurus with Astro and the Starlight documentation theme
for improved performance, better customization, and modern tooling.
Build pipeline changes:
- New build-docs.js orchestrates link checking, artifact generation,
and Astro build in sequence
- Add check-doc-links.js for validating internal links and anchors
- Generate llms.txt and llms-full.txt for LLM-friendly documentation
- Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip)
- Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build
- Output directly to build/site for cleaner deployment
Website architecture:
- Add rehype-markdown-links.js plugin to transform .md links to routes
- Add site-url.js helper for GitHub Pages URL resolution with strict
validation (throws on invalid GITHUB_REPOSITORY format)
- Custom Astro components: Banner, Header, MobileMenuFooter
- Symlink docs/ into website/src/content/docs for Starlight
Documentation cleanup:
- Remove Docusaurus _category_.json files (Starlight uses frontmatter)
- Convert all docs to use YAML frontmatter with title field
- Move downloads.md from website/src/pages to docs/
- Consolidate style guide and workflow diagram docs
- Add 404.md and tutorials/index.md
---------
Co-authored-by: forcetrainer <bryan@inagaki.us>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): align sidebar with actual docs structure and fix image path
Sidebar referenced non-existent paths (modules/bmm/, getting-started/, etc.)
while actual docs live in different locations (modules/bmm-bmad-method/,
bmad-core-concepts/, etc.). Updated sidebar to match reality so Docusaurus
can build successfully.
Also fixed broken image reference in workflows-guide.md that used an
incorrect relative path.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): update build script to include docs/modules directory
The build script was excluding the modules folder when copying from docs/,
but module docs now live in docs/modules/ instead of src/modules/*/docs/.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): correct broken internal links
Fixed relative paths that were pointing to non-existent locations:
- bmgd index: ../../bmm/docs/index.md → ../bmm/index.md
- cis index: ../../bmm/docs/index.md → ../bmm/index.md
- bmm faq: ./README.md → GitHub URL
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* docs: chose your tea engagement
* docs: addressed PR comments
* docs: made refiements to the mermaid diagram
* docs: wired in test architect discoverability nudges
---------
Co-authored-by: Brian <bmadcode@gmail.com>
Integrates the bmad-guide skill into BMAD installation process to help
Claude stay on track with BMAD methodology.
Features:
- Phase navigation and workflow selection guidance
- Project level detection (0-4) for routing to correct workflows
- Common mistakes prevention (skipping phases, manual coding)
- Emergency recovery procedures when off track
- Quick reference tables and troubleshooting
Implementation:
- Created resources/skills/ directory with bmad-guide.md (428 lines)
- Added installBmadGuideSkill() to ClaudeCodeSetup class
- Skill auto-installs to ~/.claude/skills/ during setup
- Available globally across all BMAD projects
- Updated installation documentation
Usage:
- Automatic: Skill is installed when running npx bmad-method install
- Manual access: /bmad-guide command in any project
- Optional: Add BMAD Method config to ~/.claude/CLAUDE.md for automatic invocation
Benefits:
- Prevents Claude from jumping straight to coding without workflows
- Ensures proper phase progression
- Guides workflow selection based on project level
- Self-corrects when going off track
- New /autonomous-epic command processes entire epic
- Just-in-time planning: creates each story before developing
- Auto-develops using super-dev-story or dev-story
- Progress tracking with resume capability
- Git commits after each story completion
- Error handling with retry logic and continue-on-failure
- Epic completion report with statistics
- Estimated: 100K-150K tokens per story
Use cases:
- Overnight epic completion
- CI/CD integration
- Batch sprint processing
Applies to both BMM and BMGD modules
- Complete gap analysis feature documentation
- Migration guide for existing users
- Usage examples for all planning styles
- Troubleshooting and FAQ sections
* feat: add documentation website with Docusaurus build pipeline
* feat(docs): add AI discovery meta tags for llms.txt files
- Add global headTags with ai-terms, llms, llms-full meta tags
- Update landing page link to clarify AI context purpose
* fix(docs): restore accidentally deleted faq.md and glossary.md
Files were removed in 12dd97fe during path restructuring.
* fix(docs): update broken project-readme links to GitHub URL
* feat(schema): add compound trigger format validation
Major Changes:
- Add sample custom agents demonstrating installable agent system
- commit-poet: Generates semantic commit messages (BMAD Method repo sample)
- toolsmith: Development tooling expert with knowledge base covering bundlers, deployment, docs, installers, modules, and tests (BMAD Method repo sample)
- Both agents demonstrate custom agent architecture and are installable to projects via BMAD installer system
- Include comprehensive installation guides and sidecar knowledge bases
- Add bmad-quick-flow methodology for rapid development
- create-tech-spec: Direct technical specification workflow
- quick-dev: Flexible execution workflow supporting both tech-spec-driven and direct instruction development
- quick-flow-solo-dev (Barry): 1 man show agent specialized in bmad-quick-flow methodology
- Comprehensive documentation for quick-flow approach and solo development
- Remove deprecated tech-spec workflow track
- Delete entire tech-spec workflow directory and templates
- Remove quick-spec-flow.md documentation (replaced by quick-flow docs)
- Clean up unused epic and story templates
- Fix custom agent installation across IDE installers
- Repair antigravity and multiple IDE installers to properly support custom agents
- Enable custom agent installation via quick installer, agent installer, regular installer, and special agent installer
- All installation methods now accessible via npx with full documentation
Infrastructure:
- Update BMM module configurations and team setups
- Modify workflow status paths to support quick-flow integration
- Reorganize documentation with new agent and workflow guides
- Add custom/ directory for user customizations
- Update platform codes and installer configurations
Jonah Schulte
Alex Verkhovsky
Brian Madison
forcetrainer
Murat K Ozcan
Jonah Schulte
Wendy Smoak
mreis-atlassian