diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml index 8269c03c64..877ba904ec 100644 --- a/.github/workflows/manual-release.yaml +++ b/.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 diff --git a/.gitignore b/.gitignore index 547e9e5a4c..e29148ed4a 100644 --- a/.gitignore +++ b/.gitignore @@ -57,3 +57,6 @@ tools/template-test-generator/test-scenarios/ # Test Install Output z*/ + +# BMVCS Migration Planning (local only) +.bmvcs-migration/ diff --git a/src/modules/bmm/agents/architect.md b/src/modules/bmm/agents/architect.md index cba52b4acb..1b244c3392 100644 --- a/src/modules/bmm/agents/architect.md +++ b/src/modules/bmm/agents/architect.md @@ -8,12 +8,13 @@ System Architect + Technical Design Leader 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. 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. - 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 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. Load into memory {project-root}/bmad/bmm/config.yaml and set variable project_name, output_folder, user_name, communication_language Remember the users name is {user_name} ALWAYS communicate in {communication_language} + 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. diff --git a/src/modules/bmm/agents/dev.md b/src/modules/bmm/agents/dev.md index c736f83f68..1da25f2988 100644 --- a/src/modules/bmm/agents/dev.md +++ b/src/modules/bmm/agents/dev.md @@ -8,7 +8,7 @@ Senior Implementation Engineer Executes approved stories with strict adherence to acceptance criteria, using the Story Context JSON and existing code to minimize rework and hallucinations. Succinct, checklist-driven, cites paths and AC IDs; asks only when inputs are missing or ambiguous. - 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 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. @@ -19,6 +19,7 @@ Pin the loaded Story Context into active memory for the whole session; treat it as AUTHORITATIVE over any model priors 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). ALWAYS communicate in {communication_language} + 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. diff --git a/src/modules/bmm/agents/pm.md b/src/modules/bmm/agents/pm.md index 9b5e90f2b5..127ce366ce 100644 --- a/src/modules/bmm/agents/pm.md +++ b/src/modules/bmm/agents/pm.md @@ -8,12 +8,13 @@ Investigative Product Strategist + Market-Savvy PM 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. 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. - 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 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. Load into memory {project-root}/bmad/bmm/config.yaml and set variable project_name, output_folder, user_name, communication_language Remember the users name is {user_name} ALWAYS communicate in {communication_language} + 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. Show numbered cmd list diff --git a/src/modules/bmvcs/README.md b/src/modules/bmvcs/README.md new file mode 100644 index 0000000000..67e658cf11 --- /dev/null +++ b/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:** +- **Issue Tracker:** +- **Discord:** + +--- + +**Version:** 6.0.0-alpha +**Status:** In Development +**Module Code:** `bmvcs` diff --git a/src/modules/bmvcs/_module-installer/install-menu-config.yaml b/src/modules/bmvcs/_module-installer/install-menu-config.yaml new file mode 100644 index 0000000000..17b2ed9a00 --- /dev/null +++ b/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 diff --git a/src/modules/bmvcs/_module-installer/installer.js b/src/modules/bmvcs/_module-installer/installer.js new file mode 100644 index 0000000000..17b55c3633 --- /dev/null +++ b/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 }; diff --git a/src/modules/bmvcs/agents/vcs-adapter.md b/src/modules/bmvcs/agents/vcs-adapter.md new file mode 100644 index 0000000000..674c1b05b5 --- /dev/null +++ b/src/modules/bmvcs/agents/vcs-adapter.md @@ -0,0 +1,108 @@ +# VCS Adapter Agent + + + + + + Version Control Integration Specialist + Adapts BMAD workflows to team's version control practices + Clear, methodical, and VCS-aware + +

Respect existing workflows - never force change

+

Discover before assuming - ask about VCS setup

+

Adapt language to context - use team's terminology

+

Work with what exists - enhance, don't replace

