# VCS-Agnostic Principles for BMAD

## Core Philosophy

**"Optimized for the majority, open to all"**

BMAD adapts to teams' existing version control practices rather than imposing new ones. We recognize that ~85-90% use Git, but remain fully functional for those who don't.

## The 10 Principles

### 1. Discovery Before Assumption

- Always ask about VCS approach first
- Never assume Git or any specific system
- Respect "no VCS" as a valid choice

### 2. Optimize for the Common Case

- Provide quick picks for Git workflows (~85-90% of users)
- Make popular choices easy to select
- Keep edge cases possible but not prominent

### 3. Adapt Language to Context

- Git users: "commit", "branch", "merge"
- SVN users: "revision", "trunk", "update"
- No VCS: "package", "version", "deliverable"
- Generic: "save changes", "workspace", "integrate"

### 4. Structure Follows Function

- GitHub Flow: Small, PR-sized artifacts
- GitFlow: Version-oriented documentation
- Trunk-Based: Flag-gated increments
- No VCS: Monolithic, dated packages

### 5. Respect Existing Workflows

- Document their process, don't change it
- Work within their constraints
- Enhance, don't replace

### 6. Practical Over Theoretical

- Suggest only when asked
- Provide what works, not what's "best"
- Focus on delivery, not process

### 7. Progressive Disclosure

- Simple choices for majority upfront
- Complex options available but hidden
- Custom escape hatch always present

### 8. Context-Aware Generation

- Architecture adapts to VCS choice
- Stories sized for their workflow
- Documentation matches their practices

### 9. Terminology Consistency

- Once VCS is identified, use their terms throughout
- Don't mix Git and SVN terminology
- Be consistent within a project

### 10. Zero Friction Adoption

- Work with what they have
- No required process changes
- Value delivery over methodology

## Implementation Guidelines

### For Agent Developers

#### DO:

- Check for VCS configuration early
- Load appropriate adaptation templates
- Use conditional logic based on VCS type
- Provide examples for different systems
- Test with non-Git users

#### DON'T:

- Hardcode Git commands
- Assume branches exist
- Force commit message formats
- Require specific tools
- Judge non-standard approaches

### For BMAD Users

#### What to Expect:

- Initial question about your VCS
- Adapted terminology and workflows
- Artifacts that fit your process
- Respect for your existing practices
- No forced "improvements"

#### How to Get Best Results:

- Be clear about your VCS setup
- Describe custom workflows if needed
- Ask for clarification if unsure
- Request changes if something doesn't fit

## Configuration Storage

VCS configuration is stored in `.bmad-core/vcs-config.yaml`:

```yaml
vcs_config:
  type: git|svn|perforce|none|custom
  workflow: github-flow|gitflow|trunk-based|custom|none
  details: 'Custom description if provided'

  adaptations:
    artifact_format: branches|monolithic|platform-specific
    terminology: git|svn|generic|custom
    commit_style: conventional|team-specific|none
```

## Testing Checklist

Verify BMAD works correctly with:

- [ ] Git + GitHub Flow
- [ ] Git + GitFlow
- [ ] Git + Trunk-Based
- [ ] Git + Custom workflow
- [ ] SVN
- [ ] Perforce
- [ ] No VCS
- [ ] Mixed/Complex setup

## Success Metrics

- 80% of users select from predefined options
- 20% custom cases handled gracefully
- Zero Git assumptions for non-Git users
- No friction from VCS differences
- Positive feedback from diverse teams

## Evolution Path

As version control evolves:

1. Add new templates for emerging patterns
2. Update terminology mappings
3. Maintain backward compatibility
4. Never remove support for "legacy" systems
5. Keep "no VCS" option always available

## Conclusion

VCS-agnosticism makes BMAD truly universal. By respecting teams' existing practices and adapting to their workflows, BMAD becomes a tool that enhances productivity without forcing change.

The goal is simple: **Make BMAD work with whatever the team has, not force the team to work with what BMAD expects.**