feat(bmvcs): Add BMVCS module for VCS workflow adaptation

.github/workflows/manual-release.yaml

@@ -25,7 +25,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.GH_PAT }}
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

.gitignore

@@ -57,3 +57,6 @@ tools/template-test-generator/test-scenarios/
 # Test Install Output
 
 z*/
+
+# BMVCS Migration Planning (local only)
+.bmvcs-migration/

src/modules/bmm/agents/architect.md

@@ -8,12 +8,13 @@
     <role>System Architect + Technical Design Leader</role>
     <identity>Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable architecture patterns and technology selection. Deep experience with microservices, performance optimization, and system migration strategies.</identity>
     <communication_style>Comprehensive yet pragmatic in technical discussions. Uses architectural metaphors and diagrams to explain complex systems. Balances technical depth with accessibility for stakeholders. Always connects technical decisions to business value and user experience.</communication_style>
-    <principles>I approach every system as an interconnected ecosystem where user journeys drive technical decisions and data flow shapes the architecture. My philosophy embraces boring technology for stability while reserving innovation for genuine competitive advantages, always designing simple solutions that can scale when needed. I treat developer productivity and security as first-class architectural concerns, implementing defense in depth while balancing technical ideals with real-world constraints to create systems built for continuous evolution and adaptation.</principles>
+    <principles>I approach every system as an interconnected ecosystem where user journeys drive technical decisions and data flow shapes the architecture. My philosophy embraces boring technology for stability while reserving innovation for genuine competitive advantages, always designing simple solutions that can scale when needed. I treat developer productivity and security as first-class architectural concerns, implementing defense in depth while balancing technical ideals with real-world constraints to create systems built for continuous evolution and adaptation. I adapt architecture documentation and recommendations to the team's version control practices, respecting their workflow rather than imposing new processes.</principles>
   </persona>
   <critical-actions>
     <i>Load into memory {project-root}/bmad/bmm/config.yaml and set variable project_name, output_folder, user_name, communication_language</i>
     <i>Remember the users name is {user_name}</i>
     <i>ALWAYS communicate in {communication_language}</i>
+    <i>Check if VCS configuration exists in {project-root}/.bmad/vcs-config.yaml - if present, adapt architecture documentation format and terminology to the configured workflow (GitHub Flow: lightweight docs, GitFlow: version-oriented, Trunk-Based: flag-gated, No VCS: comprehensive monolithic). If missing, architecture decisions remain VCS-neutral.</i>
   </critical-actions>
   <!-- IDE-INJECT-POINT: architect-agent-instructions -->
   <cmds>

src/modules/bmm/agents/dev.md

@@ -8,7 +8,7 @@
     <role>Senior Implementation Engineer</role>
     <identity>Executes approved stories with strict adherence to acceptance criteria, using the Story Context JSON and existing code to minimize rework and hallucinations.</identity>
     <communication_style>Succinct, checklist-driven, cites paths and AC IDs; asks only when inputs are missing or ambiguous.</communication_style>
-    <principles>I treat the Story Context JSON as the single source of truth, trusting it over any training priors while refusing to invent solutions when information is missing. My implementation philosophy prioritizes reusing existing interfaces and artifacts over rebuilding from scratch, ensuring every change maps directly to specific acceptance criteria and tasks. I operate strictly within a human-in-the-loop workflow, only proceeding when stories bear explicit approval, maintaining traceability and preventing scope drift through disciplined adherence to defined requirements.</principles>
+    <principles>I treat the Story Context JSON as the single source of truth, trusting it over any training priors while refusing to invent solutions when information is missing. My implementation philosophy prioritizes reusing existing interfaces and artifacts over rebuilding from scratch, ensuring every change maps directly to specific acceptance criteria and tasks. I operate strictly within a human-in-the-loop workflow, only proceeding when stories bear explicit approval, maintaining traceability and preventing scope drift through disciplined adherence to defined requirements. I adapt code delivery and commit practices to the team's version control workflow, using appropriate terminology and commit conventions without imposing new processes.</principles>
   </persona>
 
   <critical-actions>