+ + + + + Load into memory {project-root}/bmad/bmvcs/config.yaml if exists + Check for existing VCS configuration at {vcs_config_location} + ALWAYS communicate in {communication_language} + + + + Show numbered command list + Run VCS discovery to detect version control system + Display current VCS configuration + Adapt a document to team's VCS workflow + Validate VCS configuration file + Exit with confirmation + + + + + discover-vcs.md + create-vcs-adapted-doc.md + validate-vcs-config.md + + + 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 + + + + + STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition + STEP 2: Adopt the persona defined in the 'persona' section above + STEP 3: Check if VCS configuration exists, if not offer to run discovery + STEP 4: Greet user with your name/role and immediately run *help + DO NOT: Load any other agent files during activation + ONLY load dependency files when user selects them for execution + + + + Optimize for the majority (Git ~85-90%), open to all + Discover before assumption - never assume Git + Respect "no VCS" as valid choice + Adapt language: Git users get "commit/branch", SVN gets "revision/trunk" + Structure follows function: GitHub Flow = small artifacts, No VCS = monolithic packages + + + + VCS_AGNOSTIC_PRINCIPLES.md + VCS_AGNOSTIC_PROPOSAL.md + VCS_DETECTION_CONFIDENCE.md + + + +## Agent Description + +The VCS Adapter makes BMAD truly universal by adapting to any version control system. Instead of forcing teams to change their workflows, this agent discovers their existing practices and adjusts BMAD's output accordingly. + +### Supported VCS Types + +- **Git workflows:** GitHub Flow, GitFlow, Trunk-Based Development +- **Other VCS:** Subversion (SVN), Perforce, Mercurial, TFS +- **No VCS:** Self-contained deliverables with date versioning +- **Custom:** Team-specific workflows + +### Key Capabilities + +1. **Discovery:** Detects VCS type and workflow through interactive prompts +2. **Adaptation:** Adjusts documentation, terminology, and artifact structure +3. **Validation:** Ensures VCS configuration is correct and consistent +4. **Integration:** Works with BMM agents for VCS-aware planning + +### Usage Example + +``` +User: *discover +Agent: Runs VCS discovery workflow, saves configuration + +User: *adapt-doc architecture.md +Agent: Adapts architecture document to team's Git workflow +``` + +## Integration with BMM + +This agent can be used standalone or integrated with BMM agents: + +- **Architect**: VCS-adapted architecture documents +- **PM**: VCS-aware project planning +- **Dev**: VCS-adapted commit messages and workflow + +Integration is **optional** - BMVCS works independently. diff --git a/src/modules/bmvcs/docs/README.md b/src/modules/bmvcs/docs/README.md new file mode 100644 index 0000000000..948b0e19d9 --- /dev/null +++ b/src/modules/bmvcs/docs/README.md @@ -0,0 +1,76 @@ +# BMVCS Documentation + +Version Control System (VCS) Agnostic Module for BMAD-METHOD + +## Overview + +BMVCS enables BMAD agents to adapt to any version control system - from Git workflows to SVN, Perforce, or even no VCS at all. + +## Core Documents + +### [VCS_AGNOSTIC_PRINCIPLES.md](./VCS_AGNOSTIC_PRINCIPLES.md) + +The foundational philosophy: "Optimized for the majority, open to all" + +- 10 core principles for VCS adaptation +- Implementation guidelines for agent developers +- Configuration storage and testing + +### [VCS_AGNOSTIC_PROPOSAL.md](./VCS_AGNOSTIC_PROPOSAL.md) + +The practical implementation approach: "BMAD Suggests, User Decides" + +- VCS discovery protocol +- Agent behavioral adaptations +- Example interactions and scenarios + +### [VCS_DETECTION_CONFIDENCE.md](./VCS_DETECTION_CONFIDENCE.md) + +Auto-detection confidence scoring: "Detection as a HINT, not a DECISION" + +- Workflow detection algorithms +- Confidence score calculation +- Edge cases and migration handling + +## Quick Start + +1. **Discovery**: BMAD asks about your VCS at project start +2. **Adaptation**: All agents adapt their output to your workflow +3. **Flexibility**: Change VCS settings anytime via configuration + +## Philosophy + +BMAD adapts to teams' existing version control practices rather than imposing new ones: + +- ~85-90% use Git β†’ Quick-pick Git workflows +- ~10-15% use other systems β†’ Full support with appropriate terminology +- No VCS needed β†’ Self-contained deliverables + +## Key Features + +- **No Assumptions**: Never assumes Git or any specific VCS +- **Terminology Adaptation**: Uses your VCS language (commit/changelist/revision) +- **Workflow Respect**: Honors existing team processes +- **Progressive Disclosure**: Simple for common cases, flexible for edge cases + +## Integration + +BMVCS integrates with all BMAD agents: + +- **Architect**: VCS-adapted architecture documents +- **PM**: VCS-appropriate requirements +- **SM**: Stories sized for your workflow +- **Dev**: Code delivery matching your VCS +- **QA**: Test plans aligned with your process + +## Configuration + +VCS settings stored in `.bmad-core/vcs-config.yaml` + +See [VCS_AGNOSTIC_PRINCIPLES.md](./VCS_AGNOSTIC_PRINCIPLES.md#configuration-storage) for details. + +## Related + +- [Module README](../README.md) - BMVCS module overview +- [Discovery Task](../tasks/discover-vcs.md) - VCS discovery implementation +- [VCS Templates](../templates/vcs-adaptations/) - Workflow adaptation templates diff --git a/src/modules/bmvcs/docs/VCS_AGNOSTIC_PRINCIPLES.md b/src/modules/bmvcs/docs/VCS_AGNOSTIC_PRINCIPLES.md new file mode 100644 index 0000000000..7f21aeb05c --- /dev/null +++ b/src/modules/bmvcs/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.** diff --git a/src/modules/bmvcs/docs/VCS_AGNOSTIC_PROPOSAL.md b/src/modules/bmvcs/docs/VCS_AGNOSTIC_PROPOSAL.md new file mode 100644 index 0000000000..9c787b8d3a --- /dev/null +++ b/src/modules/bmvcs/docs/VCS_AGNOSTIC_PROPOSAL.md @@ -0,0 +1,186 @@ +# VCS-Agnostic Approach for BMAD-METHOD + +## Core Philosophy: "BMAD Suggests, User Decides" + +### Executive Summary + +BMAD should adapt to existing team practices rather than impose specific version control strategies. This proposal outlines a flexible, discovery-based approach to VCS integration. + +## The Problem with Current Assumptions + +Current BMAD and the Gemini analysis document assume: + +- All projects use Git +- Teams need "best practice" workflows +- Version control strategy is primarily technical + +Reality: + +- Many teams have unique, working systems +- Some projects don't need VCS at all +- VCS choice is often organizational/political, not technical + +## Proposed Solution: VCS Discovery Protocol + +### 1. Initial Discovery Question + +```yaml +vcs_discovery: + initial_question: 'How does your team manage code versions?' + + response_paths: + established_system: + - 'We have our own system that works' + - BMAD: 'Great! Tell me about it so I can adapt' + + no_vcs: + - "We don't use version control" + - BMAD: "Understood. I'll generate self-contained packages" + + need_guidance: + - 'We need recommendations' + - BMAD: 'Let me understand your context first...' +``` + +### 2. Adaptation Matrix + +| User Response | BMAD Adaptation | +| --------------------------- | ----------------------------------------------------- | +| "Custom Git workflow" | Agents use generic Git terms, no strategy assumptions | +| "No VCS (prototype)" | Single deliverable packages with date versioning | +| "Platform VCS (Salesforce)" | Platform-specific artifacts and terminology | +| "Legacy system (SVN)" | VCS-agnostic artifacts, no Git-specific features | +| "It's complicated..." | Free-form description, custom adaptation | + +### 3. Agent Behavioral Adaptations + +#### Architect Agent + +```yaml +vcs_adaptations: + no_vcs: + - Generate monolithic architecture document + - Include all specs in single package + - Version via: PROJECTNAME_ARCH_YYYYMMDD.md + + custom_vcs: + - Ask: 'What format works with your system?' + - Avoid Git-specific terminology + - Focus on deliverables, not process +``` + +#### Developer Agent + +```yaml +vcs_adaptations: + no_vcs: + - Generate complete code blocks + - No commit message suggestions + - Package as: FEATURE_COMPLETE_YYYYMMDD.zip + + custom_vcs: + - Ask: 'How should I structure code changes?' + - Follow team's existing patterns +``` + +#### SM Agent + +```yaml +vcs_adaptations: + no_vcs: + - Create comprehensive story documents + - Include all context in each story + + git_based: + - Option to create branch-scoped stories + - But only if team requests it +``` + +## Implementation Steps + +### Phase 1: Discovery Mechanism + +Create `bmad-core/tasks/discover-vcs.md`: + +- Non-assumptive questions +- Multiple response paths +- Custom description option + +### Phase 2: Adaptation Templates + +Create `bmad-core/templates/vcs-adaptations/`: + +- `no-vcs.yaml` +- `git-agnostic.yaml` +- `platform-specific.yaml` +- `custom-adapter.yaml` + +### Phase 3: Agent Updates + +Modify each agent to: + +1. Check VCS context before generating artifacts +2. Adapt output format based on VCS choice +3. Never assume Git unless confirmed + +## Key Principles + +1. **No Assumptions**: Never assume Git or any specific VCS +2. **Respect Existing**: Honor teams' current working systems +3. **Adapt, Don't Educate**: We adapt to them, not vice versa +4. **Suggest When Asked**: Only provide recommendations when requested +5. **Custom is Valid**: "Our own way" is a perfectly valid answer + +## Example Interactions + +### Scenario 1: Team with Custom Process + +``` +BMAD: "How does your team manage code versions?" +User: "We use Git but with our own branching model based on features and environments" +BMAD: "Perfect! I'll adapt to your model. Could you briefly describe when code moves between environments?" +User: [describes their process] +BMAD: "Got it. I'll structure artifacts to align with your featureβ†’environment flow" +``` + +### Scenario 2: No VCS Needed + +``` +BMAD: "How does your team manage code versions?" +User: "This is a one-time data migration script, no versioning needed" +BMAD: "Understood. I'll generate a single, complete package with clear documentation" +``` + +### Scenario 3: Guidance Requested + +``` +BMAD: "How does your team manage code versions?" +User: "We're not sure, what do you recommend?" +BMAD: "Let me understand your context first: +- How many developers? +- How often do you release? +- Is this a new project or existing codebase?" +[After answers] +BMAD: "Based on your context, here are 2 options that could work..." +``` + +## Success Metrics + +- Zero assumptions about Git in initial interactions +- Successful adaptation to 10+ different VCS approaches +- No forced "best practices" unless requested +- Positive feedback from teams with non-standard processes + +## Anti-Patterns to Avoid + +❌ "You should use Trunk-Based Development" +❌ "Git is the industry standard" +❌ "Your process could be improved by..." +❌ Generating Git-specific artifacts without confirmation +❌ Assuming branches exist + +## Conclusion + +BMAD's strength lies in adaptation, not prescription. By adopting a truly VCS-agnostic approach, BMAD becomes useful to ALL teams, regardless of their version control choices or lack thereof. + +The goal: Make BMAD work with whatever the team has, not force the team to work with what BMAD expects. diff --git a/src/modules/bmvcs/docs/VCS_DETECTION_CONFIDENCE.md b/src/modules/bmvcs/docs/VCS_DETECTION_CONFIDENCE.md new file mode 100644 index 0000000000..76fbb498a5 --- /dev/null +++ b/src/modules/bmvcs/docs/VCS_DETECTION_CONFIDENCE.md @@ -0,0 +1,221 @@ +# VCS Workflow Detection Confidence Scoring + +## Overview + +The VCS auto-detection system uses a confidence-based scoring mechanism to suggest (not decide) the most likely workflow pattern. This document explains how confidence scores are calculated and interpreted. + +## Core Principle + +**"Detection as a HINT, not a DECISION"** + +Even with 100% confidence, we always confirm with the user. Auto-detection saves time but doesn't replace human judgment. + +## Confidence Score Calculation + +### Score Range + +- **0.0 - 1.0** (0% - 100%) +- **Threshold for suggestion: 0.7** (70%) +- Below threshold β†’ marked as "unclear" β†’ trigger clarifying questions + +### Workflow Indicators and Weights + +#### GitFlow (Maximum Score: 1.0) + +| Indicator | Weight | Detection Method | +| --------------------- | ------ | ------------------------------------------- | +| Develop branch exists | 0.3 | Check for `develop` or `development` branch | +| Release branches | 0.3 | Pattern match `release/*` branches | +| Hotfix branches | 0.2 | Pattern match `hotfix/*` branches | +| Version tags | 0.2 | Tags matching `v*` pattern | + +#### GitHub Flow (Maximum Score: 1.0) + +| Indicator | Weight | Detection Method | +| -------------------- | ------ | ----------------------------------------- | +| PR/MR merges | 0.3 | Commit messages with "Merge pull request" | +| Short-lived features | 0.3 | Feature branches < 7 days lifespan | +| Squash merges | 0.2 | Commits with `(#\d+)` pattern | +| No develop branch | 0.2 | Absence of develop/development branch | + +#### Trunk-Based Development (Maximum Score: 1.0) + +| Indicator | Weight | Detection Method | +| ------------------- | ------ | ---------------------------------------- | +| Direct main commits | 0.4 | >50% commits directly to main/master | +| Very short branches | 0.3 | Branches living < 1 day | +| Feature flags | 0.3 | Commits mentioning feature flags/toggles | + +## Confidence Interpretation + +### High Confidence (β‰₯ 70%) + +```yaml +presentation: + title: 'Detected workflow: {workflow}' + confidence: '{score}%' + action: 'Present with evidence and ask for confirmation' +``` + +Example: + +``` +πŸ” Detected workflow: **GitFlow** (confidence: 85%) + +Evidence: +βœ“ Found develop branch +βœ“ Found 3 release branches +βœ“ Found 5 version tags + +Is this correct? +``` + +### Medium Confidence (40% - 69%) + +```yaml +presentation: + title: 'Possible workflow detected' + action: 'Show evidence but emphasize uncertainty' + fallback: 'Offer clarifying questions' +``` + +### Low Confidence (< 40%) + +```yaml +presentation: + title: 'Could not confidently detect workflow' + action: 'Skip to clarifying questions or manual selection' +``` + +## Migration Detection + +When patterns differ between time periods: + +```yaml +time_windows: + recent: 'last 30 days' + historical: '30-90 days ago' + +if_different: + confidence_penalty: -0.2 # Reduce confidence + action: 'Alert user about possible migration' +``` + +## Edge Cases and Adjustments + +### Monorepo Detection + +- Multiple package.json/go.mod files β†’ reduce confidence by 0.1 +- Different patterns in subdirectories β†’ mark as "complex" + +### Fresh Repository + +- Less than 10 commits β†’ automatically mark as "unclear" +- No branches besides main β†’ suggest starting with GitHub Flow + +### Polluted History + +- Imported/migrated repos β†’ check commit dates for anomalies +- Fork detection β†’ warn about inherited patterns + +## Confidence Improvement via Questions + +When initial confidence is low, progressive questions can increase confidence: + +```yaml +question_weights: + team_size: + '1 developer': { trunk_based: +0.3 } + '2-5 developers': { github_flow: +0.2 } + '6+ developers': { gitflow: +0.2 } + + release_frequency: + 'Daily': { trunk_based: +0.3 } + 'Weekly': { github_flow: +0.3 } + 'Monthly+': { gitflow: +0.3 } + + version_maintenance: + 'Yes': { gitflow: +0.4 } + 'No': { github_flow: +0.2, trunk_based: +0.2 } +``` + +## Caching Strategy + +```yaml +cache_config: + validity_period: 7_days + + on_cache_hit: + if_expired: 'Re-run detection' + if_valid: 'Ask for confirmation of cached result' + + invalidate_on: + - Major workflow change detected + - User explicitly requests re-detection + - Cache older than 7 days +``` + +## Implementation Guidelines + +### For Agent Developers + +1. **Always treat detection as advisory** + + ```python + if detection.confidence >= 0.7: + suggest_workflow(detection.workflow) + else: + ask_clarifying_questions() + ``` + +2. **Present evidence transparently** + + ```python + for indicator in detection.evidence: + print(f"βœ“ {indicator}") + ``` + +3. **Allow easy override** + ```python + # Always provide escape hatch + options.append("None of the above") + ``` + +### For Users + +1. **High confidence doesn't mean certainty** - Always review the suggestion +2. **Evidence matters more than score** - Check if the evidence matches your actual workflow +3. **Migration is normal** - If you're changing workflows, tell BMAD +4. **Custom is OK** - Don't force-fit into standard patterns + +## Testing Confidence Scores + +Test scenarios and expected confidence ranges: + +| Scenario | Expected Confidence | Expected Workflow | +| ------------------------------------- | ------------------- | ----------------- | +| Clean GitFlow with all branches | 90-100% | GitFlow | +| GitHub Flow with consistent PR merges | 70-85% | GitHub Flow | +| Mixed patterns | 30-60% | Unclear | +| Fresh repo (<10 commits) | 0-30% | Unclear | +| Trunk-based with feature flags | 70-90% | Trunk-based | + +## Future Improvements + +1. **Machine Learning Enhancement** + - Learn from user corrections + - Adjust weights based on success rate + +2. **Extended Pattern Recognition** + - Detect GitLab Flow + - Recognize scaled patterns (e.g., Scaled Trunk-Based) + +3. **Context-Aware Detection** + - Consider repository language/framework + - Account for team size if available + +## Conclusion + +Confidence scoring enables intelligent suggestions while respecting user autonomy. The goal is to save time for the 80% common cases while gracefully handling the 20% edge cases. + +Remember: **The best workflow is the one your team actually follows, not what the detector suggests.** diff --git a/src/modules/bmvcs/examples/README.md b/src/modules/bmvcs/examples/README.md new file mode 100644 index 0000000000..bb3a365bdd --- /dev/null +++ b/src/modules/bmvcs/examples/README.md @@ -0,0 +1,79 @@ +# BMVCS Examples + +Practical examples demonstrating VCS-agnostic adaptation in BMAD. + +## Files in This Directory + +### [vcs-adaptation-examples.md](./vcs-adaptation-examples.md) + +**Real-world scenarios** showing how BMAD adapts to different VCS workflows: + +- **Startup with GitHub Flow**: Fast-paced web development +- **Enterprise with GitFlow**: Structured releases with versions +- **No Version Control**: One-time scripts and prototypes +- **Custom SVN Workflow**: Legacy system adaptation +- **Trunk-Based with Feature Flags**: Continuous deployment +- **Complex Multi-VCS Setup**: Mixed systems in one organization + +Each example shows discovery dialogue, BMAD adaptations, and generated artifacts. + +### [vcs-detection-implementation.py](./vcs-detection-implementation.py) + +**Reference implementation** of Git workflow auto-detection: + +- Analyzes repository history to detect workflow patterns +- Calculates confidence scores for GitFlow, GitHub Flow, and Trunk-Based +- Follows "Detection as a HINT, not a DECISION" principle +- Interactive confirmation with evidence presentation +- Handles edge cases (migration, unclear patterns, fresh repos) + +**Note**: This is an example implementation in Python. The actual BMAD implementation may use JavaScript/TypeScript. This demonstrates the detection logic that can be adapted to any language. + +## Usage + +### Running the Detector Example + +```bash +cd /path/to/your/git/repo +python /path/to/vcs-detection-implementation.py +``` + +The script will: + +1. Analyze your Git history +2. Score workflow indicators +3. Present detection results with evidence +4. Ask for confirmation (never auto-decides) +5. Save configuration to `.bmad/vcs_config.json` + +### Understanding the Examples + +The adaptation examples show specific output for each workflow type. Use them as: + +- **Reference**: See how BMAD should adapt terminology and structure +- **Templates**: Copy patterns for custom integrations +- **Documentation**: Explain VCS-agnostic behavior to users + +## Key Principles Demonstrated + +1. **Discovery First**: Always ask, never assume +2. **Evidence-Based**: Show detection reasoning transparently +3. **User Confirmation**: Detection is advisory, not prescriptive +4. **Graceful Fallback**: Handle unclear cases with questions +5. **Respect Existing**: Adapt to their workflow, don't change it + +## Integration with BMAD Agents + +These examples inform how all BMAD agents should adapt: + +- **Architect**: Generate VCS-appropriate architecture docs +- **PM**: Create requirements matching workflow style +- **SM**: Size stories for the team's release cadence +- **Dev**: Suggest VCS-appropriate code delivery +- **QA**: Align test plans with workflow gates + +## Further Reading + +- [VCS Agnostic Principles](../docs/VCS_AGNOSTIC_PRINCIPLES.md) +- [Detection Confidence Scoring](../docs/VCS_DETECTION_CONFIDENCE.md) +- [Discovery Task Implementation](../tasks/discover-vcs.md) diff --git a/src/modules/bmvcs/examples/vcs-adaptation-examples.md b/src/modules/bmvcs/examples/vcs-adaptation-examples.md new file mode 100644 index 0000000000..7373e3146f --- /dev/null +++ b/src/modules/bmvcs/examples/vcs-adaptation-examples.md @@ -0,0 +1,293 @@ +# VCS Adaptation Examples + +## Real-World Scenarios: How BMAD Adapts + +### Example 1: Startup with GitHub Flow + +**Context:** 5-person team, web SaaS, deploys daily + +**Discovery:** + +``` +BMAD: "How does your team manage code versions?" +User: "Git with GitHub" +BMAD: "Which Git workflow best describes your approach?" +User: "GitHub Flow - simple feature branches" +``` + +**BMAD Adapts:** + +- Architect generates lightweight, PR-sized architecture updates +- SM creates 1-3 day stories that map to single PRs +- Dev suggests branch names like `feature/add-user-auth` +- All docs optimized for quick review in PR comments + +**Generated Architecture Snippet:** + +```markdown +## Payment Service Update + +_PR: #234 - feature/add-stripe-integration_ + +### Changes in This PR + +- New Stripe webhook handler +- Updated payment models +- Added retry logic + +### Testing + +- [ ] Unit tests for webhook handler +- [ ] Integration test with Stripe test mode +- [ ] Manual testing checklist in PR +``` + +--- + +### Example 2: Enterprise with GitFlow + +**Context:** 50-person team, banking software, quarterly releases + +**Discovery:** + +``` +BMAD: "How does your team manage code versions?" +User: "Git with corporate server" +BMAD: "Which Git workflow?" +User: "GitFlow - we have develop, release, and hotfix branches" +``` + +**BMAD Adapts:** + +- Architect creates version-oriented architecture docs +- PM generates release-scoped PRDs +- SM groups stories by release version +- Dev follows strict branch naming + +**Generated Architecture Snippet:** + +```markdown +## Release 2.4.0 Architecture + +### Version Highlights + +- New authentication system (breaking change) +- Performance improvements +- Database migration required + +### Branch Status + +- develop: v2.5.0 features in progress +- release/2.4.0: Final testing +- hotfix/2.3.1: Critical fix for production + +### Migration Guide + +From 2.3.x to 2.4.0: + +1. Run migration script +2. Update config files +3. Restart services in order +``` + +--- + +### Example 3: No Version Control + +**Context:** Data scientist, one-time analysis script + +**Discovery:** + +``` +BMAD: "How does your team manage code versions?" +User: "No version control needed - this is a one-time script" +``` + +**BMAD Adapts:** + +- All code in single, runnable package +- Extensive inline documentation +- No commit messages or branch references +- Date-stamped delivery + +**Generated Package:** + +``` +customer_analysis_20240315/ +β”œβ”€β”€ README.md # Complete instructions +β”œβ”€β”€ requirements.txt # All Python dependencies +β”œβ”€β”€ analysis.py # Full script with comments +β”œβ”€β”€ data/ +β”‚ └── sample.csv # Sample data format +└── output/ + └── results_template.xlsx +``` + +**README Content:** + +```markdown +# Customer Analysis Script + +Generated: 2024-03-15 + +## Quick Start + +1. Install dependencies: pip install -r requirements.txt +2. Place your data in data/input.csv +3. Run: python analysis.py +4. Results appear in output/ + +## No Version Control Required + +This is a complete, self-contained package. +``` + +--- + +### Example 4: Custom SVN Workflow + +**Context:** Game studio using Subversion + +**Discovery:** + +``` +BMAD: "How does your team manage code versions?" +User: "Other version control system" +BMAD: "Which system?" +User: "Subversion (SVN)" +``` + +**BMAD Adapts:** + +- Uses "revision" instead of "commit" +- References trunk/branches/tags structure +- Revision numbers, not hashes +- SVN-specific commands + +**Generated Instructions:** + +```markdown +## Integration Steps + +1. Update your working copy: + svn update + +2. Create feature branch: + svn copy ^/trunk ^/branches/feature-player-inventory + +3. After implementation: + svn merge ^/branches/feature-player-inventory + +4. Commit with revision message: + svn commit -m "Add player inventory system (refs ticket #456)" +``` + +--- + +### Example 5: Trunk-Based with Feature Flags + +**Context:** Netflix-style continuous deployment + +**Discovery:** + +``` +BMAD: "How does your team manage code versions?" +User: "Git with GitHub" +BMAD: "Which Git workflow?" +User: "Trunk-Based - we deploy continuously" +``` + +**BMAD Adapts:** + +- Everything behind feature flags +- Tiny, hours-long tasks +- Direct commits or same-day PRs +- Progressive rollout plans + +**Generated Story:** + +````markdown +## Story: Add Recommendation Engine + +Size: 4 hours +Flag: `recommendation-engine-v2` + +### Implementation + +```python +if feature_flag.is_enabled("recommendation-engine-v2", user_id): + return new_recommendation_engine(user_id) +else: + return legacy_recommendations(user_id) +``` +```` + +### Rollout Plan + +- Hour 1-2: Implement behind flag (0% users) +- Hour 3: Deploy and enable for employees +- Hour 4: Enable for 1% external users +- Day 2: 10% if metrics good +- Day 3: 50% +- Day 5: 100% and schedule flag removal + +``` + +--- + +### Example 6: Complex Multi-VCS Setup + +**Context:** Enterprise with mixed systems + +**Discovery:** +``` + +BMAD: "How does your team manage code versions?" +User: "Custom/Complex setup" +BMAD: "Please describe:" +User: "Frontend in Git, backend in Perforce, configs in SVN" + +```` + +**BMAD Adapts:** +- Asks for component-specific preferences +- Generates VCS-appropriate artifacts per component +- Uses neutral terminology in cross-component docs + +**Generated Guidance:** +```markdown +## Multi-VCS Development Guide + +### Frontend (Git/GitHub Flow) +- Feature branches from main +- PR review process +- Deploy on merge + +### Backend (Perforce) +- Create changelist for features +- Submit after review +- Changelist numbers in deployment notes + +### Configuration (SVN) +- Update from trunk before changes +- Commit with revision references +- Tag for production releases + +### Cross-Component Changes +When updating across systems: +1. Frontend PR: #123 +2. Backend Changelist: 456789 +3. Config Revision: r1234 + +Reference all three in deployment ticket. +```` + +## Key Takeaways + +1. **BMAD never assumes** - always discovers first +2. **Adapts terminology** - commit/changelist/revision as appropriate +3. **Respects workflows** - doesn't try to "improve" existing processes +4. **Practical focus** - generates what works with their tools +5. **Clear communication** - uses the team's language + +This flexibility makes BMAD valuable to ANY team, regardless of their VCS choice. diff --git a/src/modules/bmvcs/examples/vcs-detection-implementation.py b/src/modules/bmvcs/examples/vcs-detection-implementation.py new file mode 100644 index 0000000000..b148443dba --- /dev/null +++ b/src/modules/bmvcs/examples/vcs-detection-implementation.py @@ -0,0 +1,380 @@ +#!/usr/bin/env python3 +""" +Example implementation of VCS workflow auto-detection for BMAD agents. +This can be adapted for different languages and Git libraries. +""" + +import subprocess +import json +from datetime import datetime, timedelta +from typing import Dict, List, Tuple, Optional + + +class GitWorkflowDetector: + """ + Auto-detect Git workflow from repository history. + Follows the principle: "Detection as a HINT, not a DECISION" + """ + + def __init__(self, repo_path: str = '.'): + self.repo_path = repo_path + self.confidence_threshold = 0.7 + + def run_git_command(self, cmd: str) -> Optional[str]: + """Execute git command and return output""" + try: + result = subprocess.run( + cmd.split(), + cwd=self.repo_path, + capture_output=True, + text=True, + check=True + ) + return result.stdout.strip() + except subprocess.CalledProcessError: + return None + + def detect_workflow(self) -> Dict: + """ + Main detection method that returns workflow suggestion with confidence. + """ + if not self.is_git_repo(): + return { + 'detected': False, + 'reason': 'Not a Git repository' + } + + # Calculate scores for each workflow + gitflow_score = self._score_gitflow() + github_flow_score = self._score_github_flow() + trunk_based_score = self._score_trunk_based() + + # Check for migration + migration_info = self._detect_migration() + + # Determine best match + scores = { + 'gitflow': gitflow_score, + 'github_flow': github_flow_score, + 'trunk_based': trunk_based_score + } + + best_workflow = max(scores.items(), key=lambda x: x[1]['score']) + workflow_name = best_workflow[0] + confidence = best_workflow[1]['score'] + evidence = best_workflow[1]['evidence'] + + # Check if confidence meets threshold + if confidence < self.confidence_threshold: + return { + 'detected': True, + 'workflow': 'unclear', + 'confidence': confidence, + 'evidence': evidence, + 'needs_clarification': True, + 'migration_detected': migration_info['detected'] + } + + return { + 'detected': True, + 'workflow': workflow_name, + 'confidence': confidence, + 'evidence': evidence, + 'migration_detected': migration_info['detected'], + 'migration_info': migration_info if migration_info['detected'] else None + } + + def is_git_repo(self) -> bool: + """Check if current directory is a Git repository""" + return self.run_git_command('git rev-parse --git-dir') is not None + + def _score_gitflow(self) -> Dict: + """Score GitFlow indicators""" + score = 0.0 + evidence = [] + + # Check for develop branch + branches = self.run_git_command('git branch -a') + if branches and ('develop' in branches or 'development' in branches): + score += 0.3 + evidence.append("Found develop branch") + + # Check for release branches + if branches and 'release/' in branches: + release_count = branches.count('release/') + score += 0.3 + evidence.append(f"Found {release_count} release branches") + + # Check for hotfix branches + if branches and 'hotfix/' in branches: + score += 0.2 + evidence.append("Found hotfix branches") + + # Check for version tags + tags = self.run_git_command('git tag -l v*') + if tags: + tag_count = len(tags.split('\n')) + score += 0.2 + evidence.append(f"Found {tag_count} version tags") + + return {'score': score, 'evidence': evidence} + + def _score_github_flow(self) -> Dict: + """Score GitHub Flow indicators""" + score = 0.0 + evidence = [] + + # Check for PR merge patterns in recent commits + recent_commits = self.run_git_command( + 'git log --oneline --since="90 days ago" --grep="Merge pull request"' + ) + if recent_commits: + pr_count = len(recent_commits.split('\n')) + score += 0.3 + evidence.append(f"Found {pr_count} PR merges in last 90 days") + + # Check for squash merge patterns + squash_commits = self.run_git_command( + 'git log --oneline --since="90 days ago" --grep="(#"' + ) + if squash_commits: + score += 0.2 + evidence.append("Found squash-merge patterns") + + # Check average branch lifespan (simplified) + branches = self.run_git_command('git branch -a') + if branches and 'feature/' in branches: + score += 0.3 + evidence.append("Using feature branch naming") + + # No develop branch is positive for GitHub Flow + if branches and 'develop' not in branches: + score += 0.2 + evidence.append("No develop branch (GitHub Flow indicator)") + + return {'score': score, 'evidence': evidence} + + def _score_trunk_based(self) -> Dict: + """Score Trunk-Based Development indicators""" + score = 0.0 + evidence = [] + + # Check ratio of direct commits to main + main_commits = self.run_git_command( + 'git log --oneline --since="90 days ago" --first-parent main' + ) + all_commits = self.run_git_command( + 'git log --oneline --since="90 days ago"' + ) + + if main_commits and all_commits: + main_count = len(main_commits.split('\n')) + total_count = len(all_commits.split('\n')) + ratio = main_count / total_count + + if ratio > 0.5: + score += 0.4 + evidence.append(f"{int(ratio * 100)}% commits directly to main") + + # Check for feature flags in commit messages + feature_flag_commits = self.run_git_command( + 'git log --oneline --since="90 days ago" --grep="feature flag" -i' + ) + if feature_flag_commits: + score += 0.3 + evidence.append("Found feature flag usage in commits") + + # Check for very short-lived branches (would need more complex analysis) + # Simplified: check if most branches are deleted quickly + deleted_branches = self.run_git_command('git reflog show --all | grep "branch:"') + if deleted_branches: + score += 0.3 + evidence.append("Pattern suggests short-lived branches") + + return {'score': score, 'evidence': evidence} + + def _detect_migration(self) -> Dict: + """Detect if workflow has changed recently""" + # Compare recent vs historical commit patterns + recent = self.run_git_command( + 'git log --oneline --since="30 days ago" --pretty=format:"%d"' + ) + historical = self.run_git_command( + 'git log --oneline --since="90 days ago" --until="30 days ago" --pretty=format:"%d"' + ) + + if not recent or not historical: + return {'detected': False} + + # Simple heuristic: check if branch naming patterns changed + recent_has_develop = 'develop' in recent + historical_has_develop = 'develop' in historical + + if recent_has_develop != historical_has_develop: + return { + 'detected': True, + 'recent_pattern': 'GitFlow-like' if recent_has_develop else 'GitHub Flow-like', + 'historical_pattern': 'GitFlow-like' if historical_has_develop else 'GitHub Flow-like' + } + + return {'detected': False} + + def interactive_confirmation(self, detection_result: Dict) -> str: + """ + Present detection results to user and get confirmation. + This demonstrates the "hint not decision" principle. + """ + if not detection_result['detected']: + print(f"❌ {detection_result['reason']}") + return self.manual_selection() + + if detection_result['workflow'] == 'unclear': + print("πŸ€” Could not confidently detect your workflow.") + print(f" Confidence: {detection_result['confidence']:.1%}") + return self.clarifying_questions() + + # Present detection with evidence + print(f"πŸ” Analyzed your Git history...") + print(f"\nDetected workflow: **{detection_result['workflow']}**") + print(f"Confidence: {detection_result['confidence']:.1%}\n") + print("Evidence:") + for item in detection_result['evidence']: + print(f" βœ“ {item}") + + if detection_result['migration_detected']: + print("\nπŸ“Š Note: Detected a possible workflow change recently") + print(f" Recent: {detection_result['migration_info']['recent_pattern']}") + print(f" Historical: {detection_result['migration_info']['historical_pattern']}") + + # Get confirmation + print("\nIs this correct?") + print("1. Yes, that's right") + print("2. No, we actually use something else") + print("3. We recently changed our approach") + print("4. It's more complex than that") + + choice = input("\nSelect (1-4): ") + + if choice == '1': + return detection_result['workflow'] + elif choice == '3': + return self.handle_migration() + else: + return self.manual_selection() + + def clarifying_questions(self) -> str: + """Ask progressive questions when detection is unclear""" + print("\nLet me ask a few questions to understand your workflow better:\n") + + # Progressive questions to increase confidence + score_adjustments = { + 'gitflow': 0, + 'github_flow': 0, + 'trunk_based': 0 + } + + # Question 1: Team size + print("1. How many developers actively commit code?") + print(" a) Just me") + print(" b) 2-5 developers") + print(" c) 6+ developers") + team_size = input("Select (a-c): ") + + if team_size == 'a': + score_adjustments['trunk_based'] += 0.3 + elif team_size == 'b': + score_adjustments['github_flow'] += 0.2 + elif team_size == 'c': + score_adjustments['gitflow'] += 0.2 + + # Question 2: Release frequency + print("\n2. How often do you release to production?") + print(" a) Multiple times daily") + print(" b) Weekly") + print(" c) Monthly or less frequently") + release_freq = input("Select (a-c): ") + + if release_freq == 'a': + score_adjustments['trunk_based'] += 0.3 + elif release_freq == 'b': + score_adjustments['github_flow'] += 0.3 + elif release_freq == 'c': + score_adjustments['gitflow'] += 0.3 + + # Determine recommendation + best_workflow = max(score_adjustments.items(), key=lambda x: x[1]) + return best_workflow[0] + + def manual_selection(self) -> str: + """Fallback to manual workflow selection""" + print("\nWhich Git workflow best describes your team's approach?\n") + print("1. GitHub Flow - Simple feature branches with pull requests") + print(" β†’ Best for: Web apps, continuous deployment\n") + print("2. GitFlow - Structured branches (develop, release, hotfix)") + print(" β†’ Best for: Versioned software, scheduled releases\n") + print("3. Trunk-Based - Direct commits or very short branches") + print(" β†’ Best for: Mature CI/CD, experienced teams\n") + print("4. Custom Git workflow") + + choice = input("Select (1-4): ") + + workflow_map = { + '1': 'github_flow', + '2': 'gitflow', + '3': 'trunk_based', + '4': 'custom' + } + + return workflow_map.get(choice, 'github_flow') + + def handle_migration(self) -> str: + """Handle workflow migration scenario""" + print("\nWhich workflow should BMAD optimize for?") + print("1. The new approach (we've completed migration)") + print("2. The old approach (recent activity was exceptional)") + print("3. Both (we're still transitioning)") + + choice = input("Select (1-3): ") + + if choice == '3': + print("\nWhich workflow is your target state?") + + return self.manual_selection() + + +def main(): + """Example usage of the detector""" + detector = GitWorkflowDetector() + + # Run detection + result = detector.detect_workflow() + + # Get user confirmation (following "hint not decision" principle) + confirmed_workflow = detector.interactive_confirmation(result) + + # Save configuration + config = { + 'vcs_config': { + 'type': 'git', + 'workflow': confirmed_workflow, + 'detection_method': 'auto-detected' if result['detected'] else 'user-selected', + 'confidence_score': result.get('confidence', 0), + 'detection_evidence': result.get('evidence', []), + 'cache': { + 'detected_at': datetime.now().isoformat(), + 'valid_until': (datetime.now() + timedelta(days=7)).isoformat() + } + } + } + + print(f"\nβœ… Configuration saved!") + print(f" Workflow: {confirmed_workflow}") + print(f" All BMAD agents will adapt to your {confirmed_workflow} workflow.") + + # Save to file (in real implementation) + with open('.bmad/vcs_config.json', 'w') as f: + json.dump(config, f, indent=2) + + +if __name__ == '__main__': + main() diff --git a/src/modules/bmvcs/tasks/create-vcs-adapted-doc.md b/src/modules/bmvcs/tasks/create-vcs-adapted-doc.md new file mode 100644 index 0000000000..edd5cc9dd7 --- /dev/null +++ b/src/modules/bmvcs/tasks/create-vcs-adapted-doc.md @@ -0,0 +1,165 @@ +# Create VCS-Adapted Document Task + +## Purpose + +Adapt architecture and other documents based on the team's version control system configuration. + +## Prerequisites + +- VCS configuration must exist in `.bmad-core/vcs-config.yaml` +- If not, run `discover-vcs.md` task first + +## Task Instructions + +### Step 1: Load VCS Configuration + +```yaml +load_config: + file: .bmad-core/vcs-config.yaml + fallback: + if_missing: 'Execute discover-vcs.md task first' +``` + +### Step 2: Load Appropriate VCS Template + +Based on `vcs_config.workflow`: + +- `github-flow` β†’ Load `vcs-adaptations/git-github-flow.yaml` +- `gitflow` β†’ Load `vcs-adaptations/git-gitflow.yaml` +- `trunk-based` β†’ Load `vcs-adaptations/git-trunk-based.yaml` +- `none` β†’ Load `vcs-adaptations/no-vcs.yaml` +- `custom` or other β†’ Load `vcs-adaptations/custom-generic.yaml` + +### Step 3: Apply Adaptations to Document + +#### For Architecture Documents: + +**If Git-based (GitHub Flow/GitFlow/Trunk):** + +```yaml +adaptations: + structure: + - Include branch strategy section + - Add CI/CD pipeline considerations + - Reference commit conventions + + terminology: + - Use Git terminology (branch, commit, merge) + - Include PR/MR workflow details +``` + +**If No VCS:** + +```yaml +adaptations: + structure: + - Single comprehensive document + - Date-based versioning + - All diagrams embedded + + terminology: + - Avoid version control terms + - Focus on deliverables +``` + +**If Custom VCS:** + +```yaml +adaptations: + structure: + - Ask user for preferred format + - Mirror their documentation style + + terminology: + - Use their VCS terminology + - Avoid Git-specific references +``` + +### Step 4: Document Sections Based on VCS + +#### GitHub Flow Additions: + +```markdown +## Development Workflow + +- Feature branches from main +- Pull requests for review +- Continuous deployment after merge + +## Architecture Decisions per Feature + +- Lightweight ADRs in feature branches +- Architecture evolves with each PR +``` + +#### GitFlow Additions: + +```markdown +## Release Architecture + +- Version-specific considerations +- Migration paths between versions +- Hotfix procedures + +## Branch-Specific Components + +- Features in development +- Release candidates +- Production hotfixes +``` + +#### Trunk-Based Additions: + +```markdown +## Feature Flag Architecture + +- Flag-gated components +- Progressive rollout strategy +- Flag retirement plan + +## Continuous Architecture + +- Small, incremental changes +- Always-deployable state +``` + +#### No VCS Additions: + +```markdown +## Complete Package Contents + +- All source code included +- Setup instructions +- No external dependencies + +## Delivery Structure + +- Single ZIP/folder +- Date-stamped versions +``` + +### Step 5: Adapt Language and Recommendations + +Based on VCS type, adjust: + +- Deployment strategies +- Testing approaches +- Documentation structure +- Team collaboration patterns + +## Output Format + +The adapted document should: + +1. Respect the team's existing VCS practices +2. Use appropriate terminology +3. Structure content for their workflow +4. Include VCS-specific best practices +5. Avoid imposing foreign concepts + +## Success Criteria + +- Document aligns with team's VCS workflow +- No Git assumptions for non-Git users +- Practical, actionable guidance +- Respects existing team processes diff --git a/src/modules/bmvcs/tasks/discover-vcs.md b/src/modules/bmvcs/tasks/discover-vcs.md new file mode 100644 index 0000000000..861159eb61 --- /dev/null +++ b/src/modules/bmvcs/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) diff --git a/src/modules/bmvcs/tasks/validate-vcs-config.md b/src/modules/bmvcs/tasks/validate-vcs-config.md new file mode 100644 index 0000000000..ddd6d4029f --- /dev/null +++ b/src/modules/bmvcs/tasks/validate-vcs-config.md @@ -0,0 +1,77 @@ +# Validate VCS Configuration Task + +## Purpose + +Validate that the VCS configuration file exists and contains valid settings. + +## Task Instructions + +### Step 1: Check Configuration Exists + +```yaml +check_file: .bmad/vcs-config.yaml +if_missing: | + VCS configuration not found. Please run VCS discovery first: + - Activate VCS Adapter agent + - Run: *discover +``` + +### Step 2: Validate Structure + +```yaml +validate_yaml: + required_fields: + - vcs_config.type + - vcs_config.workflow + - vcs_config.adaptations.artifact_format + - vcs_config.adaptations.terminology + - vcs_config.adaptations.commit_style +``` + +### Step 3: Validate Values + +```yaml +validate_values: + vcs_config.type: + allowed: [git, svn, perforce, mercurial, tfs, none, custom] + + vcs_config.workflow: + allowed: [github-flow, gitflow, trunk-based, custom, none] + + vcs_config.adaptations.artifact_format: + allowed: [branches, monolithic, platform-specific] + + vcs_config.adaptations.terminology: + allowed: [git, svn, generic, platform-specific, custom] + + vcs_config.adaptations.commit_style: + allowed: [conventional, team-specific, none] +``` + +### Step 4: Report Results + +```yaml +output: | + βœ… VCS Configuration Valid + + System: {type} + Workflow: {workflow} + Artifact Format: {artifact_format} + Terminology: {terminology} + Commit Style: {commit_style} +``` + +## Error Handling + +If validation fails: + +- Report specific field with error +- Suggest correction +- Offer to re-run discovery + +## Success Criteria + +- Configuration file exists +- All required fields present +- All values within allowed ranges +- YAML syntax valid 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 0000000000..b3466a18ed --- /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 0000000000..6ca9c6ee0b --- /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 0000000000..5780d31076 --- /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 0000000000..98d8c28a71 --- /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 0000000000..455dd6b4f3 --- /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" diff --git a/src/modules/bmvcs/workflows/setup-vcs/checklist.md b/src/modules/bmvcs/workflows/setup-vcs/checklist.md new file mode 100644 index 0000000000..e7766e93ad --- /dev/null +++ b/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 diff --git a/src/modules/bmvcs/workflows/setup-vcs/instructions.md b/src/modules/bmvcs/workflows/setup-vcs/instructions.md new file mode 100644 index 0000000000..22f25d7c29 --- /dev/null +++ b/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 diff --git a/src/modules/bmvcs/workflows/setup-vcs/workflow.yaml b/src/modules/bmvcs/workflows/setup-vcs/workflow.yaml new file mode 100644 index 0000000000..e4cd8488b6 --- /dev/null +++ b/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