feat(bmvcs): Add BMVCS module for VCS workflow adaptation #670
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Create BMVCS module directory structure - Add installer configuration (install-menu-config.yaml) - Add VCS Adapter agent with command structure - Add module README with overview and usage - Foundation for VCS-agnostic workflow adaptation Part 1/5 of BMVCS migration (bmad-code-org#661) Supersedes legacy PRs bmad-code-org#582, bmad-code-org#583, bmad-code-org#584
- Port discover-vcs.md from PR bmad-code-org#582 (187 lines) - Port create-vcs-adapted-doc.md from PR bmad-code-org#583 (165 lines) - Add validate-vcs-config.md task (73 lines new) - Add installer.js for module setup (26 lines) Part 2/5 of BMVCS migration (bmad-code-org#661) - Tasks Complete Note: VCS templates to be added in next commit after proper extraction Next: Manually create 5 VCS templates with valid YAML
Add 5 VCS adaptation templates for different workflows: - git-github-flow.yaml: Simple feature branches (40% of users) - git-gitflow.yaml: Structured releases (20% of users) - git-trunk-based.yaml: Continuous deployment (15% of users) - no-vcs.yaml: Prototypes and one-time scripts (5% of users) - custom-generic.yaml: Custom/legacy VCS systems (10% of users) Templates support VCS-agnostic artifact generation across all BMAD agents. Part 2/5 of BMVCS migration (bmad-code-org#661) Completes core VCS discovery functionality 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Add comprehensive documentation for VCS-agnostic approach: - VCS_AGNOSTIC_PRINCIPLES.md: Core philosophy and 10 principles - VCS_AGNOSTIC_PROPOSAL.md: Implementation approach and examples - VCS_DETECTION_CONFIDENCE.md: Auto-detection confidence scoring - docs/README.md: Documentation overview and quick start Documentation explains how BMAD adapts to any VCS (Git, SVN, Perforce, or no VCS) with appropriate terminology and workflow patterns. Part 3/5 of BMVCS migration (bmad-code-org#661) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Add practical examples demonstrating VCS-agnostic adaptation: - vcs-adaptation-examples.md: 6 real-world scenarios (GitHub Flow, GitFlow, No VCS, SVN, Trunk-Based, Multi-VCS) - vcs-detection-implementation.py: Reference implementation of Git workflow auto-detection with confidence scoring - examples/README.md: Guide to using examples and integration Examples demonstrate "Detection as a HINT, not a DECISION" principle with evidence-based suggestions and user confirmation. Part 4/5 of BMVCS migration (bmad-code-org#661) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Add VCS setup workflow and integrate with BMM agents: BMVCS Workflows: - workflows/setup-vcs/instructions.md: Comprehensive VCS discovery guide with auto-detection, clarifying questions, and edge case handling - workflows/setup-vcs/checklist.md: Pre/during/post setup validation - workflows/setup-vcs/workflow.yaml: Machine-readable workflow definition BMM Agent Integration: - architect.md: Added VCS-aware architecture documentation adaptation - pm.md: Added VCS-aware requirements and release planning - dev.md: Added VCS-aware code delivery and commit practices Agents now check bmad-core/vcs-config.yaml and adapt their output to the configured workflow (GitHub Flow, GitFlow, Trunk-Based, No VCS, etc.) without imposing new processes on teams. Part 5/5 of BMVCS migration (bmad-code-org#661) Completes VCS-agnostic module integration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add comprehensive DEVELOPMENT_APPROACH.md document - Document direct development vs BMB create-module comparison - Include compliance matrix with BMAD v6 standards - Add recommendations for future module development - Fix markdown formatting and URL links in README - Add new doc to Documentation section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add blank line before list in Error Handling section - Improve markdown compliance 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add comprehensive testing checklist for VCS Discovery Flow - Document installer testing requirements - Define success metrics (MVP, Target, Stretch) - Add integration testing with BMM module - Include documentation validation tasks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
NEXT_SESSION.md is useful for testing but should not be in the development branch. Can be recreated in a separate testing branch if needed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
…docs
RESEARCH FINDINGS:
- KB Mode exists in BMAD v6 (interactive agent guide from v4)
- Command: *kb-mode provides guided exploration
- 8 topic areas including "Agents" discovery
- Can be extended with BMVCS awareness
KEY DISCOVERY:
- Don't create new agent discovery mechanism
- Extend existing KB Mode with VCS-aware agent info
- Add to .bmad-core/data/bmad-kb.md
- Leverage official pattern for user guidance
PATH FIX PLAN:
- Issue: BMM agents look for bmad-core/vcs-config.yaml
- Should be: .bmad/vcs-config.yaml
- Affects: 3 agents (Architect, PM, Dev)
- Ready for execution in Session 4
FILES ADDED:
src/modules/bmvcs/docs/
├── KB_MODE_RESEARCH_FINDINGS.md (10k)
│ - Full KB Mode analysis
│ - Integration opportunities
│ - Phase 3 strategy
├── BMM_AGENTS_VCS_CONFIG_PATH_FIX.md (12k)
│ - 5-phase execution plan
│ - 15-25 min estimated time
│ - Fixes 3 agent files
└── TODO.md
- Phase 3 tasks (Documentation & Quality)
- Path fix checklist
- Future enhancements
- Documentation standards tasks
IMPLICATIONS:
- Phase 3.1 can start NOW (planning, no path fix needed)
- Path fix required before implementation/testing (Session 4)
- All BMVCS documentation now in module docs/
NEXT STEPS:
1. Design BMVCS KB Mode additions (Session 3 continues)
2. Execute path fix (Session 4)
3. Implement Phase 3.1 documentation (Session 5+)
Context: Alpha testing complete, Phase 3 planning started
Research validates "fail to plan - plan to fail" principle
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
ISSUE: Path Inconsistency BMM agents were looking for VCS config at wrong path: - Old: bmad-core/vcs-config.yaml (incorrect) - New: .bmad/vcs-config.yaml (correct per BMVCS spec) IMPACT: VCS integration failed without manual workaround FIX: Updated 3 agent files to use correct path: - src/modules/bmm/agents/architect.md (line 17) - src/modules/bmm/agents/pm.md (line 17) - src/modules/bmm/agents/dev.md (line 22) TESTING: Discovered during BMVCS Alpha Phase 2 testing - Workaround documented, now properly fixed in source - Test results: ~/test-bmvcs-install/testing/ AFFECTED AGENTS: ✅ Architect - VCS-aware documentation generation ✅ PM - VCS-aware requirements planning ✅ Dev - VCS-aware implementation guidance This fix enables seamless VCS integration without manual intervention. Related: bmad-code-org#661 Testing: Alpha Phase 2 complete (2025-10-01)
Brings feat/bmvcs-dev up to date with latest v6-alpha: - TEA agent workflows (bmad-code-org#660) - SubAgents organization in subfolders - Installer improvements (hash checking, v4→v6 upgrade) - v6 flow documentation - BMM Flow document No conflicts expected - path fix already applied. BMVCS module files untouched by upstream changes. Related: bmad-code-org#661
Remove link to DEVELOPMENT_APPROACH.md which is internal development documentation not needed in production release. Prepares module for clean PR submission.
Remove internal development documentation from git: - TODO.md - BMM_AGENTS_VCS_CONFIG_PATH_FIX.md - DEVELOPMENT_APPROACH.md - KB_MODE_RESEARCH_FINDINGS.md These files remain locally and will be stashed for future KB Mode work. Not needed in production release.
30 tasks
Contributor
Author
Update: Architecture Refinement ReadyDuring local testing, discovered an architectural improvement opportunity: Current state (in PR):
Proposed refinement:
Changes ready locally, waiting for your review feedback before pushing updates. Happy to discuss the architectural approach if you have questions! |
Collaborator
|
Do not see a need at this time for officially supporting any version control beyond github |
joyshmitz
added a commit
to felectra/BMAD-METHOD
that referenced
this pull request
Nov 4, 2025
Add BMVCS module KB content to be injected into bmad-kb.md during installation. WHAT: - Created src/modules/bmvcs/_module-installer/assets/bmvcs-kb.md (91 lines, 3.9k) - Follows "Optional Modules" pattern (compact, What/When/How/Integration) - Designed for insertion after "Core Architecture" section WHY: - KB Mode needs BMVCS awareness for user discovery - Users need to understand when BMVCS is useful vs unnecessary - Installer copies module KB files to .bmad-core/data/ at install time - Completes BMVCS module documentation suite HOW: - Structure: What/When/Quick Start/Agents/VCS Systems/Adaptations/Links - ~90 lines (compact like Expansion Packs section) - Tables for agents and VCS support matrix - Clear "When to Use" vs "Skip BMVCS" guidance - Links to detailed module documentation CONTENT SECTIONS: 1. What is BMVCS? - Philosophy and approach 2. When to Use - Use cases and anti-patterns 3. Quick Start - 3-step installation/discovery/adaptation 4. VCS-Aware Agents - Integration table 5. Supported VCS Systems - Comprehensive matrix 6. Workflow Adaptations - Terminology/artifacts/templates 7. Learn More - Links to detailed docs INTEGRATION: - File will be read by installer during BMVCS module install - Content injected into .bmad-core/data/bmad-kb.md (ignored by git) - Follows same pattern as src/modules/bmm/_module-installer/assets/bmm-kb.md Related: PR bmad-code-org#670 (BMVCS module complete) Context: Alpha Phase 3 - Documentation & Quality Session: 2025-10-02 BMVCS KB Mode integration work 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
Adds BMVCS (BMAD Version Control Suite) module for v6, enabling BMAD to adapt to any version control system instead of assuming Git.
Why
Addresses #661. BMAD needs to respect diverse team workflows - from GitHub Flow to SVN, Perforce, or no VCS. Current architecture assumes Git, limiting adoption. BMVCS makes BMAD truly universal.
Consolidates legacy PRs #582, #583, #584 from v4 architecture into v6 modular structure.
How
Testing
Size Justification
PR exceeds 800-line guideline (~3,500 lines) but represents cohesive v6 module following bmm/bmb/cis pattern. All components tested together. Splitting would leave module incomplete. Can split if maintainers prefer.