feat(bmvcs): add VCS discovery tasks and installer
- Port discover-vcs.md from PR #582 (187 lines) - Port create-vcs-adapted-doc.md from PR #583 (165 lines) - Add validate-vcs-config.md task (73 lines new) - Add installer.js for module setup (26 lines) Part 2/5 of BMVCS migration (#661) - Tasks Complete Note: VCS templates to be added in next commit after proper extraction Next: Manually create 5 VCS templates with valid YAML
This commit is contained in:
Serhii
parent
9571a2f332
commit
2137a7790b
|
|
@ -57,3 +57,6 @@ tools/template-test-generator/test-scenarios/
|
|||
# Test Install Output
|
||||
|
||||
z*/
|
||||
|
||||
# BMVCS Migration Planning (local only)
|
||||
.bmvcs-migration/
|
||||
|
|
|
|||
|
|
@ -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 };
|
||||
|
|
@ -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
|
||||
|
|
@ -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,76 @@
|
|||
# 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
|
||||
Loading…
Reference in New Issue