From e4a469c67ac244b2c75e66d20a375c4496f32287 Mon Sep 17 00:00:00 2001 From: Serhii Date: Mon, 15 Sep 2025 09:27:48 +0300 Subject: [PATCH] feat(core): Add VCS discovery mechanism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces core VCS discovery functionality to make BMAD adapt to existing version control practices. - Add discover-vcs.md task for identifying team's VCS approach - Update Architect agent to run VCS discovery on activation - Add VCS_AGNOSTIC_PRINCIPLES.md documenting the approach - Enable support for Git, SVN, Perforce, and no-VCS workflows Aligns with "Optimized for the majority, open to all" principle. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- bmad-core/agents/architect.md | 18 ++- bmad-core/tasks/discover-vcs.md | 187 ++++++++++++++++++++++++++++++++ docs/VCS_AGNOSTIC_PRINCIPLES.md | 161 +++++++++++++++++++++++++++ 3 files changed, 362 insertions(+), 4 deletions(-) create mode 100644 bmad-core/tasks/discover-vcs.md create mode 100644 docs/VCS_AGNOSTIC_PRINCIPLES.md diff --git a/bmad-core/agents/architect.md b/bmad-core/agents/architect.md index ab801f3f..f3852905 100644 --- a/bmad-core/agents/architect.md +++ b/bmad-core/agents/architect.md @@ -20,6 +20,7 @@ activation-instructions: - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below - STEP 3: Load and read `.bmad-core/core-config.yaml` (project configuration) before any greeting + - STEP 3.5: Check if VCS configuration exists in `.bmad-core/vcs-config.yaml`, if not, execute task `discover-vcs.md` - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands - DO NOT: Load any other agent files during activation - ONLY load dependency files when user selects them for execution via command or request of a task @@ -53,13 +54,15 @@ persona: - Data-Centric Design - Let data requirements drive architecture - Cost-Conscious Engineering - Balance technical ideals with financial reality - Living Architecture - Design for change and adaptation + - VCS-Agnostic Design - Adapt architecture to team's version control practices, not vice versa # All commands require * prefix when used (e.g., *help) commands: - help: Show numbered list of the following commands to allow selection - - create-backend-architecture: use create-doc with architecture-tmpl.yaml - - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml - - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml - - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml + - discover-vcs: Execute discover-vcs.md task to identify team's version control approach + - create-backend-architecture: use create-doc with architecture-tmpl.yaml (VCS-adapted) + - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml (VCS-adapted) + - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml (VCS-adapted) + - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml (VCS-adapted) - doc-out: Output full document to current destination file - document-project: execute the task document-project.md - execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist) @@ -75,6 +78,7 @@ dependencies: tasks: - create-deep-research-prompt.md - create-doc.md + - discover-vcs.md - document-project.md - execute-checklist.md templates: @@ -82,4 +86,10 @@ dependencies: - brownfield-architecture-tmpl.yaml - front-end-architecture-tmpl.yaml - fullstack-architecture-tmpl.yaml + vcs-adaptations: + - vcs-adaptations/git-github-flow.yaml + - vcs-adaptations/git-gitflow.yaml + - vcs-adaptations/git-trunk-based.yaml + - vcs-adaptations/no-vcs.yaml + - vcs-adaptations/custom-generic.yaml ``` diff --git a/bmad-core/tasks/discover-vcs.md b/bmad-core/tasks/discover-vcs.md new file mode 100644 index 00000000..861159eb --- /dev/null +++ b/bmad-core/tasks/discover-vcs.md @@ -0,0 +1,187 @@ +# VCS Discovery Task + +## Purpose + +Identify and adapt to the team's version control system at project initialization. + +## Philosophy + +- Optimize for the 85-90% who use Git +- Remain open for the 10-15% with special needs +- Suggest best practices without forcing them + +## Task Instructions + +### Step 1: Initial Discovery + +```yaml +elicit: true +prompt: | + How does your team manage code versions? + + 1. Git with GitHub/GitLab/Bitbucket [MOST COMMON] + 2. Git with corporate server + 3. Other version control system + 4. No version control needed + 5. Custom/Complex setup + + Select a number (1-5): +``` + +### Step 2A: Git-Based Workflows (Options 1-2) + +If user selects Git-based: + +```yaml +elicit: true +prompt: | + Which Git workflow best describes your team's approach? + + 1. GitHub Flow - Simple feature branches with pull requests + → Best for: Web apps, continuous deployment + + 2. GitFlow - Structured branches (develop, release, hotfix) + → Best for: Versioned software, scheduled releases + + 3. Trunk-Based - Direct commits or very short branches + → Best for: Mature CI/CD, experienced teams + + 4. Not sure - I'd like a recommendation + → We'll ask a few questions to suggest the best fit + + 5. Custom Git workflow + → Describe your approach + + Select a number (1-5): +``` + +#### If "Not sure" (Option 4): + +```yaml +elicit: true +questions: + - 'How many developers on your team? (1, 2-5, 6+)' + - 'How often do you release? (Daily, Weekly, Monthly, Quarterly)' + - 'Do you have automated testing? (Yes/No)' + - 'Do you need to maintain multiple versions? (Yes/No)' + +recommendation_logic: | + - Solo or Daily releases + Automated tests → Trunk-Based + - Small team + Weekly/Monthly → GitHub Flow + - Large team or Multiple versions → GitFlow + - Default → GitHub Flow (safest choice) +``` + +#### If "Custom" (Option 5): + +```yaml +elicit: true +prompt: | + Please briefly describe your Git workflow: + (e.g., "We use feature branches but merge to staging first, then production") + + [Free text input] +``` + +### Step 2B: Other VCS (Option 3) + +```yaml +elicit: true +prompt: | + Which version control system do you use? + + 1. Subversion (SVN) + 2. Perforce + 3. Mercurial + 4. Team Foundation Server (TFS) + 5. Other (please specify) + + Select a number or describe: +``` + +### Step 2C: No VCS (Option 4) + +```yaml +confirm: | + Understood. BMAD will generate: + - Self-contained deliverables + - Date-versioned packages + - No commit messages or branch references + + Is this a prototype/one-time project? (Yes/No) +``` + +### Step 2D: Complex Setup (Option 5) + +```yaml +elicit: true +prompt: | + Please describe your version control setup: + (e.g., "Monorepo with custom tooling", "Multiple systems for different components") + + [Free text input] +``` + +### Step 3: Store Configuration + +Save the VCS configuration for all agents to access: + +```yaml +vcs_config: + type: [git|svn|perforce|none|custom] + workflow: [github-flow|gitflow|trunk-based|custom|none] + details: [user's custom description if provided] + + adaptations: + artifact_format: [branches|monolithic|platform-specific] + terminology: [git|generic|platform-specific] + commit_style: [conventional|team-specific|none] +``` + +### Step 4: Confirm Understanding + +```yaml +output: | + VCS Configuration Confirmed: + - System: {type} + - Workflow: {workflow} + - BMAD will adapt by: {key_adaptations} + + All agents will generate artifacts compatible with your setup. +``` + +## Success Criteria + +- 80% of users can select from predefined options +- 20% custom cases are handled gracefully +- Configuration is stored and accessible to all agents +- No Git assumptions for non-Git users +- Clear recommendations when requested + +## Agent Adaptations Based on VCS + +### For Architect Agent + +- Git + GitHub Flow: Suggest feature-based architecture docs +- Git + GitFlow: Support release-oriented planning +- No VCS: Generate comprehensive, dated documents +- Custom: Ask for preferred format + +### For Dev Agent + +- Git workflows: Generate appropriate commit messages +- No VCS: Package complete code solutions +- Custom: Follow described conventions + +### For SM Agent + +- Git + Trunk: Create small, atomic stories +- Git + GitFlow: Support epic-based stories +- No VCS: Create comprehensive story documents + +## Notes + +- This discovery happens ONCE at project start +- All agents read this configuration +- Can be updated if team process changes +- Default to GitHub Flow if uncertain (most common, safest) diff --git a/docs/VCS_AGNOSTIC_PRINCIPLES.md b/docs/VCS_AGNOSTIC_PRINCIPLES.md new file mode 100644 index 00000000..7f21aeb0 --- /dev/null +++ b/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.**