feat(bmvcs): add VCS integration and BMM agent updates

Add VCS setup workflow and integrate with BMM agents:

BMVCS Workflows:
- workflows/setup-vcs/instructions.md: Comprehensive VCS discovery guide
  with auto-detection, clarifying questions, and edge case handling
- workflows/setup-vcs/checklist.md: Pre/during/post setup validation
- workflows/setup-vcs/workflow.yaml: Machine-readable workflow definition

BMM Agent Integration:
- architect.md: Added VCS-aware architecture documentation adaptation
- pm.md: Added VCS-aware requirements and release planning
- dev.md: Added VCS-aware code delivery and commit practices

Agents now check bmad-core/vcs-config.yaml and adapt their output to
the configured workflow (GitHub Flow, GitFlow, Trunk-Based, No VCS, etc.)
without imposing new processes on teams.

Part 5/5 of BMVCS migration (#661)
Completes VCS-agnostic module integration

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

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

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-core/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-core/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-core/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/workflows/setup-vcs/checklist.md

@@ -0,0 +1,183 @@
+# VCS Setup Workflow Checklist
+
+## Pre-Setup Checklist
+
+Run through these items **before** starting VCS configuration:
+
+### Environment Check
+
+- [ ] `.bmad-core/` directory exists or can be created
+- [ ] User has write permissions to project directory
+- [ ] If Git repo: Can run `git` commands
+
+### Information Gathering
+
+- [ ] Understand project type (prototype, production, migration, etc.)
+- [ ] Know team size (solo, small team, large team)
+- [ ] Know release frequency (daily, weekly, monthly, quarterly)
+- [ ] Know if multiple versions need maintenance
+
+### Existing Configuration
+
+- [ ] Check if `.bmad-core/vcs-config.yaml` exists
+- [ ] If exists: Check if valid (< 7 days old)
+- [ ] If exists: Ask user if still accurate
+
+## During Setup Checklist
+
+Follow these during the VCS discovery workflow:
+
+### Detection Phase (Git only)
+
+- [ ] Attempt auto-detection if Git repository
+- [ ] Calculate confidence score
+- [ ] Present evidence if confidence >= 70%
+- [ ] Skip to manual selection if confidence < 70%
+
+### Discovery Phase
+
+- [ ] Ask initial VCS question
+- [ ] Branch based on response (Git, Other VCS, No VCS, Custom)
+- [ ] If Git: Ask workflow question
+- [ ] If "Not sure": Ask clarifying questions
+- [ ] If Custom: Request detailed description
+
+### Confirmation Phase
+
+- [ ] Present detected or selected workflow
+- [ ] Show adaptations that will be applied
+- [ ] Get explicit user confirmation
+- [ ] Handle edge cases (migration, unclear, fresh repo)
+
+### Configuration Phase
+
+- [ ] Create `.bmad-core/` directory if needed
+- [ ] Write `vcs-config.yaml` with correct format
+- [ ] Set cache validity (7 days from now)
+- [ ] Record detection method and confidence
+
+## Post-Setup Checklist
+
+Verify setup completion:
+
+### Configuration Verification
+
+- [ ] `.bmad-core/vcs-config.yaml` exists
+- [ ] File contains valid YAML
+- [ ] `type` field is set correctly
+- [ ] `workflow` field is set correctly
+- [ ] `cache_valid_until` is set to future date
+
+### User Confirmation
+
+- [ ] Show success message to user
+- [ ] Display configured workflow
+- [ ] Explain agent adaptations
+- [ ] Provide instructions for updating config later
+
+### Agent Integration
+
+- [ ] Architect agent can read VCS config
+- [ ] PM agent can read VCS config
+- [ ] SM agent can read VCS config
+- [ ] Dev agent can read VCS config
+- [ ] QA agent can read VCS config
+
+### Documentation
+
+- [ ] User knows how to view configuration
+- [ ] User knows how to update configuration
+- [ ] User knows when cache expires (7 days)
+- [ ] User knows how to trigger re-detection
+
+## Validation Checklist
+
+Ensure configuration quality:
+
+### Content Validation
+
+- [ ] VCS type is one of: `git`, `svn`, `perforce`, `mercurial`, `tfs`, `none`, `custom`
+- [ ] Workflow (if Git) is one of: `github-flow`, `gitflow`, `trunk-based`, `custom`, `none`
+- [ ] Details field populated if custom/complex setup
+- [ ] Adaptations section includes: `artifact_format`, `terminology`, `commit_style`
+
+### Logic Validation
+
+- [ ] If type=`none`, workflow should be `none`
+- [ ] If type=`git`, workflow should not be `none`
+- [ ] If workflow=`custom`, details field should be populated
+- [ ] If auto-detected, confidence_score should exist
+
+### Timestamp Validation
+
+- [ ] `configured_at` is valid ISO 8601 timestamp
+- [ ] `cache_valid_until` is 7 days after `configured_at`
+- [ ] Both timestamps are in UTC
+
+## Troubleshooting Checklist
+
+If issues occur:
+
+### Detection Issues
+
+- [ ] **Low confidence**: Fall back to manual selection
+- [ ] **Fresh repo**: Skip detection, use manual selection
+- [ ] **Migration detected**: Ask user which workflow to use
+- [ ] **Non-Git repo**: Skip detection, ask for VCS type
+
+### Configuration Issues
+
+- [ ] **Write fails**: Use in-memory config, warn user
+- [ ] **Invalid YAML**: Re-create with default values
+- [ ] **Missing directory**: Create `.bmad-core/` automatically
+- [ ] **Permission denied**: Instruct user to fix permissions
+
+### User Confusion
+
+- [ ] **Unclear options**: Provide more detailed descriptions
+- [ ] **Not sure**: Trigger clarifying questions
+- [ ] **Complex setup**: Allow free-text description
+- [ ] **Multiple VCS**: Ask component-specific questions
+
+## Re-Configuration Checklist
+
+When updating existing configuration:
+
+### Trigger Scenarios
+
+- [ ] User explicitly requests change
+- [ ] Cache expired (>7 days old)
+- [ ] Detected workflow change (migration)
+- [ ] Configuration file corrupted/invalid
+
+### Update Process
+
+- [ ] Show current configuration
+- [ ] Ask reason for update
+- [ ] Run through discovery again (faster path)
+- [ ] Preserve user's custom details if applicable
+- [ ] Update timestamps
+
+### Verification
+
+- [ ] New configuration saved
+- [ ] Old configuration backed up (optional)
+- [ ] All agents recognize new configuration
+- [ ] User confirmed update
+
+## Success Criteria
+
+Setup is complete when:
+
+- ✅ Configuration file exists and valid
+- ✅ User confirmed workflow selection
+- ✅ All agents can read configuration
+- ✅ User understands adaptations
+- ✅ Cache expiry set correctly
+- ✅ No errors or warnings
+
+## Related Files
+
+- [Instructions](./instructions.md) - Detailed workflow steps
+- [Workflow Definition](./workflow.yaml) - Machine-readable workflow
+- [Discovery Task](../../tasks/discover-vcs.md) - Implementation details

src/modules/bmvcs/workflows/setup-vcs/instructions.md

@@ -0,0 +1,311 @@
+# VCS Setup Workflow Instructions
+
+## Purpose
+
+Guide users through VCS discovery and configuration at project initialization, ensuring BMAD adapts to their version control practices.
+
+## When to Use
+
+- New project initialization with BMAD
+- First-time BMAD user in existing project
+- Team changing VCS workflows
+- VCS configuration missing or outdated
+
+## Workflow Overview
+
+```
+1. Detect existing VCS → 2. Discovery questions → 3. Confirm workflow → 4. Save configuration
+```
+
+## Step-by-Step Instructions
+
+### Step 1: Check Existing Configuration
+
+**Action:** Look for `.bmad-core/vcs-config.yaml`
+
+**If exists and valid (<7 days old):**
+
+```yaml
+action: confirm_existing
+prompt: |
+  Found existing VCS configuration:
+  - System: {type}
+  - Workflow: {workflow}
+
+  Is this still accurate? (Yes/No)
+```
+
+**If No or missing:** Proceed to Step 2
+
+### Step 2: Auto-Detection (Optional)
+
+**For Git repositories only:**
+
+```yaml
+action: attempt_detection
+method: analyze_history
+confidence_threshold: 0.7
+
+if_high_confidence:
+  present:
+    - Detected workflow with evidence
+    - Ask for confirmation
+
+if_low_confidence:
+  skip_to: manual_discovery
+```
+
+**Detection analyzes:**
+
+- Branch patterns (develop, release/\*, hotfix/\*)
+- Commit messages (PR merges, squash patterns)
+- Tag patterns (version tags)
+- Commit frequency to main branch
+- Feature flag mentions
+
+**Present results:**
+
+```
+🔍 Analyzed your Git history...
+
+Detected workflow: GitHub Flow
+Confidence: 85%
+
+Evidence:
+✓ Found 23 PR merges in last 90 days
+✓ Using feature branch naming
+✓ No develop branch (GitHub Flow indicator)
+
+Is this correct?
+1. Yes, that's right
+2. No, we actually use something else
+3. We recently changed our approach
+```
+
+### Step 3: Discovery Questions
+
+**Initial Question:**
+
+```yaml
+question: 'How does your team manage code versions?'
+options:
+  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'
+```
+
+#### Path 3A: Git-Based Workflows (Options 1-2)
+
+```yaml
+question: 'Which Git workflow best describes your approach?'
+options:
+  1:
+    name: 'GitHub Flow'
+    description: 'Simple feature branches with pull requests'
+    best_for: 'Web apps, continuous deployment'
+
+  2:
+    name: 'GitFlow'
+    description: 'Structured branches (develop, release, hotfix)'
+    best_for: 'Versioned software, scheduled releases'
+
+  3:
+    name: 'Trunk-Based'
+    description: 'Direct commits or very short branches'
+    best_for: 'Mature CI/CD, experienced teams'
+
+  4:
+    name: 'Not sure'
+    action: 'trigger_clarifying_questions'
+
+  5:
+    name: 'Custom Git workflow'
+    action: 'request_description'
+```
+
+**If "Not sure":**
+
+```yaml
+clarifying_questions:
+  q1:
+    question: 'How many developers on your team?'
+    options: ['1', '2-5', '6+']
+    scoring:
+      '1': { trunk_based: +0.3 }
+      '2-5': { github_flow: +0.2 }
+      '6+': { gitflow: +0.2 }
+
+  q2:
+    question: 'How often do you release?'
+    options: ['Daily', 'Weekly', 'Monthly', 'Quarterly']
+    scoring:
+      'Daily': { trunk_based: +0.3 }
+      'Weekly': { github_flow: +0.3 }
+      'Monthly': { gitflow: +0.3 }
+      'Quarterly': { gitflow: +0.3 }
+
+  q3:
+    question: 'Do you have automated testing?'
+    options: ['Yes', 'No']
+    scoring:
+      'Yes': { trunk_based: +0.2 }
+
+  q4:
+    question: 'Do you maintain multiple versions?'
+    options: ['Yes', 'No']
+    scoring:
+      'Yes': { gitflow: +0.4 }
+
+recommendation: 'Based on your answers, we suggest: {highest_score}'
+```
+
+#### Path 3B: Other VCS (Option 3)
+
+```yaml
+question: 'Which version control system do you use?'
+options:
+  1: 'Subversion (SVN)'
+  2: 'Perforce'
+  3: 'Mercurial'
+  4: 'Team Foundation Server (TFS)'
+  5: 'Other (please specify)'
+```
+
+#### Path 3C: No VCS (Option 4)
+
+```yaml
+confirm: |
+  Understood. BMAD will generate:
+  - Self-contained deliverables
+  - Date-versioned packages
+  - No commit messages or branch references
+
+question: 'Is this a prototype or one-time project?'
+action: 'Save configuration with type=none'
+```
+
+#### Path 3D: Custom/Complex (Option 5)
+
+```yaml
+prompt: |
+  Please describe your version control setup:
+  (e.g., "Monorepo with custom tooling", "Multiple systems for different components")
+
+action: 'free_text_input'
+follow_up: 'Ask component-specific questions if multi-VCS'
+```
+
+### Step 4: Save Configuration
+
+**Create `.bmad-core/vcs-config.yaml`:**
+
+```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|svn|generic|custom
+    commit_style: conventional|team-specific|none
+
+  metadata:
+    configured_at: '2024-09-30T12:00:00Z'
+    method: auto-detected|user-selected|recommended
+    confidence_score: 0.85 # if auto-detected
+    cache_valid_until: '2024-10-07T12:00:00Z'
+```
+
+**Confirm to user:**
+
+```
+✅ VCS Configuration Saved!
+
+System: Git
+Workflow: GitHub Flow
+Adaptations: Small PRs, feature branches, conventional commits
+
+All BMAD agents will now adapt to your workflow:
+- Architect: Lightweight, PR-sized architecture docs
+- PM: Feature-scoped requirements
+- SM: Small stories mapping to single PRs
+- Dev: Feature branch suggestions, atomic commits
+- QA: PR-focused test plans
+```
+
+## Edge Cases
+
+### Migration Detected
+
+```yaml
+if: recent_pattern != historical_pattern
+action: |
+  📊 Note: Detected a possible workflow change
+  Recent: GitHub Flow-like
+  Historical: GitFlow-like
+
+  Which should BMAD optimize for?
+  1. New approach (migration complete)
+  2. Old approach (recent was exceptional)
+  3. Both (still transitioning)
+```
+
+### Fresh Repository (<10 commits)
+
+```yaml
+if: commit_count < 10
+action: skip_detection
+message: 'Repository too new for reliable detection'
+default_to: manual_selection
+```
+
+### Non-Git Repository
+
+```yaml
+if: not is_git_repo()
+action: skip_detection
+prompt: 'What version control system do you use?'
+options: [SVN, Perforce, Mercurial, TFS, None, Other]
+```
+
+## Success Criteria
+
+- ✅ Configuration saved in `.bmad-core/vcs-config.yaml`
+- ✅ User confirmed workflow selection
+- ✅ No Git assumptions for non-Git users
+- ✅ Graceful handling of unclear cases
+- ✅ Cache validity set (7 days)
+
+## Error Handling
+
+### Detection Fails
+
+```yaml
+fallback: manual_selection
+message: "Could not analyze repository. Let's select manually."
+```
+
+### Invalid Selection
+
+```yaml
+action: re-prompt
+validation: 'Please select a valid option (1-5)'
+```
+
+### Configuration Write Fails
+
+```yaml
+fallback: in_memory_config
+warning: 'Could not save configuration. Will use for this session only.'
+action: suggest_manual_save
+```
+
+## Related Files
+
+- [Checklist](./checklist.md) - Pre/post setup checklist
+- [Workflow Definition](./workflow.yaml) - Machine-readable workflow
+- [Discovery Task](../../tasks/discover-vcs.md) - Discovery implementation
+- [Detection Confidence](../../docs/VCS_DETECTION_CONFIDENCE.md) - Detection algorithms

src/modules/bmvcs/workflows/setup-vcs/workflow.yaml

@@ -0,0 +1,298 @@
+# VCS Setup Workflow
+# Machine-readable workflow definition for BMAD agents
+
+name: VCS Discovery and Configuration
+version: 1.0.0
+type: initialization
+category: system_configuration
+
+trigger:
+  events:
+    - project_initialization
+    - vcs_config_missing
+    - vcs_config_expired
+    - user_request_reconfigure
+
+prerequisites:
+  required:
+    - bmad_core_accessible: true
+    - write_permissions: true
+  optional:
+    - git_available: false # Only needed for auto-detection
+
+steps:
+  - id: check_existing_config
+    type: conditional
+    action: check_file_exists
+    file: .bmad-core/vcs-config.yaml
+    on_exists: validate_config
+    on_missing: proceed_to_detection
+
+  - id: validate_config
+    type: validation
+    checks:
+      - cache_expired: check_timestamp
+      - valid_yaml: parse_yaml
+    on_valid: confirm_existing
+    on_invalid: proceed_to_detection
+
+  - id: confirm_existing
+    type: user_prompt
+    message: |
+      Found existing VCS configuration:
+      - System: {{type}}
+      - Workflow: {{workflow}}
+
+      Is this still accurate?
+    options:
+      - value: yes
+        action: exit_workflow
+      - value: no
+        action: proceed_to_detection
+
+  - id: proceed_to_detection
+    type: conditional
+    condition: is_git_repo AND git_available
+    on_true: attempt_auto_detection
+    on_false: manual_discovery
+
+  - id: attempt_auto_detection
+    type: detection
+    method: analyze_git_history
+    confidence_threshold: 0.7
+    on_high_confidence: present_detection
+    on_low_confidence: manual_discovery
+
+  - id: present_detection
+    type: user_prompt
+    message: |
+      🔍 Detected workflow: {{workflow}} ({{confidence}}% confidence)
+
+      Evidence:
+      {{#evidence}}
+      ✓ {{.}}
+      {{/evidence}}
+
+      Is this correct?
+    options:
+      - value: yes
+        action: save_configuration
+      - value: no
+        action: manual_discovery
+      - value: migration
+        action: handle_migration
+
+  - id: manual_discovery
+    type: user_prompt
+    message: "How does your team manage code versions?"
+    options:
+      - value: git_github
+        label: "Git with GitHub/GitLab/Bitbucket [MOST COMMON]"
+        action: git_workflow_selection
+      - value: git_corporate
+        label: "Git with corporate server"
+        action: git_workflow_selection
+      - value: other_vcs
+        label: "Other version control system"
+        action: other_vcs_selection
+      - value: no_vcs
+        label: "No version control needed"
+        action: configure_no_vcs
+      - value: custom_complex
+        label: "Custom/Complex setup"
+        action: custom_description
+
+  - id: git_workflow_selection
+    type: user_prompt
+    message: "Which Git workflow best describes your approach?"
+    options:
+      - value: github_flow
+        label: "GitHub Flow - Simple feature branches"
+        metadata:
+          workflow: github-flow
+          best_for: "Web apps, continuous deployment"
+        action: save_configuration
+      - value: gitflow
+        label: "GitFlow - Structured branches (develop, release, hotfix)"
+        metadata:
+          workflow: gitflow
+          best_for: "Versioned software, scheduled releases"
+        action: save_configuration
+      - value: trunk_based
+        label: "Trunk-Based - Direct commits or very short branches"
+        metadata:
+          workflow: trunk-based
+          best_for: "Mature CI/CD, experienced teams"
+        action: save_configuration
+      - value: not_sure
+        label: "Not sure - I'd like a recommendation"
+        action: clarifying_questions
+      - value: custom
+        label: "Custom Git workflow"
+        action: custom_description
+
+  - id: clarifying_questions
+    type: questionnaire
+    questions:
+      - id: team_size
+        text: "How many developers on your team?"
+        options:
+          - value: "1"
+            scoring: { trunk_based: 0.3 }
+          - value: "2-5"
+            scoring: { github_flow: 0.2 }
+          - value: "6+"
+            scoring: { gitflow: 0.2 }
+
+      - id: release_frequency
+        text: "How often do you release?"
+        options:
+          - value: daily
+            scoring: { trunk_based: 0.3 }
+          - value: weekly
+            scoring: { github_flow: 0.3 }
+          - value: monthly
+            scoring: { gitflow: 0.3 }
+
+      - id: multiple_versions
+        text: "Do you maintain multiple versions?"
+        options:
+          - value: yes
+            scoring: { gitflow: 0.4 }
+          - value: no
+            scoring: { github_flow: 0.2, trunk_based: 0.2 }
+
+    action: recommend_workflow
+
+  - id: recommend_workflow
+    type: calculation
+    method: sum_scores
+    output: recommended_workflow
+    action: present_recommendation
+
+  - id: present_recommendation
+    type: user_prompt
+    message: "Based on your answers, we recommend: {{recommended_workflow}}"
+    action: save_configuration
+
+  - id: other_vcs_selection
+    type: user_prompt
+    message: "Which version control system do you use?"
+    options:
+      - value: svn
+        label: "Subversion (SVN)"
+      - value: perforce
+        label: "Perforce"
+      - value: mercurial
+        label: "Mercurial"
+      - value: tfs
+        label: "Team Foundation Server (TFS)"
+      - value: other
+        label: "Other (please specify)"
+    action: save_configuration
+
+  - id: configure_no_vcs
+    type: user_prompt
+    message: |
+      Understood. BMAD will generate:
+      - Self-contained deliverables
+      - Date-versioned packages
+      - No commit messages or branch references
+
+      Is this a prototype or one-time project?
+    options:
+      - value: yes
+        action: save_configuration
+      - value: no
+        action: save_configuration
+
+  - id: custom_description
+    type: user_input
+    message: |
+      Please describe your version control setup:
+      (e.g., "Monorepo with custom tooling", "Multiple systems for different components")
+    input_type: text
+    action: save_configuration
+
+  - id: handle_migration
+    type: user_prompt
+    message: |
+      📊 Detected possible workflow change.
+      Which should BMAD optimize for?
+    options:
+      - value: new
+        label: "New approach (migration complete)"
+      - value: old
+        label: "Old approach (recent was exceptional)"
+      - value: both
+        label: "Both (still transitioning)"
+    action: save_configuration
+
+  - id: save_configuration
+    type: file_write
+    file: .bmad-core/vcs-config.yaml
+    template: |
+      vcs_config:
+        type: {{type}}
+        workflow: {{workflow}}
+        details: {{details}}
+
+        adaptations:
+          artifact_format: {{artifact_format}}
+          terminology: {{terminology}}
+          commit_style: {{commit_style}}
+
+        metadata:
+          configured_at: {{timestamp}}
+          method: {{method}}
+          confidence_score: {{confidence}}
+          cache_valid_until: {{cache_expiry}}
+
+    on_success: show_confirmation
+    on_error: handle_save_error
+
+  - id: show_confirmation
+    type: notification
+    message: |
+      ✅ VCS Configuration Saved!
+
+      System: {{type}}
+      Workflow: {{workflow}}
+
+      All BMAD agents will adapt to your workflow.
+    action: exit_workflow
+
+  - id: handle_save_error
+    type: error_handler
+    fallback: in_memory_config
+    message: |
+      ⚠️  Could not save configuration to file.
+      Will use configuration for this session only.
+
+outputs:
+  vcs_config:
+    type: object
+    location: .bmad-core/vcs-config.yaml
+    schema: VCS_CONFIG_SCHEMA_V1
+    cache_duration: 604800 # 7 days in seconds
+
+error_handling:
+  detection_fails:
+    action: fallback_to_manual
+    log_level: info
+
+  invalid_selection:
+    action: re_prompt
+    message: "Please select a valid option"
+
+  write_fails:
+    action: use_in_memory
+    warning: "Configuration not persisted"
+
+metadata:
+  author: BMAD BMVCS Module
+  documentation: ./instructions.md
+  checklist: ./checklist.md
+  related_tasks:
+    - ../../tasks/discover-vcs.md
+    - ../../tasks/validate-vcs-config.md