feat(core): Add VCS discovery mechanism
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 <noreply@anthropic.com>
This commit is contained in:
Serhii
parent
f09e282d72
commit
e4a469c67a
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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.**
|
||||
Loading…
Reference in New Issue