feat(core): Add VCS discovery mechanism

Introduces core VCS discovery functionality to make BMAD adapt to existing version control practices.

- Add discover-vcs.md task for identifying team's VCS approach
- Update Architect agent to run VCS discovery on activation
- Add VCS_AGNOSTIC_PRINCIPLES.md documenting the approach
- Enable support for Git, SVN, Perforce, and no-VCS workflows

Aligns with "Optimized for the majority, open to all" principle.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

bmad-core/agents/architect.md

@@ -20,6 +20,7 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: Load and read `.bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 3.5: Check if VCS configuration exists in `.bmad-core/vcs-config.yaml`, if not, execute task `discover-vcs.md`
   - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
@@ -53,13 +54,15 @@ persona:
     - Data-Centric Design - Let data requirements drive architecture
     - Cost-Conscious Engineering - Balance technical ideals with financial reality
     - Living Architecture - Design for change and adaptation
+    - VCS-Agnostic Design - Adapt architecture to team's version control practices, not vice versa
 # All commands require * prefix when used (e.g., *help)
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-backend-architecture: use create-doc with architecture-tmpl.yaml
+  - discover-vcs: Execute discover-vcs.md task to identify team's version control approach
-  - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml
+  - create-backend-architecture: use create-doc with architecture-tmpl.yaml (VCS-adapted)
-  - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml
+  - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml (VCS-adapted)
-  - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml
+  - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml (VCS-adapted)
+  - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml (VCS-adapted)
   - doc-out: Output full document to current destination file
   - document-project: execute the task document-project.md
   - execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)
@@ -75,6 +78,7 @@ dependencies:
   tasks:
     - create-deep-research-prompt.md
     - create-doc.md
+    - discover-vcs.md
     - document-project.md
     - execute-checklist.md
   templates:
@@ -82,4 +86,10 @@ dependencies:
     - brownfield-architecture-tmpl.yaml
     - front-end-architecture-tmpl.yaml
     - fullstack-architecture-tmpl.yaml
+  vcs-adaptations:
+    - vcs-adaptations/git-github-flow.yaml
+    - vcs-adaptations/git-gitflow.yaml
+    - vcs-adaptations/git-trunk-based.yaml
+    - vcs-adaptations/no-vcs.yaml
+    - vcs-adaptations/custom-generic.yaml
 ```

bmad-core/tasks/discover-vcs.md

@@ -0,0 +1,187 @@
+# VCS Discovery Task
+
+## Purpose
+
+Identify and adapt to the team's version control system at project initialization.
+
+## Philosophy
+
+- Optimize for the 85-90% who use Git
+- Remain open for the 10-15% with special needs
+- Suggest best practices without forcing them
+
+## Task Instructions
+
+### Step 1: Initial Discovery
+
+```yaml
+elicit: true
+prompt: |
+  How does your team manage code versions?
+
+  1. Git with GitHub/GitLab/Bitbucket [MOST COMMON]
+  2. Git with corporate server
+  3. Other version control system
+  4. No version control needed
+  5. Custom/Complex setup
+
+  Select a number (1-5):
+```
+
+### Step 2A: Git-Based Workflows (Options 1-2)
+
+If user selects Git-based:
+
+```yaml
+elicit: true
+prompt: |
+  Which Git workflow best describes your team's approach?
+
+  1. GitHub Flow - Simple feature branches with pull requests
+     → Best for: Web apps, continuous deployment
+
+  2. GitFlow - Structured branches (develop, release, hotfix)
+     → Best for: Versioned software, scheduled releases
+
+  3. Trunk-Based - Direct commits or very short branches
+     → Best for: Mature CI/CD, experienced teams
+
+  4. Not sure - I'd like a recommendation
+     → We'll ask a few questions to suggest the best fit
+
+  5. Custom Git workflow
+     → Describe your approach
+
+  Select a number (1-5):
+```
+
+#### If "Not sure" (Option 4):
+
+```yaml
+elicit: true
+questions:
+  - 'How many developers on your team? (1, 2-5, 6+)'
+  - 'How often do you release? (Daily, Weekly, Monthly, Quarterly)'
+  - 'Do you have automated testing? (Yes/No)'
+  - 'Do you need to maintain multiple versions? (Yes/No)'
+
+recommendation_logic: |
+  - Solo or Daily releases + Automated tests → Trunk-Based
+  - Small team + Weekly/Monthly → GitHub Flow
+  - Large team or Multiple versions → GitFlow
+  - Default → GitHub Flow (safest choice)
+```
+
+#### If "Custom" (Option 5):
+
+```yaml
+elicit: true
+prompt: |
+  Please briefly describe your Git workflow:
+  (e.g., "We use feature branches but merge to staging first, then production")
+
+  [Free text input]
+```
+
+### Step 2B: Other VCS (Option 3)
+
+```yaml
+elicit: true
+prompt: |
+  Which version control system do you use?
+
+  1. Subversion (SVN)
+  2. Perforce
+  3. Mercurial
+  4. Team Foundation Server (TFS)
+  5. Other (please specify)
+
+  Select a number or describe:
+```
+
+### Step 2C: No VCS (Option 4)
+
+```yaml
+confirm: |
+  Understood. BMAD will generate:
+  - Self-contained deliverables
+  - Date-versioned packages
+  - No commit messages or branch references
+
+  Is this a prototype/one-time project? (Yes/No)
+```
+
+### Step 2D: Complex Setup (Option 5)
+
+```yaml
+elicit: true
+prompt: |
+  Please describe your version control setup:
+  (e.g., "Monorepo with custom tooling", "Multiple systems for different components")
+
+  [Free text input]
+```
+
+### Step 3: Store Configuration
+
+Save the VCS configuration for all agents to access:
+
+```yaml
+vcs_config:
+  type: [git|svn|perforce|none|custom]
+  workflow: [github-flow|gitflow|trunk-based|custom|none]
+  details: [user's custom description if provided]
+
+  adaptations:
+    artifact_format: [branches|monolithic|platform-specific]
+    terminology: [git|generic|platform-specific]
+    commit_style: [conventional|team-specific|none]
+```
+
+### Step 4: Confirm Understanding
+
+```yaml
+output: |
+  VCS Configuration Confirmed:
+  - System: {type}
+  - Workflow: {workflow}
+  - BMAD will adapt by: {key_adaptations}
+
+  All agents will generate artifacts compatible with your setup.
+```
+
+## Success Criteria
+
+- 80% of users can select from predefined options
+- 20% custom cases are handled gracefully
+- Configuration is stored and accessible to all agents
+- No Git assumptions for non-Git users
+- Clear recommendations when requested
+
+## Agent Adaptations Based on VCS
+
+### For Architect Agent
+
+- Git + GitHub Flow: Suggest feature-based architecture docs
+- Git + GitFlow: Support release-oriented planning
+- No VCS: Generate comprehensive, dated documents
+- Custom: Ask for preferred format
+
+### For Dev Agent
+
+- Git workflows: Generate appropriate commit messages
+- No VCS: Package complete code solutions
+- Custom: Follow described conventions
+
+### For SM Agent
+
+- Git + Trunk: Create small, atomic stories
+- Git + GitFlow: Support epic-based stories
+- No VCS: Create comprehensive story documents
+
+## Notes
+
+- This discovery happens ONCE at project start
+- All agents read this configuration
+- Can be updated if team process changes
+- Default to GitHub Flow if uncertain (most common, safest)

docs/VCS_AGNOSTIC_PRINCIPLES.md

@@ -0,0 +1,161 @@
+# 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.**