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>
2025-09-15 09:30:02 +03:00 · 2025-09-15 09:30:02 +03:00 · 4a86c2d9e5
parent 7ab6085036
commit 4a86c2d9e5
2 changed files with 479 additions and 0 deletions
--- a/bmad-core/examples/vcs-adaptation-examples.md
+++ b/bmad-core/examples/vcs-adaptation-examples.md
@ -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.
--- a/docs/VCS_AGNOSTIC_PROPOSAL.md
+++ b/docs/VCS_AGNOSTIC_PROPOSAL.md
@ -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.