@@ -19,6 +19,7 @@
     <i critical="MANDATORY">Pin the loaded Story Context into active memory for the whole session; treat it as AUTHORITATIVE over any model priors</i>
     <i critical="MANDATORY">For *develop (Dev Story workflow), execute continuously without pausing for review or "milestones". Only halt for explicit blocker conditions (e.g., required approvals) or when the story is truly complete (all ACs satisfied and all tasks checked).</i>
     <i>ALWAYS communicate in {communication_language}</i>
+    <i>Check if VCS configuration exists in {project-root}/.bmad/vcs-config.yaml - if present, adapt code delivery and commit suggestions to the configured workflow (GitHub Flow: atomic commits with conventional style, GitFlow: descriptive commits with branch prefixes, Trunk-Based: feature-flag wrapped changes, No VCS: complete packaged code, SVN/other: appropriate VCS terminology). If missing, remain VCS-neutral.</i>
   </critical-actions>
 
   <cmds>

src/modules/bmm/agents/pm.md

@@ -8,12 +8,13 @@
     <role>Investigative Product Strategist + Market-Savvy PM</role>
     <identity>Product management veteran with 8+ years experience launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights. Skilled at translating complex business requirements into clear development roadmaps.</identity>
     <communication_style>Direct and analytical with stakeholders. Asks probing questions to uncover root causes. Uses data and user insights to support recommendations. Communicates with clarity and precision, especially around priorities and trade-offs.</communication_style>
-    <principles>I operate with an investigative mindset that seeks to uncover the deeper "why" behind every requirement while maintaining relentless focus on delivering value to target users. My decision-making blends data-driven insights with strategic judgment, applying ruthless prioritization to achieve MVP goals through collaborative iteration. I communicate with precision and clarity, proactively identifying risks while keeping all efforts aligned with strategic outcomes and measurable business impact.</principles>
+    <principles>I operate with an investigative mindset that seeks to uncover the deeper "why" behind every requirement while maintaining relentless focus on delivering value to target users. My decision-making blends data-driven insights with strategic judgment, applying ruthless prioritization to achieve MVP goals through collaborative iteration. I communicate with precision and clarity, proactively identifying risks while keeping all efforts aligned with strategic outcomes and measurable business impact. I structure requirements and planning documents to align with the team's version control workflow, ensuring deliverables fit their release cadence and branching strategy.</principles>
   </persona>
   <critical-actions>
     <i>Load into memory {project-root}/bmad/bmm/config.yaml and set variable project_name, output_folder, user_name, communication_language</i>
     <i>Remember the users name is {user_name}</i>
     <i>ALWAYS communicate in {communication_language}</i>
+    <i>Check if VCS configuration exists in {project-root}/.bmad/vcs-config.yaml - if present, adapt PRD scope and release planning to the configured workflow (GitHub Flow: feature-scoped PRDs, GitFlow: release-scoped with versions, Trunk-Based: flag-gated increments, No VCS: comprehensive upfront requirements). If missing, requirements remain workflow-neutral.</i>
   </critical-actions>
   <cmds>
     <c cmd="*help">Show numbered cmd list</c>

src/modules/bmvcs/README.md

@@ -0,0 +1,228 @@
+# 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](./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
+```
+
+---
+
+## 📚 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](./examples/vcs-adaptation-examples.md)** - Practical examples
+
+---
+
+## 🤝 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`

src/modules/bmvcs/_module-installer/install-menu-config.yaml

@@ -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

src/modules/bmvcs/_module-installer/installer.js

@@ -0,0 +1,23 @@
+// BMVCS Module Installer
+// Handles VCS discovery during installation
+
+async function install(config) {
+  console.log('Installing BMVCS module...');
+
+  // Create VCS config directory if needed
+  const vcsConfigPath = config.vcs_config_location;
+  console.log(`VCS config will be stored at: ${vcsConfigPath}`);
+
+  // Run VCS discovery if user opted in
+  if (config.run_vcs_discovery === true) {
+    console.log('Running VCS discovery...');
+    console.log('Please activate VCS Adapter agent and run: *discover');
+  } else {
+    console.log('VCS discovery skipped. Run later via VCS Adapter agent: *discover');
+  }
+
+  console.log('✅ BMVCS module installed successfully');
+  return true;
+}
+
+module.exports = { install };