create-byan-agent 2.6.2 → 2.7.0

package/MIGRATION-v2.0-to-v2.1.md

@@ -1,430 +0,0 @@
-# Migration Guide: v2.0.0 → v2.1.0
-
-**Good News**: BYAN v2.1.0 is 100% backwards compatible with v2.0.0!
-
-## 🎯 TL;DR
-
-**No changes required** - Your v2.0.0 code works unchanged in v2.1.0.
-
-If you want to use new BMAD features, they're opt-in.
-
----
-
-## Option 1: No Changes (Recommended for Existing Projects)
-
-Your existing code continues to work:
-
-```javascript
-// v2.0.0 code - works identically in v2.1.0
-const ByanV2 = require('create-byan-agent');
-
-const byan = new ByanV2();
-await byan.startSession();
-
-while (!byan.isComplete()) {
-  const question = byan.getNextQuestion();
-  const answer = await getUserInput(question);
-  await byan.submitResponse(answer);
-}
-
-const profile = await byan.generateProfile();
-```
-
-**Result**: Identical behavior to v2.0.0, zero breaking changes.
-
----
-
-## Option 2: Enable All BMAD Features
-
-Get the full v2.1.0 experience:
-
-```javascript
-const ByanV2 = require('create-byan-agent');
-
-const byan = new ByanV2({
-  // Your existing config
-  maxQuestions: 12,
-  outputDir: './_bmad-output/bmb-creations',
-  
-  // NEW: Enable all BMAD features (optional)
-  bmad_features: {
-    glossary_builder: {
-      enabled: true,
-      auto_trigger_domains: ['ecommerce', 'finance', 'healthcare'],
-      min_concepts: 5,
-      clarity_threshold: 0.7
-    },
-    five_whys: {
-      enabled: true,
-      max_depth: 5,
-      auto_trigger: true
-    },
-    active_listener: {
-      enabled: true,
-      reformulation_frequency: 3
-    },
-    mantras_validator: {
-      enabled: true,
-      min_compliance_score: 0.8
-    }
-  }
-});
-
-// Interview works the same, but now:
-// - Glossary auto-triggers for complex domains
-// - Pain points automatically analyzed with 5 Whys
-// - Responses reformulated every 3rd question
-// - Agent validated against 64 mantras at the end
-```
-
-**New Methods Available**:
-```javascript
-// Glossary
-const glossary = byan.startGlossary();
-const concept = byan.addConcept('Order', 'Customer purchase request');
-const concepts = byan.getConcepts();
-
-// Five Whys
-const painPoints = byan.detectPainPoints(response);
-const whyQuestion = byan.askWhy();
-const analysis = byan.processWhyAnswer(answer);
-const rootCause = byan.getRootCause();
-
-// Active Listener
-const result = byan.listen(userInput, context);
-const summary = byan.summarizeSession();
-
-// Mantras
-const validation = byan.validateAgent(agentDefinition);
-const report = byan.generateComplianceReport();
-```
-
----
-
-## Option 3: Selective Feature Enablement
-
-Enable only specific features:
-
-```javascript
-const byan = new ByanV2({
-  bmad_features: {
-    glossary_builder: { enabled: true },   // ✅ Enable glossary
-    five_whys: { enabled: false },         // ❌ Disable 5 Whys
-    active_listener: { enabled: true },    // ✅ Enable active listening
-    mantras_validator: { enabled: false }  // ❌ Disable mantras
-  }
-});
-```
-
-**Use Cases**:
-- **Glossary only**: Perfect for domain-heavy projects
-- **Active Listener only**: Focus on interview quality
-- **Mantras only**: Post-generation validation
-- **Custom combo**: Mix and match as needed
-
----
-
-## Configuration File Migration
-
-### v2.0.0 `_byan/config.yaml`
-```yaml
-user_name: Yan
-communication_language: Francais
-document_output_language: Francais
-output_folder: "{project-root}/_bmad-output"
-```
-
-### v2.1.0 `_byan/config.yaml` (Optional Additions)
-```yaml
-# Existing config - unchanged
-user_name: Yan
-communication_language: Francais
-document_output_language: Francais
-output_folder: "{project-root}/_bmad-output"
-
-# NEW: Optional BMAD features
-bmad_features:
-  glossary_builder:
-    enabled: true
-    auto_trigger_domains:
-      - ecommerce
-      - finance
-      - healthcare
-    min_concepts: 5
-    clarity_threshold: 0.7
-  
-  five_whys:
-    enabled: true
-    max_depth: 5
-    pain_keywords:
-      - problem
-      - issue
-      - slow
-      - error
-      - bug
-    auto_trigger: true
-  
-  active_listener:
-    enabled: true
-    reformulation_frequency: 3
-    
-  mantras_validator:
-    enabled: true
-    min_compliance_score: 0.8
-```
-
-**If you don't add the `bmad_features` section**, default values are used (all enabled).
-
----
-
-## State Machine Changes
-
-### v2.0.0 Workflow
-```
-INIT → INTERVIEW → ANALYSIS → GENERATION → COMPLETED
-```
-
-### v2.1.0 Workflow (with BMAD)
-```
-INIT → INTERVIEW → [GLOSSARY] → ANALYSIS → GENERATION → [VALIDATION] → COMPLETED
-```
-
-**Notes**:
-- `GLOSSARY` state: Optional, auto-triggers for complex domains
-- `VALIDATION` state: Optional, validates against mantras
-- If features disabled, workflow identical to v2.0.0
-
----
-
-## New API Methods
-
-### Glossary Builder
-```javascript
-// Start glossary for a domain
-const glossary = byan.startGlossary('ecommerce', { 
-  minConcepts: 5,
-  clarityThreshold: 0.7 
-});
-
-// Add concept
-const result = byan.addConcept('Product', 'An item available for purchase');
-// Returns: { concept: {...}, validation: {...} }
-
-// Get all concepts
-const concepts = byan.getConcepts();
-// Returns: [{ term, definition, clarityScore, ... }]
-
-// Get full glossary
-const full = byan.getGlossary();
-// Returns: { domain, concepts, relatedTerms, ... }
-```
-
-### Five Whys Analyzer
-```javascript
-// Detect pain points
-const detection = byan.detectPainPoints(response);
-// Returns: { needsWhys: true/false, painPoints: [...] }
-
-// Ask WHY question
-const question = byan.askWhy();
-// Returns: { depth: 1, question: "Why is this a problem?", prompt: "..." }
-
-// Process answer
-const result = byan.processWhyAnswer('Because the API is slow');
-// Returns: { valid: true, depth: 1, nextQuestion: {...} }
-
-// Get root cause
-const rootCause = byan.getRootCause();
-// Returns: { 
-//   statement: "Lack of API caching infrastructure",
-//   category: "technical",
-//   confidence: 0.85,
-//   depth: 5,
-//   actions: [...]
-// }
-```
-
-### Active Listener
-```javascript
-// Listen to user input
-const result = byan.listen(userInput, context);
-// Returns: {
-//   reformulation: "So you need...",
-//   validation: { valid: true, issues: [] },
-//   issues: [],
-//   corrections: [],
-//   confidence: 0.9
-// }
-
-// Reformulate explicitly
-const reformulated = byan.reformulate(userInput, 'formal');
-// Returns: { original, reformulation, improvements, style }
-
-// Validate response
-const validation = byan.validateResponse(userInput);
-// Returns: { valid: true/false, issues: [...] }
-
-// Summarize session
-const summary = byan.summarizeSession();
-// Returns: {
-//   overview: "The user wants...",
-//   keyPoints: [...],
-//   insights: [...],
-//   patterns: { clarityLevel: 'high', ... }
-// }
-```
-
-### Mantras Validator
-```javascript
-// Validate agent
-const validation = byan.validateAgent(agentDefinition);
-// Returns: {
-//   compliant: [{ id: '#37', name: 'Ockham\'s Razor', ... }],
-//   nonCompliant: [{ id: 'IA-23', name: 'No Emoji Pollution', ... }],
-//   score: 0.85
-// }
-
-// Generate report
-const report = byan.generateComplianceReport();
-// Returns: full compliance report with recommendations
-
-// Validate specific mantra
-const result = byan.validateMantra('IA-23', agentContent);
-// Returns: { compliant: true/false, violations: [...] }
-
-// Get mantras by category
-const mantras = byan.getMantras('Quality');
-// Returns: all Quality mantras
-
-// Get validation summary
-const summary = byan.getValidationSummary();
-// Returns: { score, compliant, nonCompliant, recommendations }
-```
-
----
-
-## Testing Updates
-
-### v2.0.0
-```bash
-npm test
-# 891 tests passing
-```
-
-### v2.1.0
-```bash
-npm test
-# 1,308 tests passing (891 core + 417 BMAD)
-```
-
-**No test changes needed** for your existing code.
-
----
-
-## Performance Impact
-
-**v2.1.0 Performance**:
-- **Overhead**: < 10% vs v2.0.0 (measured)
-- **Glossary**: < 100ms per concept
-- **Five Whys**: < 50ms per question
-- **Active Listener**: < 100ms per response
-- **Mantras**: < 200ms per validation
-
-**Total Workflow**: < 10% slower than v2.0.0 with all features enabled.
-
-**Recommendation**: Negligible impact for typical workflows (< 1 second added to 10-second interview).
-
----
-
-## Common Migration Scenarios
-
-### Scenario 1: Existing Production Code
-**Recommendation**: No changes
-- v2.1.0 works identically to v2.0.0
-- Update `package.json` to `^2.1.0`
-- Test to confirm (zero changes expected)
-- Deploy with confidence
-
-### Scenario 2: New Project
-**Recommendation**: Enable all BMAD features
-- Benefit from glossary, 5 Whys, active listening, mantras
-- Better agent quality out of the box
-- More structured interview process
-
-### Scenario 3: Domain-Heavy Project (Finance, Healthcare, Legal)
-**Recommendation**: Enable glossary_builder + mantras_validator
-```javascript
-bmad_features: {
-  glossary_builder: { enabled: true },
-  five_whys: { enabled: false },
-  active_listener: { enabled: false },
-  mantras_validator: { enabled: true }
-}
-```
-
-### Scenario 4: Problem-Focused Project (Troubleshooting Agents)
-**Recommendation**: Enable five_whys + active_listener
-```javascript
-bmad_features: {
-  glossary_builder: { enabled: false },
-  five_whys: { enabled: true },
-  active_listener: { enabled: true },
-  mantras_validator: { enabled: false }
-}
-```
-
----
-
-## Breaking Changes
-
-**None** - v2.1.0 is 100% backwards compatible.
-
----
-
-## Deprecations
-
-**None** - All v2.0.0 APIs remain fully supported.
-
----
-
-## Rollback Plan
-
-If you encounter issues:
-
-```bash
-# Downgrade to v2.0.0
-npm install byan-v2@2.0.0
-```
-
-Or in `package.json`:
-```json
-{
-  "dependencies": {
-    "byan-v2": "2.0.0"
-  }
-}
-```
-
-**Note**: No rollbacks reported in testing (100% compatibility maintained).
-
----
-
-## Support
-
-- **Issues**: GitHub Issues
-- **Questions**: See [README-BYAN-V2.md](./README-BYAN-V2.md)
-- **API Docs**: See [API-BYAN-V2.md](./API-BYAN-V2.md)
-- **BMAD Guide**: See [BMAD-QUICK-REFERENCE.md](./BMAD-QUICK-REFERENCE.md)
-
----
-
-## Checklist
-
-- [ ] Update `package.json` to `^2.1.0`
-- [ ] Run `npm install`
-- [ ] Run tests: `npm test`
-- [ ] (Optional) Add `bmad_features` to config
-- [ ] (Optional) Update code to use new methods
-- [ ] Deploy
-
-**Estimated Time**: 5 minutes (or less if no BMAD features needed)