docs: Add VCS-agnostic documentation and examples
Comprehensive documentation explaining the VCS-agnostic approach. - Add VCS_AGNOSTIC_PROPOSAL.md with detailed rationale and implementation - Add vcs-adaptation-examples.md with practical usage examples - Include interaction scenarios for different VCS setups - Document success metrics and anti-patterns to avoid Helps teams understand how BMAD adapts to their existing workflows. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Serhii
parent
7ab6085036
commit
4a86c2d9e5
|
|
@ -0,0 +1,293 @@
|
|||
# VCS Adaptation Examples
|
||||
|
||||
## Real-World Scenarios: How BMAD Adapts
|
||||
|
||||
### Example 1: Startup with GitHub Flow
|
||||
|
||||
**Context:** 5-person team, web SaaS, deploys daily
|
||||
|
||||
**Discovery:**
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "Git with GitHub"
|
||||
BMAD: "Which Git workflow best describes your approach?"
|
||||
User: "GitHub Flow - simple feature branches"
|
||||
```
|
||||
|
||||
**BMAD Adapts:**
|
||||
|
||||
- Architect generates lightweight, PR-sized architecture updates
|
||||
- SM creates 1-3 day stories that map to single PRs
|
||||
- Dev suggests branch names like `feature/add-user-auth`
|
||||
- All docs optimized for quick review in PR comments
|
||||
|
||||
**Generated Architecture Snippet:**
|
||||
|
||||
```markdown
|
||||
## Payment Service Update
|
||||
|
||||
_PR: #234 - feature/add-stripe-integration_
|
||||
|
||||
### Changes in This PR
|
||||
|
||||
- New Stripe webhook handler
|
||||
- Updated payment models
|
||||
- Added retry logic
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Unit tests for webhook handler
|
||||
- [ ] Integration test with Stripe test mode
|
||||
- [ ] Manual testing checklist in PR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Enterprise with GitFlow
|
||||
|
||||
**Context:** 50-person team, banking software, quarterly releases
|
||||
|
||||
**Discovery:**
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "Git with corporate server"
|
||||
BMAD: "Which Git workflow?"
|
||||
User: "GitFlow - we have develop, release, and hotfix branches"
|
||||
```
|
||||
|
||||
**BMAD Adapts:**
|
||||
|
||||
- Architect creates version-oriented architecture docs
|
||||
- PM generates release-scoped PRDs
|
||||
- SM groups stories by release version
|
||||
- Dev follows strict branch naming
|
||||
|
||||
**Generated Architecture Snippet:**
|
||||
|
||||
```markdown
|
||||
## Release 2.4.0 Architecture
|
||||
|
||||
### Version Highlights
|
||||
|
||||
- New authentication system (breaking change)
|
||||
- Performance improvements
|
||||
- Database migration required
|
||||
|
||||
### Branch Status
|
||||
|
||||
- develop: v2.5.0 features in progress
|
||||
- release/2.4.0: Final testing
|
||||
- hotfix/2.3.1: Critical fix for production
|
||||
|
||||
### Migration Guide
|
||||
|
||||
From 2.3.x to 2.4.0:
|
||||
|
||||
1. Run migration script
|
||||
2. Update config files
|
||||
3. Restart services in order
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: No Version Control
|
||||
|
||||
**Context:** Data scientist, one-time analysis script
|
||||
|
||||
**Discovery:**
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "No version control needed - this is a one-time script"
|
||||
```
|
||||
|
||||
**BMAD Adapts:**
|
||||
|
||||
- All code in single, runnable package
|
||||
- Extensive inline documentation
|
||||
- No commit messages or branch references
|
||||
- Date-stamped delivery
|
||||
|
||||
**Generated Package:**
|
||||
|
||||
```
|
||||
customer_analysis_20240315/
|
||||
├── README.md # Complete instructions
|
||||
├── requirements.txt # All Python dependencies
|
||||
├── analysis.py # Full script with comments
|
||||
├── data/
|
||||
│ └── sample.csv # Sample data format
|
||||
└── output/
|
||||
└── results_template.xlsx
|
||||
```
|
||||
|
||||
**README Content:**
|
||||
|
||||
```markdown
|
||||
# Customer Analysis Script
|
||||
|
||||
Generated: 2024-03-15
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Install dependencies: pip install -r requirements.txt
|
||||
2. Place your data in data/input.csv
|
||||
3. Run: python analysis.py
|
||||
4. Results appear in output/
|
||||
|
||||
## No Version Control Required
|
||||
|
||||
This is a complete, self-contained package.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 4: Custom SVN Workflow
|
||||
|
||||
**Context:** Game studio using Subversion
|
||||
|
||||
**Discovery:**
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "Other version control system"
|
||||
BMAD: "Which system?"
|
||||
User: "Subversion (SVN)"
|
||||
```
|
||||
|
||||
**BMAD Adapts:**
|
||||
|
||||
- Uses "revision" instead of "commit"
|
||||
- References trunk/branches/tags structure
|
||||
- Revision numbers, not hashes
|
||||
- SVN-specific commands
|
||||
|
||||
**Generated Instructions:**
|
||||
|
||||
```markdown
|
||||
## Integration Steps
|
||||
|
||||
1. Update your working copy:
|
||||
svn update
|
||||
|
||||
2. Create feature branch:
|
||||
svn copy ^/trunk ^/branches/feature-player-inventory
|
||||
|
||||
3. After implementation:
|
||||
svn merge ^/branches/feature-player-inventory
|
||||
|
||||
4. Commit with revision message:
|
||||
svn commit -m "Add player inventory system (refs ticket #456)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 5: Trunk-Based with Feature Flags
|
||||
|
||||
**Context:** Netflix-style continuous deployment
|
||||
|
||||
**Discovery:**
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "Git with GitHub"
|
||||
BMAD: "Which Git workflow?"
|
||||
User: "Trunk-Based - we deploy continuously"
|
||||
```
|
||||
|
||||
**BMAD Adapts:**
|
||||
|
||||
- Everything behind feature flags
|
||||
- Tiny, hours-long tasks
|
||||
- Direct commits or same-day PRs
|
||||
- Progressive rollout plans
|
||||
|
||||
**Generated Story:**
|
||||
|
||||
````markdown
|
||||
## Story: Add Recommendation Engine
|
||||
|
||||
Size: 4 hours
|
||||
Flag: `recommendation-engine-v2`
|
||||
|
||||
### Implementation
|
||||
|
||||
```python
|
||||
if feature_flag.is_enabled("recommendation-engine-v2", user_id):
|
||||
return new_recommendation_engine(user_id)
|
||||
else:
|
||||
return legacy_recommendations(user_id)
|
||||
```
|
||||
````
|
||||
|
||||
### Rollout Plan
|
||||
|
||||
- Hour 1-2: Implement behind flag (0% users)
|
||||
- Hour 3: Deploy and enable for employees
|
||||
- Hour 4: Enable for 1% external users
|
||||
- Day 2: 10% if metrics good
|
||||
- Day 3: 50%
|
||||
- Day 5: 100% and schedule flag removal
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 6: Complex Multi-VCS Setup
|
||||
|
||||
**Context:** Enterprise with mixed systems
|
||||
|
||||
**Discovery:**
|
||||
```
|
||||
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "Custom/Complex setup"
|
||||
BMAD: "Please describe:"
|
||||
User: "Frontend in Git, backend in Perforce, configs in SVN"
|
||||
|
||||
````
|
||||
|
||||
**BMAD Adapts:**
|
||||
- Asks for component-specific preferences
|
||||
- Generates VCS-appropriate artifacts per component
|
||||
- Uses neutral terminology in cross-component docs
|
||||
|
||||
**Generated Guidance:**
|
||||
```markdown
|
||||
## Multi-VCS Development Guide
|
||||
|
||||
### Frontend (Git/GitHub Flow)
|
||||
- Feature branches from main
|
||||
- PR review process
|
||||
- Deploy on merge
|
||||
|
||||
### Backend (Perforce)
|
||||
- Create changelist for features
|
||||
- Submit after review
|
||||
- Changelist numbers in deployment notes
|
||||
|
||||
### Configuration (SVN)
|
||||
- Update from trunk before changes
|
||||
- Commit with revision references
|
||||
- Tag for production releases
|
||||
|
||||
### Cross-Component Changes
|
||||
When updating across systems:
|
||||
1. Frontend PR: #123
|
||||
2. Backend Changelist: 456789
|
||||
3. Config Revision: r1234
|
||||
|
||||
Reference all three in deployment ticket.
|
||||
````
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
1. **BMAD never assumes** - always discovers first
|
||||
2. **Adapts terminology** - commit/changelist/revision as appropriate
|
||||
3. **Respects workflows** - doesn't try to "improve" existing processes
|
||||
4. **Practical focus** - generates what works with their tools
|
||||
5. **Clear communication** - uses the team's language
|
||||
|
||||
This flexibility makes BMAD valuable to ANY team, regardless of their VCS choice.
|
||||
|
|
@ -0,0 +1,186 @@
|
|||
# VCS-Agnostic Approach for BMAD-METHOD
|
||||
|
||||
## Core Philosophy: "BMAD Suggests, User Decides"
|
||||
|
||||
### Executive Summary
|
||||
|
||||
BMAD should adapt to existing team practices rather than impose specific version control strategies. This proposal outlines a flexible, discovery-based approach to VCS integration.
|
||||
|
||||
## The Problem with Current Assumptions
|
||||
|
||||
Current BMAD and the Gemini analysis document assume:
|
||||
|
||||
- All projects use Git
|
||||
- Teams need "best practice" workflows
|
||||
- Version control strategy is primarily technical
|
||||
|
||||
Reality:
|
||||
|
||||
- Many teams have unique, working systems
|
||||
- Some projects don't need VCS at all
|
||||
- VCS choice is often organizational/political, not technical
|
||||
|
||||
## Proposed Solution: VCS Discovery Protocol
|
||||
|
||||
### 1. Initial Discovery Question
|
||||
|
||||
```yaml
|
||||
vcs_discovery:
|
||||
initial_question: 'How does your team manage code versions?'
|
||||
|
||||
response_paths:
|
||||
established_system:
|
||||
- 'We have our own system that works'
|
||||
- BMAD: 'Great! Tell me about it so I can adapt'
|
||||
|
||||
no_vcs:
|
||||
- "We don't use version control"
|
||||
- BMAD: "Understood. I'll generate self-contained packages"
|
||||
|
||||
need_guidance:
|
||||
- 'We need recommendations'
|
||||
- BMAD: 'Let me understand your context first...'
|
||||
```
|
||||
|
||||
### 2. Adaptation Matrix
|
||||
|
||||
| User Response | BMAD Adaptation |
|
||||
| --------------------------- | ----------------------------------------------------- |
|
||||
| "Custom Git workflow" | Agents use generic Git terms, no strategy assumptions |
|
||||
| "No VCS (prototype)" | Single deliverable packages with date versioning |
|
||||
| "Platform VCS (Salesforce)" | Platform-specific artifacts and terminology |
|
||||
| "Legacy system (SVN)" | VCS-agnostic artifacts, no Git-specific features |
|
||||
| "It's complicated..." | Free-form description, custom adaptation |
|
||||
|
||||
### 3. Agent Behavioral Adaptations
|
||||
|
||||
#### Architect Agent
|
||||
|
||||
```yaml
|
||||
vcs_adaptations:
|
||||
no_vcs:
|
||||
- Generate monolithic architecture document
|
||||
- Include all specs in single package
|
||||
- Version via: PROJECTNAME_ARCH_YYYYMMDD.md
|
||||
|
||||
custom_vcs:
|
||||
- Ask: 'What format works with your system?'
|
||||
- Avoid Git-specific terminology
|
||||
- Focus on deliverables, not process
|
||||
```
|
||||
|
||||
#### Developer Agent
|
||||
|
||||
```yaml
|
||||
vcs_adaptations:
|
||||
no_vcs:
|
||||
- Generate complete code blocks
|
||||
- No commit message suggestions
|
||||
- Package as: FEATURE_COMPLETE_YYYYMMDD.zip
|
||||
|
||||
custom_vcs:
|
||||
- Ask: 'How should I structure code changes?'
|
||||
- Follow team's existing patterns
|
||||
```
|
||||
|
||||
#### SM Agent
|
||||
|
||||
```yaml
|
||||
vcs_adaptations:
|
||||
no_vcs:
|
||||
- Create comprehensive story documents
|
||||
- Include all context in each story
|
||||
|
||||
git_based:
|
||||
- Option to create branch-scoped stories
|
||||
- But only if team requests it
|
||||
```
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Phase 1: Discovery Mechanism
|
||||
|
||||
Create `bmad-core/tasks/discover-vcs.md`:
|
||||
|
||||
- Non-assumptive questions
|
||||
- Multiple response paths
|
||||
- Custom description option
|
||||
|
||||
### Phase 2: Adaptation Templates
|
||||
|
||||
Create `bmad-core/templates/vcs-adaptations/`:
|
||||
|
||||
- `no-vcs.yaml`
|
||||
- `git-agnostic.yaml`
|
||||
- `platform-specific.yaml`
|
||||
- `custom-adapter.yaml`
|
||||
|
||||
### Phase 3: Agent Updates
|
||||
|
||||
Modify each agent to:
|
||||
|
||||
1. Check VCS context before generating artifacts
|
||||
2. Adapt output format based on VCS choice
|
||||
3. Never assume Git unless confirmed
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **No Assumptions**: Never assume Git or any specific VCS
|
||||
2. **Respect Existing**: Honor teams' current working systems
|
||||
3. **Adapt, Don't Educate**: We adapt to them, not vice versa
|
||||
4. **Suggest When Asked**: Only provide recommendations when requested
|
||||
5. **Custom is Valid**: "Our own way" is a perfectly valid answer
|
||||
|
||||
## Example Interactions
|
||||
|
||||
### Scenario 1: Team with Custom Process
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "We use Git but with our own branching model based on features and environments"
|
||||
BMAD: "Perfect! I'll adapt to your model. Could you briefly describe when code moves between environments?"
|
||||
User: [describes their process]
|
||||
BMAD: "Got it. I'll structure artifacts to align with your feature→environment flow"
|
||||
```
|
||||
|
||||
### Scenario 2: No VCS Needed
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "This is a one-time data migration script, no versioning needed"
|
||||
BMAD: "Understood. I'll generate a single, complete package with clear documentation"
|
||||
```
|
||||
|
||||
### Scenario 3: Guidance Requested
|
||||
|
||||
```
|
||||
BMAD: "How does your team manage code versions?"
|
||||
User: "We're not sure, what do you recommend?"
|
||||
BMAD: "Let me understand your context first:
|
||||
- How many developers?
|
||||
- How often do you release?
|
||||
- Is this a new project or existing codebase?"
|
||||
[After answers]
|
||||
BMAD: "Based on your context, here are 2 options that could work..."
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- Zero assumptions about Git in initial interactions
|
||||
- Successful adaptation to 10+ different VCS approaches
|
||||
- No forced "best practices" unless requested
|
||||
- Positive feedback from teams with non-standard processes
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
❌ "You should use Trunk-Based Development"
|
||||
❌ "Git is the industry standard"
|
||||
❌ "Your process could be improved by..."
|
||||
❌ Generating Git-specific artifacts without confirmation
|
||||
❌ Assuming branches exist
|
||||
|
||||
## Conclusion
|
||||
|
||||
BMAD's strength lies in adaptation, not prescription. By adopting a truly VCS-agnostic approach, BMAD becomes useful to ALL teams, regardless of their version control choices or lack thereof.
|
||||
|
||||
The goal: Make BMAD work with whatever the team has, not force the team to work with what BMAD expects.
|
||||
Loading…
Reference in New Issue