From 8d342f3bd71728cea0a3301d8857b83f352ae3ac Mon Sep 17 00:00:00 2001 From: Serhii Date: Tue, 30 Sep 2025 19:57:25 +0300 Subject: [PATCH] feat(bmvcs): add VCS workflow templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add 5 VCS adaptation templates for different workflows: - git-github-flow.yaml: Simple feature branches (40% of users) - git-gitflow.yaml: Structured releases (20% of users) - git-trunk-based.yaml: Continuous deployment (15% of users) - no-vcs.yaml: Prototypes and one-time scripts (5% of users) - custom-generic.yaml: Custom/legacy VCS systems (10% of users) Templates support VCS-agnostic artifact generation across all BMAD agents. Part 2/5 of BMVCS migration (#661) Completes core VCS discovery functionality 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../vcs-adaptations/custom-generic.yaml | 117 ++++++++++++++++++ .../vcs-adaptations/git-gitflow.yaml | 77 ++++++++++++ .../vcs-adaptations/git-github-flow.yaml | 72 +++++++++++ .../vcs-adaptations/git-trunk-based.yaml | 99 +++++++++++++++ .../templates/vcs-adaptations/no-vcs.yaml | 107 ++++++++++++++++ 5 files changed, 472 insertions(+) create mode 100644 src/modules/bmvcs/templates/vcs-adaptations/custom-generic.yaml create mode 100644 src/modules/bmvcs/templates/vcs-adaptations/git-gitflow.yaml create mode 100644 src/modules/bmvcs/templates/vcs-adaptations/git-github-flow.yaml create mode 100644 src/modules/bmvcs/templates/vcs-adaptations/git-trunk-based.yaml create mode 100644 src/modules/bmvcs/templates/vcs-adaptations/no-vcs.yaml diff --git a/src/modules/bmvcs/templates/vcs-adaptations/custom-generic.yaml b/src/modules/bmvcs/templates/vcs-adaptations/custom-generic.yaml new file mode 100644 index 00000000..b3466a18 --- /dev/null +++ b/src/modules/bmvcs/templates/vcs-adaptations/custom-generic.yaml @@ -0,0 +1,117 @@ +# Custom/Generic VCS Template +# For ~10% of users - SVN, Perforce, custom workflows, complex setups + +name: Custom/Generic VCS +description: Adaptable template for non-standard version control systems +optimized_for: "Legacy systems, enterprise custom workflows, specialized VCS tools" + +discovery_required: + questions_to_ask: + - "What commands do you use to save changes?" + - "How do you mark versions or milestones?" + - "How do team members share code?" + - "What's your review process?" + - "Any specific naming conventions?" + +artifact_patterns: + architecture: + structure: "flexible" + format: | + - Ask: "What format works best with your system?" + - Default to markdown if no preference + - Avoid Git-specific terminology + terminology_mapping: + - instead_of: "branch" + use: "workspace/stream/variant" + - instead_of: "commit" + use: "changeset/submission/check-in" + - instead_of: "merge" + use: "integrate/incorporate/combine" + stories: + format: | + - Ask about existing story/task tracking + - Adapt to their terminology + - Focus on deliverables, not process + + code: + delivery: "aligned-to-vcs" + format: | + - Ask: "How should code changes be packaged?" + - Follow their existing patterns + - Document changes clearly + +agent_adaptations: + architect: + - Use VCS-neutral language + - Ask about their documentation standards + - Adapt diagrams to their tooling + + pm: + - Align with existing requirement formats + - Use their project terminology + - No assumptions about workflow + + sm: + - Match their task breakdown approach + - Use their status terminology + - Respect existing processes + + dev: + - Follow their code organization + - Match their change description format + - No Git-specific suggestions + + qa: + - Align with their testing workflow + - Use their defect tracking terms + - Respect existing procedures + +generic_terminology: + version_control_neutral: + - 'Use "Save changes" instead of "commit"' + - 'Use "Code variant" instead of "branch"' + - 'Use "Combine changes" instead of "merge"' + - 'Use "Change history" instead of "git log"' + - 'Use "Revert changes" instead of "git revert"' + +svn_specific: + if_detected: "Subversion/SVN" + adaptations: + - 'Use "revision" instead of "commit"' + - "Trunk/branches/tags structure" + - "Revision numbers, not hashes" + - '"svn update" before changes' + +perforce_specific: + if_detected: "Perforce" + adaptations: + - 'Use "changelist" instead of "commit"' + - "Workspace/depot terminology" + - "Client specs consideration" + - "Large binary file handling" + +adaptation_strategy: | + 1. Never assume - always ask + 2. Learn their terminology first + 3. Mirror their existing patterns + 4. Document in their style + 5. Deliver in their format + +example_interactions: + discovering_process: | + BMAD: "How do you typically save and share code changes?" + User: "We use Perforce with numbered changelists" + BMAD: "Got it! I'll use Perforce terminology. Should I organize + changes as separate changelists or group them?" + + adapting_output: | + Instead of: "Create a feature branch and commit changes" + Generate: "Create a workspace and submit a changelist" + +best_practices: + - "Listen more than suggest" + - "Use their language, not ours" + - "Ask when uncertain" + - "Document their process, don't change it" + - "Be flexible in output format" + - "Respect existing workflows" diff --git a/src/modules/bmvcs/templates/vcs-adaptations/git-gitflow.yaml b/src/modules/bmvcs/templates/vcs-adaptations/git-gitflow.yaml new file mode 100644 index 00000000..6ca9c6ee --- /dev/null +++ b/src/modules/bmvcs/templates/vcs-adaptations/git-gitflow.yaml @@ -0,0 +1,77 @@ +# Git GitFlow Adaptation Template +# For ~20% of users - versioned releases + +name: GitFlow +description: Structured branches with develop, release, and hotfix flows +optimized_for: "Desktop software, mobile apps, versioned APIs, scheduled releases" + +artifact_patterns: + architecture: + structure: "version-aligned" + location: "docs/architecture/" + format: | + - Main architecture in docs/architecture/ + - Version-specific changes in docs/releases/v{version}/ + - Comprehensive planning documents + + stories: + granularity: "medium" + size: "3-5 days of work" + format: | + - Stories grouped by release version + - Located in docs/releases/v{version}/stories/ + - Can span multiple commits in feature branch + + commits: + style: "descriptive" + branch_prefixes: + feature: "feature/" + release: "release/" + hotfix: "hotfix/" + bugfix: "bugfix/" + examples: + - "feature/user-auth: implement OAuth2 flow" + - "release/2.1.0: prepare release notes" + - "hotfix/critical-payment-bug: fix decimal handling" + +agent_adaptations: + architect: + - Generate comprehensive release-oriented architecture + - Include version migration guides + - Document breaking changes clearly + + pm: + - Create release-scoped PRDs + - Define features by target version + - Maintain product roadmap document + + sm: + - Group stories by release milestone + - Create epic-level organization + - Track story status across branches + + dev: + - Follow branch naming conventions strictly + - Include version tags in code comments + - Generate migration scripts when needed + + qa: + - Comprehensive test plans per release + - Regression test suites for versions + - Hotfix validation procedures + +version_management: + develop_branch: "Latest development work" + main_branch: "Production-ready releases only" + release_process: | + 1. Branch release/x.y.z from develop + 2. Fix bugs in release branch + 3. Merge to main and tag + 4. Merge back to develop + +best_practices: + - "Never commit directly to main" + - "Feature branches from develop, not main" + - "Hotfixes from main, merge to both main and develop" + - "Release branches for final preparations" + - "Semantic versioning (MAJOR.MINOR.PATCH)" diff --git a/src/modules/bmvcs/templates/vcs-adaptations/git-github-flow.yaml b/src/modules/bmvcs/templates/vcs-adaptations/git-github-flow.yaml new file mode 100644 index 00000000..5780d310 --- /dev/null +++ b/src/modules/bmvcs/templates/vcs-adaptations/git-github-flow.yaml @@ -0,0 +1,72 @@ +# Git GitHub Flow Adaptation Template +# For ~40% of users - the most common workflow + +name: GitHub Flow +description: Simple feature branches with pull requests +optimized_for: "Web applications, continuous deployment, small to medium teams" + +artifact_patterns: + architecture: + structure: "feature-aligned" + location: "docs/architecture/features/{feature-name}/" + format: | + - Main architecture in docs/architecture/README.md + - Feature additions in feature branches + - Lightweight, PR-friendly documents + + stories: + granularity: "small" + size: "1-3 days of work" + format: | + - One story per PR ideal + - Story file travels with code changes + - Located in docs/stories/{story-id}.md + + commits: + style: "conventional" + examples: + - "feat: add user authentication" + - "fix: resolve login timeout issue" + - "docs: update API documentation" + pr_description: | + ## What + Brief description of changes + + ## Why + Context from story: {story-id} + + ## Testing + - [ ] Unit tests pass + - [ ] Manual testing completed + +agent_adaptations: + architect: + - Generate lightweight, modular architecture docs + - Focus on changed components only + - Include "Impact Analysis" section for features + + pm: + - Create feature-scoped PRDs when needed + - Keep requirements atomic and PR-sized + + sm: + - Generate small, independent stories + - Each story should map to one PR + - Include acceptance criteria for PR review + + dev: + - Suggest feature branch names: feature/story-{id} + - Generate atomic commits + - Include PR template in first commit + + qa: + - Test plans per PR + - Focus on regression in changed areas + - Checklist format for PR reviews + +best_practices: + - "Keep PRs small - under 400 lines ideal" + - "One story = One PR when possible" + - "Branch from main, merge to main" + - "Delete branches after merge" + - "Deploy immediately after merge (if CI passes)" diff --git a/src/modules/bmvcs/templates/vcs-adaptations/git-trunk-based.yaml b/src/modules/bmvcs/templates/vcs-adaptations/git-trunk-based.yaml new file mode 100644 index 00000000..98d8c28a --- /dev/null +++ b/src/modules/bmvcs/templates/vcs-adaptations/git-trunk-based.yaml @@ -0,0 +1,99 @@ +# Git Trunk-Based Development Template +# For ~15% of users - mature CI/CD teams + +name: Trunk-Based Development +description: Direct commits or very short-lived branches to main +optimized_for: "Continuous deployment, mature DevOps teams, microservices" + +prerequisites: + required: + - "Comprehensive automated testing" + - "Feature flags system" + - "CI/CD pipeline with automatic rollback" + recommended: + - "Monitoring and alerting" + - "Blue-green or canary deployments" + +artifact_patterns: + architecture: + structure: "incrementally-evolving" + location: "docs/architecture/" + format: | + - Living documents that evolve with each change + - Feature flags documented inline + - ADRs (Architecture Decision Records) for changes + + stories: + granularity: "tiny" + size: "Hours to 1 day maximum" + format: | + - Ultra-small, immediately mergeable + - Flag-gated feature development + - Located in docs/stories/current/ + + commits: + style: "atomic" + frequency: "Multiple per day" + examples: + - "add user email validation behind flag:validate-email" + - "refactor payment service for performance" + - "enable feature flag:new-checkout-flow for 10% users" + flag_convention: "flag:{feature-name}" + +agent_adaptations: + architect: + - Design for feature flags from start + - Document flag dependencies + - Create rollback procedures + + pm: + - Define features as flag-gated increments + - Specify rollout percentages + - Create flag retirement timeline + + sm: + - Generate tiny, atomic stories + - Each story deployable behind flag + - Include flag configuration in story + + dev: + - Implement feature flags first + - Keep changes small and isolated + - Include flag cleanup tasks + - Commit directly or PR within hours + + qa: + - Test with flags on/off + - Automated test coverage mandatory + - Performance testing for each change + +feature_flags: + naming: "kebab-case-descriptive" + structure: | + { + "flag": "new-user-dashboard", + "description": "Redesigned dashboard for users", + "rollout": { + "dev": 100, + "staging": 100, + "production": 10 + }, + "expiry": "2024-Q2" + } + +ci_cd_requirements: + pipeline: | + 1. Automated tests (must pass) + 2. Security scanning + 3. Deploy to staging + 4. Smoke tests + 5. Deploy to production (behind flag) + 6. Progressive rollout + +best_practices: + - "Main branch always deployable" + - "No long-lived branches (max 24 hours)" + - "Feature flags for all new functionality" + - "Small, frequent commits" + - "Pair programming or immediate review" + - "Rollback is always an option" diff --git a/src/modules/bmvcs/templates/vcs-adaptations/no-vcs.yaml b/src/modules/bmvcs/templates/vcs-adaptations/no-vcs.yaml new file mode 100644 index 00000000..455dd6b4 --- /dev/null +++ b/src/modules/bmvcs/templates/vcs-adaptations/no-vcs.yaml @@ -0,0 +1,107 @@ +# No Version Control Template +# For ~5% of users - prototypes, one-time scripts, POCs + +name: No Version Control +description: Single deliverable packages without version tracking +optimized_for: "Prototypes, data migrations, one-time scripts, proof of concepts" + +artifact_patterns: + architecture: + structure: "monolithic" + location: "deliverables/" + format: | + - Single comprehensive document + - All requirements embedded + - Self-contained package + naming: "{project}_{type}_YYYYMMDD.md" + + stories: + granularity: "complete-features" + format: | + - All stories in one document + - Sequential implementation order + - No branching considerations + naming: "{project}_requirements_YYYYMMDD.md" + + code: + delivery: "complete-packages" + format: | + - All code in one deliverable + - Extensive inline comments + - Setup instructions included + naming: "{project}_complete_YYYYMMDD.zip" + +package_structure: + example: | + project_20240315/ + ├── README.md # Complete instructions + ├── requirements.txt # All dependencies + ├── src/ # All source code + │ └── main.py + ├── docs/ # All documentation + │ ├── architecture.md + │ └── requirements.md + ├── scripts/ # Setup/run scripts + │ └── setup.sh + └── tests/ # Test files if any + +agent_adaptations: + architect: + - Generate single, complete architecture document + - Include all diagrams inline (base64 or ASCII) + - No references to branches or versions + - Date-stamp all documents + + pm: + - Create comprehensive PRD upfront + - All requirements in one document + - Clear success criteria + + sm: + - Sequential story implementation plan + - Dependencies clearly mapped + - No parallel work assumptions + + dev: + - Generate complete, runnable code + - Extensive comments explaining logic + - No commit messages + - Include all necessary files + + qa: + - Single test plan document + - Manual test procedures + - No regression considerations + +documentation: + readme_template: | + # {Project Name} + Generated: {Date} + + ## Quick Start + 1. Extract all files + 2. Run setup script: ./scripts/setup.sh + 3. Execute: python src/main.py + + ## Requirements + - Python 3.8+ + - Dependencies in requirements.txt + + ## What This Does + {Clear description} + + ## File Descriptions + {List each file and its purpose} + + ## Notes + - This is a complete, self-contained package + - No version control required + - For questions, refer to docs/ + +best_practices: + - "Date-stamp everything" + - "Over-document rather than under-document" + - "Include all dependencies explicitly" + - "Test the complete package before delivery" + - "One ZIP/folder contains everything" + - "No external references"