feat(bmvcs): add module foundation structure
- 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 (#661) Supersedes legacy PRs #582, #583, #584
This commit is contained in:
Serhii
parent
30fb0e67e1
commit
9571a2f332
|
|
@ -0,0 +1,219 @@
|
|||
# BMVCS: BMad Version Control Suite
|
||||
|
||||
**Status:** 🚧 In Development (v6-alpha)
|
||||
|
||||
> Make BMAD adapt to your version control workflow, not the other way around.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What is BMVCS?
|
||||
|
||||
**BMVCS** (BMad Version Control Suite) is an optional module that makes BMAD truly universal by adapting to any version control system. Instead of assuming Git or forcing workflow changes, BMVCS discovers your existing practices and adjusts BMAD's output accordingly.
|
||||
|
||||
### Core Philosophy
|
||||
|
||||
**"Optimize for the majority, open to all"**
|
||||
|
||||
- ~85-90% of teams use Git → Quick picks for common Git workflows
|
||||
- ~10-15% use other VCS or no VCS → Fully supported, never forced to change
|
||||
- **Respect existing workflows** - Enhance, don't replace
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
### 🔍 VCS Discovery
|
||||
|
||||
Interactive detection of your version control system:
|
||||
|
||||
- **Git workflows:** GitHub Flow, GitFlow, Trunk-Based Development
|
||||
- **Other VCS:** SVN, Perforce, Mercurial, TFS
|
||||
- **No VCS:** Self-contained deliverables with date versioning
|
||||
- **Custom:** Team-specific workflows
|
||||
|
||||
### 📝 Workflow Adaptation
|
||||
|
||||
Automatically adapts BMAD output to your workflow:
|
||||
|
||||
- **Terminology:** Git users get "commit/branch", SVN users get "revision/trunk"
|
||||
- **Artifact size:** GitHub Flow = small PRs, No VCS = monolithic packages
|
||||
- **Documentation:** Branch strategy, CI/CD considerations, commit conventions
|
||||
|
||||
### 🔧 VCS Adapter Agent
|
||||
|
||||
Specialized agent for version control integration:
|
||||
|
||||
- Commands: `*discover`, `*adapt-doc`, `*show-config`, `*validate`
|
||||
- Works standalone or integrates with BMM agents
|
||||
- Optional dependency - BMM works without BMVCS
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### via BMad Method Installer
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "BMVCS: Version Control Suite" from the module list
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
```bash
|
||||
# Copy module to your project
|
||||
cp -r src/modules/bmvcs {project-root}/bmad/bmvcs
|
||||
|
||||
# Run VCS discovery
|
||||
# (activate VCS Adapter agent and run *discover command)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Run VCS Discovery
|
||||
|
||||
```bash
|
||||
# Activate VCS Adapter agent
|
||||
# Run: *discover
|
||||
|
||||
# Interactive prompts will guide you through:
|
||||
# - What VCS you use (Git/SVN/Perforce/None/Custom)
|
||||
# - Your Git workflow (if applicable)
|
||||
# - Team preferences and constraints
|
||||
```
|
||||
|
||||
### 2. VCS Configuration Created
|
||||
|
||||
Discovery saves configuration to `.bmad/vcs-config.yaml`:
|
||||
|
||||
```yaml
|
||||
vcs_config:
|
||||
type: git
|
||||
workflow: github-flow
|
||||
|
||||
adaptations:
|
||||
artifact_format: branches
|
||||
terminology: git
|
||||
commit_style: conventional
|
||||
```
|
||||
|
||||
### 3. Adapt Documents
|
||||
|
||||
```bash
|
||||
# Activate VCS Adapter agent
|
||||
# Run: *adapt-doc architecture.md
|
||||
|
||||
# Document will be adapted to your VCS workflow:
|
||||
# - GitHub Flow: Feature branch strategy, PR workflow
|
||||
# - GitFlow: Release branches, hotfix process
|
||||
# - No VCS: Monolithic delivery, date versioning
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Integration with BMM
|
||||
|
||||
BMVCS integrates optionally with BMM (BMad Method) agents:
|
||||
|
||||
### Architect Agent
|
||||
|
||||
- VCS-adapted architecture documents
|
||||
- Branch strategy recommendations
|
||||
- CI/CD pipeline considerations
|
||||
|
||||
### PM Agent
|
||||
|
||||
- VCS-aware project planning
|
||||
- Release planning adapted to workflow
|
||||
- Story sizing for workflow
|
||||
|
||||
### Dev Agent
|
||||
|
||||
- VCS-adapted commit messages
|
||||
- Workflow-specific conventions
|
||||
- Branch naming patterns
|
||||
|
||||
**Note:** Integration is **optional** - BMM works without BMVCS, BMVCS works without BMM.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **[VCS Agnostic Principles](./docs/VCS_AGNOSTIC_PRINCIPLES.md)** - Philosophy and approach
|
||||
- **[VCS Agnostic Proposal](./docs/VCS_AGNOSTIC_PROPOSAL.md)** - Detailed implementation design
|
||||
- **[VCS Detection Confidence](./docs/VCS_DETECTION_CONFIDENCE.md)** - How discovery scoring works
|
||||
- **[Usage Examples](./docs/examples/vcs-adaptation-examples.md)** - Practical examples
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Supported VCS Systems
|
||||
|
||||
| VCS Type | Workflows | Status |
|
||||
| ------------- | ----------------------------------------- | ------------ |
|
||||
| **Git** | GitHub Flow, GitFlow, Trunk-Based, Custom | ✅ Supported |
|
||||
| **SVN** | Trunk/Branches | ✅ Supported |
|
||||
| **Perforce** | Streams, Classic | ✅ Supported |
|
||||
| **Mercurial** | Generic | ✅ Supported |
|
||||
| **TFS/TFVC** | Generic | ✅ Supported |
|
||||
| **No VCS** | Date-based deliverables | ✅ Supported |
|
||||
| **Custom** | User-defined | ✅ Supported |
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Module Structure
|
||||
|
||||
```
|
||||
src/modules/bmvcs/
|
||||
├── agents/
|
||||
│ └── vcs-adapter.md # VCS Adapter agent
|
||||
├── tasks/
|
||||
│ ├── discover-vcs.md # Interactive VCS discovery
|
||||
│ ├── create-vcs-adapted-doc.md # Document adaptation
|
||||
│ └── validate-vcs-config.md # Config validation
|
||||
├── templates/
|
||||
│ └── vcs-adaptations/
|
||||
│ ├── git-github-flow.yaml
|
||||
│ ├── git-gitflow.yaml
|
||||
│ ├── git-trunk-based.yaml
|
||||
│ ├── no-vcs.yaml
|
||||
│ └── custom-generic.yaml
|
||||
├── workflows/
|
||||
│ └── setup-vcs/ # Initial VCS setup workflow
|
||||
├── docs/ # Documentation
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
BMVCS is part of the BMAD Method project. See [CONTRIBUTING.md](../../../CONTRIBUTING.md) for guidelines.
|
||||
|
||||
### Adding New VCS Support
|
||||
|
||||
1. Add template in `templates/vcs-adaptations/`
|
||||
2. Update `discover-vcs.md` task with new prompts
|
||||
3. Test with real projects using that VCS
|
||||
4. Submit PR with examples
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
Same license as BMAD Method project.
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- **BMAD Method:** https://github.com/bmad-code-org/BMAD-METHOD
|
||||
- **Issue Tracker:** https://github.com/bmad-code-org/BMAD-METHOD/issues
|
||||
- **Discord:** https://discord.gg/gk8jAdXWmj
|
||||
|
||||
---
|
||||
|
||||
**Version:** 6.0.0-alpha
|
||||
**Status:** In Development
|
||||
**Module Code:** `bmvcs`
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
# BMVCS: BMad Version Control Suite Configuration
|
||||
|
||||
code: bmvcs
|
||||
name: "BMVCS: Version Control Suite"
|
||||
default_selected: false # Optional module - install only if VCS adaptation needed
|
||||
|
||||
prompt:
|
||||
- "BMVCS adapts BMAD to your version control workflow"
|
||||
- "Supports Git (GitHub Flow, GitFlow, Trunk-Based), SVN, Perforce, and no-VCS setups"
|
||||
- "All paths are relative to project root, with no leading slash."
|
||||
|
||||
# Variables from Core Config inserted:
|
||||
## user_name
|
||||
## communication_language
|
||||
## output_folder
|
||||
|
||||
vcs_config_location:
|
||||
prompt: "Where should VCS configuration be stored?"
|
||||
default: ".bmad/vcs-config.yaml"
|
||||
result: "{project-root}/{value}"
|
||||
|
||||
run_vcs_discovery:
|
||||
prompt: "Would you like to run VCS discovery now to detect your version control setup?"
|
||||
default: true
|
||||
result: "{value}"
|
||||
type: boolean
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
# VCS Adapter Agent
|
||||
|
||||
<!-- Powered by BMAD-CORE™ -->
|
||||
|
||||
<agent id="bmad/bmvcs/agents/vcs-adapter.md" name="VCS Adapter" title="Version Control Workflow Specialist" icon="🔄">
|
||||
<persona>
|
||||
<role>Version Control Integration Specialist</role>
|
||||
<identity>Adapts BMAD workflows to team's version control practices</identity>
|
||||
<communication_style>Clear, methodical, and VCS-aware</communication_style>
|
||||
<principles>
|
||||
<p>Respect existing workflows - never force change</p>
|
||||
<p>Discover before assuming - ask about VCS setup</p>
|
||||
<p>Adapt language to context - use team's terminology</p>
|
||||
<p>Work with what exists - enhance, don't replace</p>
|
||||
</principles>
|
||||
</persona>
|
||||
|
||||
<critical-actions>
|
||||
<i>Load into memory {project-root}/bmad/bmvcs/config.yaml if exists</i>
|
||||
<i>Check for existing VCS configuration at {vcs_config_location}</i>
|
||||
<i>ALWAYS communicate in {communication_language}</i>
|
||||
</critical-actions>
|
||||
|
||||
<cmds>
|
||||
<c cmd="*help">Show numbered command list</c>
|
||||
<c cmd="*discover">Run VCS discovery to detect version control system</c>
|
||||
<c cmd="*show-config">Display current VCS configuration</c>
|
||||
<c cmd="*adapt-doc">Adapt a document to team's VCS workflow</c>
|
||||
<c cmd="*validate">Validate VCS configuration file</c>
|
||||
<c cmd="*exit">Exit with confirmation</c>
|
||||
</cmds>
|
||||
|
||||
<dependencies>
|
||||
<tasks>
|
||||
<t>discover-vcs.md</t>
|
||||
<t>create-vcs-adapted-doc.md</t>
|
||||
<t>validate-vcs-config.md</t>
|
||||
</tasks>
|
||||
<templates>
|
||||
<t>vcs-adaptations/git-github-flow.yaml</t>
|
||||
<t>vcs-adaptations/git-gitflow.yaml</t>
|
||||
<t>vcs-adaptations/git-trunk-based.yaml</t>
|
||||
<t>vcs-adaptations/no-vcs.yaml</t>
|
||||
<t>vcs-adaptations/custom-generic.yaml</t>
|
||||
</templates>
|
||||
</dependencies>
|
||||
|
||||
<activation-instructions>
|
||||
<i>STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition</i>
|
||||
<i>STEP 2: Adopt the persona defined in the 'persona' section above</i>
|
||||
<i>STEP 3: Check if VCS configuration exists, if not offer to run discovery</i>
|
||||
<i>STEP 4: Greet user with your name/role and immediately run *help</i>
|
||||
<i>DO NOT: Load any other agent files during activation</i>
|
||||
<i>ONLY load dependency files when user selects them for execution</i>
|
||||
</activation-instructions>
|
||||
|
||||
<vcs-philosophy>
|
||||
<principle>Optimize for the majority (Git ~85-90%), open to all</principle>
|
||||
<principle>Discover before assumption - never assume Git</principle>
|
||||
<principle>Respect "no VCS" as valid choice</principle>
|
||||
<principle>Adapt language: Git users get "commit/branch", SVN gets "revision/trunk"</principle>
|
||||
<principle>Structure follows function: GitHub Flow = small artifacts, No VCS = monolithic packages</principle>
|
||||
</vcs-philosophy>
|
||||
|
||||
<knowledge-base>
|
||||
<doc>VCS_AGNOSTIC_PRINCIPLES.md</doc>
|
||||
<doc>VCS_AGNOSTIC_PROPOSAL.md</doc>
|
||||
<doc>VCS_DETECTION_CONFIDENCE.md</doc>
|
||||
</knowledge-base>
|
||||
</agent>
|
||||
|
||||
## Agent Description
|
||||
|
||||
The VCS Adapter makes BMAD truly universal by adapting to any version control system. Instead of forcing teams to change their workflows, this agent discovers their existing practices and adjusts BMAD's output accordingly.
|
||||
|
||||
### Supported VCS Types
|
||||
|
||||
- **Git workflows:** GitHub Flow, GitFlow, Trunk-Based Development
|
||||
- **Other VCS:** Subversion (SVN), Perforce, Mercurial, TFS
|
||||
- **No VCS:** Self-contained deliverables with date versioning
|
||||
- **Custom:** Team-specific workflows
|
||||
|
||||
### Key Capabilities
|
||||
|
||||
1. **Discovery:** Detects VCS type and workflow through interactive prompts
|
||||
2. **Adaptation:** Adjusts documentation, terminology, and artifact structure
|
||||
3. **Validation:** Ensures VCS configuration is correct and consistent
|
||||
4. **Integration:** Works with BMM agents for VCS-aware planning
|
||||
|
||||
### Usage Example
|
||||
|
||||
```
|
||||
User: *discover
|
||||
Agent: Runs VCS discovery workflow, saves configuration
|
||||
|
||||
User: *adapt-doc architecture.md
|
||||
Agent: Adapts architecture document to team's Git workflow
|
||||
```
|
||||
|
||||
## Integration with BMM
|
||||
|
||||
This agent can be used standalone or integrated with BMM agents:
|
||||
|
||||
- **Architect**: VCS-adapted architecture documents
|
||||
- **PM**: VCS-aware project planning
|
||||
- **Dev**: VCS-adapted commit messages and workflow
|
||||
|
||||
Integration is **optional** - BMVCS works independently.
|
||||
Loading…
Reference in New Issue