From bccfe9d651a065ca062078989012e1ee38b013fd Mon Sep 17 00:00:00 2001 From: Serhii Date: Tue, 30 Sep 2025 20:01:03 +0300 Subject: [PATCH] feat(bmvcs): add VCS-agnostic documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive documentation for VCS-agnostic approach: - VCS_AGNOSTIC_PRINCIPLES.md: Core philosophy and 10 principles - VCS_AGNOSTIC_PROPOSAL.md: Implementation approach and examples - VCS_DETECTION_CONFIDENCE.md: Auto-detection confidence scoring - docs/README.md: Documentation overview and quick start Documentation explains how BMAD adapts to any VCS (Git, SVN, Perforce, or no VCS) with appropriate terminology and workflow patterns. Part 3/5 of BMVCS migration (#661) πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- src/modules/bmvcs/docs/README.md | 76 ++++++ .../bmvcs/docs/VCS_AGNOSTIC_PRINCIPLES.md | 161 +++++++++++++ .../bmvcs/docs/VCS_AGNOSTIC_PROPOSAL.md | 186 +++++++++++++++ .../bmvcs/docs/VCS_DETECTION_CONFIDENCE.md | 221 ++++++++++++++++++ 4 files changed, 644 insertions(+) create mode 100644 src/modules/bmvcs/docs/README.md create mode 100644 src/modules/bmvcs/docs/VCS_AGNOSTIC_PRINCIPLES.md create mode 100644 src/modules/bmvcs/docs/VCS_AGNOSTIC_PROPOSAL.md create mode 100644 src/modules/bmvcs/docs/VCS_DETECTION_CONFIDENCE.md diff --git a/src/modules/bmvcs/docs/README.md b/src/modules/bmvcs/docs/README.md new file mode 100644 index 00000000..948b0e19 --- /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 00000000..7f21aeb0 --- /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 00000000..9c787b8d --- /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 00000000..76fbb498 --- /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.**