feat(bmvcs): add VCS-agnostic documentation
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 <noreply@anthropic.com>
This commit is contained in:
Serhii
parent
8d342f3bd7
commit
bccfe9d651
|
|
@ -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
|
||||||
|
|
@ -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.**
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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.**
|
||||||
Loading…
Reference in New Issue