@iservu-inc/adf-cli 0.2.0 → 0.3.6

package/.project/docs/FRAMEWORK-UPDATE-INTEGRATION.md

@@ -0,0 +1,421 @@
+# Framework Update System Integration
+
+**Date:** 2025-10-03
+**Status:** ✅ Complete - Ready to Deploy
+**Purpose:** Integration between AgentDevFramework monitoring and adf-cli updates
+
+---
+
+## 🎯 System Overview
+
+We've created a complete system to:
+1. **Monitor** the 4 upstream framework repositories for updates
+2. **Notify** when changes are detected
+3. **Analyze** changes using AI (Claude) to determine impact
+4. **Recommend** specific updates for adf-cli
+5. **Automate** the entire process (optional)
+
+---
+
+## 📁 What Was Created
+
+### In AgentDevFramework Repository
+
+**Scripts:**
+- `scripts/check-framework-updates.js` - Check for new commits in 4 frameworks
+- `scripts/update-frameworks.js` - Pull latest changes from all frameworks
+- `scripts/analyze-framework-updates.js` - AI analysis of changes
+
+**Automation:**
+- `.github/workflows/monitor-framework-updates.yml` - GitHub Actions workflow (runs daily)
+
+**Documentation:**
+- `FRAMEWORK-UPDATE-SYSTEM-QUICKSTART.md` - Quick start guide
+
+**Package Updates:**
+- Added `@anthropic-ai/sdk` dependency
+- Added 4 new npm scripts
+
+### In adf-cli Repository
+
+**Documentation:**
+- `.project/docs/FRAMEWORK-UPDATE-SYSTEM.md` - Complete system design
+- `.project/docs/FRAMEWORK-UPDATE-INTEGRATION.md` - This file
+
+---
+
+## 🔄 How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Upstream Frameworks (Git Repos)                            │
+│  • BMAD-METHOD                                              │
+│  • Spec-Kit (GitHub)                                        │
+│  • Context Engineering                                      │
+│  • PRPs Agentic Engineering                                 │
+└──────────────────┬──────────────────────────────────────────┘
+                   │
+                   │ Monitor (Daily via GitHub Actions)
+                   │ Or Manual (npm run check-updates)
+                   ↓
+┌─────────────────────────────────────────────────────────────┐
+│  AgentDevFramework Repository                               │
+│  • Git submodules detect new commits                        │
+│  • Creates update branch                                    │
+│  • Creates GitHub issue                                     │
+└──────────────────┬──────────────────────────────────────────┘
+                   │
+                   │ Trigger AI Analysis
+                   ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Claude AI Analysis                                         │
+│  • Analyzes diffs                                           │
+│  • Determines impact on adf-cli                             │
+│  • Provides specific recommendations                        │
+│  • Suggests code changes                                    │
+└──────────────────┬──────────────────────────────────────────┘
+                   │
+                   │ Generate Reports
+                   ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Decision & Implementation                                  │
+│  • Human reviews AI recommendations                         │
+│  • Decides which changes to adopt                          │
+│  • Updates adf-cli code                                    │
+│  • Tests, commits, publishes new version                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Usage
+
+### Option 1: Manual (Recommended for Start)
+
+```bash
+# 1. Go to AgentDevFramework
+cd D:\Documents\GitHub\AgentDevFramework
+
+# 2. Install dependencies (first time only)
+npm install
+
+# 3. Set API key
+export ANTHROPIC_API_KEY="your-key"
+
+# 4. Check for updates
+npm run check-updates
+
+# 5. If updates found, analyze them
+npm run update-and-analyze
+
+# 6. Review the report
+cat framework-analysis-report.md
+
+# 7. Update adf-cli based on recommendations
+cd ../adf-cli
+# Make changes...
+npm test
+# Commit, publish
+```
+
+### Option 2: Automated (GitHub Actions)
+
+**One-time setup:**
+```bash
+# 1. Add API key to GitHub secrets
+# Go to: https://github.com/your-username/AgentDevFramework/settings/secrets/actions
+# Add: ANTHROPIC_API_KEY = your-key
+
+# 2. Commit and push the workflow
+cd D:\Documents\GitHub\AgentDevFramework
+git add .github/workflows/monitor-framework-updates.yml
+git commit -m "feat: Add framework update monitoring system"
+git push
+```
+
+**Then it runs automatically:**
+- Daily at 2am UTC
+- Creates GitHub issues when updates detected
+- Runs AI analysis
+- You just review and decide
+
+---
+
+## 📊 AI Analysis Output
+
+The AI provides structured analysis for each framework update:
+
+```json
+{
+  "summary": "Added new DevOps Engineer persona and infrastructure testing",
+  "impactLevel": "High",
+  "affectsAdfCli": true,
+  "reason": "New persona requires agent definition in adf-cli",
+  "recommendedActions": [
+    "Add DevOps Engineer agent to lib/templates/shared/agents/",
+    "Update output-generators.js to include infrastructure testing",
+    "Add infrastructure testing questions to questions.js"
+  ],
+  "codeSuggestions": [
+    {
+      "file": "lib/templates/shared/agents/devops.md",
+      "change": "Create new DevOps Engineer agent",
+      "priority": "High",
+      "code": "# DevOps Engineer Agent\n\n## Role\n..."
+    }
+  ],
+  "breakingChanges": [],
+  "confidence": "High"
+}
+```
+
+---
+
+## 🎯 Decision Framework
+
+### When to Update adf-cli
+
+| Impact Level | Affects adf-cli | Action |
+|--------------|-----------------|--------|
+| **Critical** | Yes | ✅ Update immediately |
+| **Critical** | No | ⏸️ Review but may skip |
+| **High** | Yes | ✅ Plan to update soon |
+| **High** | No | ⏸️ Monitor |
+| **Medium** | Yes | 🤔 Consider updating |
+| **Medium** | No | ⏸️ Skip |
+| **Low** | Yes/No | ⏸️ Optional |
+| **None** | No | ❌ Skip |
+
+### Update Process
+
+**When AI recommends updates:**
+
+1. **Review Recommendations**
+   - Read the AI analysis report
+   - Understand what changed
+   - Evaluate impact on adf-cli
+
+2. **Create Feature Branch**
+   ```bash
+   cd D:\Documents\GitHub\adf-cli
+   git checkout -b feature/framework-update-YYYY-MM-DD
+   ```
+
+3. **Implement Changes**
+   - Follow code suggestions from AI
+   - Update relevant files
+   - Add new features if needed
+
+4. **Test Thoroughly**
+   ```bash
+   npm test
+   # All 57 tests should pass
+   # Add new tests for new features
+   ```
+
+5. **Update Documentation**
+   - Update CHANGELOG.md
+   - Update README if features changed
+   - Document new capabilities
+
+6. **Commit and Release**
+   ```bash
+   git add .
+   git commit -m "feat: Adopt [framework] updates
+
+   - [Change 1]
+   - [Change 2]
+
+   Based on framework update analysis YYYY-MM-DD"
+
+   # Bump version
+   npm version minor  # or major/patch
+
+   # Publish
+   npm publish
+   git push --tags
+   ```
+
+---
+
+## 📋 Real-World Example
+
+### Scenario: BMAD-METHOD adds DevOps persona
+
+**1. Detection:**
+```
+🔍 Checking for framework updates...
+📦 BMAD-METHOD: 2 new commits available
+   • Add DevOps Engineer persona
+   • Update testing methodology
+```
+
+**2. AI Analysis:**
+```json
+{
+  "impactLevel": "High",
+  "affectsAdfCli": true,
+  "recommendedActions": [
+    "Add devops.md to lib/templates/shared/agents/",
+    "Update questions.js with infrastructure questions"
+  ]
+}
+```
+
+**3. Implementation in adf-cli:**
+```bash
+# Create new agent
+cat > lib/templates/shared/agents/devops.md <<EOF
+# DevOps Engineer
+
+## Role
+Infrastructure automation and deployment specialist...
+EOF
+
+# Update questions
+# Edit lib/frameworks/questions.js
+# Add infrastructure testing questions
+
+# Test
+npm test
+
+# Commit
+git commit -m "feat: Add DevOps Engineer agent from BMAD-METHOD update"
+
+# Publish v0.4.0
+npm version minor
+npm publish
+```
+
+**4. Result:**
+- Users can now use DevOps agent
+- Infrastructure testing questions added
+- adf-cli stays current with methodology
+
+---
+
+## 🔐 Security & Best Practices
+
+**API Keys:**
+- ✅ Store in GitHub Secrets (for automation)
+- ✅ Store in .env file (for local)
+- ❌ NEVER commit to git
+
+**Review Before Merging:**
+- ✅ Always review AI recommendations
+- ✅ Don't blindly accept changes
+- ✅ Test thoroughly
+- ✅ Consider user impact
+
+**Version Management:**
+- Breaking changes → major version bump
+- New features → minor version bump
+- Bug fixes → patch version bump
+
+---
+
+## 📈 Monitoring Metrics
+
+Track these to measure system effectiveness:
+
+| Metric | Target |
+|--------|--------|
+| Detection time | < 24 hours |
+| AI accuracy | > 80% |
+| False positives | < 20% |
+| Review time | < 30 min |
+| Missed critical updates | 0 |
+
+---
+
+## 🛠️ Maintenance
+
+**Weekly:**
+- Run `npm run check-updates` manually
+- Review any open GitHub issues
+
+**Monthly:**
+- Review AI analysis accuracy
+- Adjust prompts if needed
+- Check for missed updates
+
+**As Needed:**
+- Update API key if changed
+- Adjust cron schedule if needed
+- Tune impact level thresholds
+
+---
+
+## 🎓 Training the Team
+
+**For Maintainers:**
+1. Read FRAMEWORK-UPDATE-SYSTEM-QUICKSTART.md
+2. Try manual workflow once
+3. Set up automation
+4. Practice decision-making with mock updates
+
+**For Contributors:**
+1. Understand the 4 frameworks
+2. Know where to find analysis reports
+3. Understand adf-cli architecture
+4. Follow update process
+
+---
+
+## ✅ Checklist
+
+**Setup Complete:**
+- [x] Scripts created in AgentDevFramework
+- [x] Dependencies added to package.json
+- [x] GitHub Actions workflow created
+- [x] Documentation written
+- [x] Scripts made executable
+
+**To Deploy:**
+- [x] Install dependencies: `npm install` ✅ Tested 2025-10-03
+- [ ] Set ANTHROPIC_API_KEY
+- [x] Test manual workflow: `npm run check-updates` ✅ Tested 2025-10-03
+- [ ] Set up GitHub Actions (optional)
+- [ ] Add to weekly routine
+
+**First Use:**
+- [x] Check for updates ✅ Detected 3 framework updates
+- [ ] Run AI analysis (requires API key)
+- [ ] Review report
+- [ ] Make first update to adf-cli
+- [ ] Document lessons learned
+
+---
+
+## 📚 Related Documentation
+
+**In AgentDevFramework:**
+- `FRAMEWORK-UPDATE-SYSTEM-QUICKSTART.md` - Quick start guide
+- `FRAMEWORK-UPDATE-SYSTEM-TEST-RESULTS.md` - Test validation ✅
+- `scripts/check-framework-updates.js` - Check script
+- `scripts/analyze-framework-updates.js` - Analysis script
+- `.github/workflows/monitor-framework-updates.yml` - Automation
+
+**In adf-cli:**
+- `.project/docs/FRAMEWORK-UPDATE-SYSTEM.md` - Full system design
+- `.project/docs/PROJECT-STRUCTURE-EXPLANATION.md` - Project relationship
+- `CHANGELOG.md` - Version history
+
+---
+
+## 🎯 Success Criteria
+
+**System is successful when:**
+- ✅ Framework updates detected within 24 hours
+- ✅ AI provides actionable recommendations
+- ✅ Impact assessment is 80%+ accurate
+- ✅ Human review takes < 30 minutes
+- ✅ Zero missed critical updates
+- ✅ adf-cli stays current with methodology
+
+---
+
+**Created:** 2025-10-03
+**Status:** ✅ Tested & Operational
+**Test Results:** See `AgentDevFramework/FRAMEWORK-UPDATE-SYSTEM-TEST-RESULTS.md`
+**Next Step:** Set ANTHROPIC_API_KEY and run AI analysis