create-byan-agent 2.0.1 → 2.1.0

package/install/DEPLOYMENT-GUIDE-V2.md

@@ -0,0 +1,431 @@
+# BYAN v2.0 Installer - Quick Deployment Guide
+
+**Version:** 2.0.0-alpha.1  
+**Status:** Ready to Deploy  
+**Date:** 2026-02-05
+
+---
+
+## ⚡ Quick Start
+
+### 1. Update Package Version
+
+```bash
+cd /home/yan/conception/install
+```
+
+Edit `package.json`:
+
+```json
+{
+  "name": "create-byan-agent",
+  "version": "2.0.0-alpha.1",  // ← UPDATE THIS
+  "description": "NPX installer for BYAN v2.0 - Agent creators with v2.0 runtime support",
+  "bin": {
+    "create-byan-agent": "bin/create-byan-agent-v2.js"  // ← POINT TO V2
+  }
+}
+```
+
+### 2. Update Executable Permissions
+
+```bash
+chmod +x bin/create-byan-agent-v2.js
+```
+
+### 3. Test Locally
+
+```bash
+cd /tmp
+mkdir test-project && cd test-project
+git init
+npm init -y
+
+# Test the installer
+node /home/yan/conception/install/bin/create-byan-agent-v2.js
+```
+
+### 4. Verify Installation
+
+After running installer, check:
+
+```bash
+# Check v2.0 runtime files
+ls -la src/
+ls -la __tests__/
+cat package.json | grep jest
+
+# Check platform files
+ls -la _bmad/bmb/agents/
+ls -la _bmad/bmb/workflows/
+
+# Run tests
+npm install
+npm test
+```
+
+Expected: All tests pass ✅
+
+### 5. Deploy to NPM (when ready)
+
+```bash
+cd /home/yan/conception/install
+
+# Login to npm (if not already)
+npm login
+
+# Publish
+npm publish --tag alpha
+```
+
+---
+
+## 🎯 What Changed
+
+### File Changes
+
+```
+install/
+├── bin/
+│   ├── create-byan-agent.js       (v1.0 - PRESERVED)
+│   └── create-byan-agent-v2.js    (v2.0 - NEW) ✨
+├── package.json                   (UPDATE: version, bin)
+├── test-installer-v2.sh           (NEW) ✨
+└── INSTALLER-V2-CHANGES.md        (NEW) ✨
+```
+
+### Required Updates
+
+**In `package.json`:**
+
+```diff
+{
+  "name": "create-byan-agent",
+- "version": "1.1.3",
++ "version": "2.0.0-alpha.1",
+- "description": "NPX installer for BYAN ecosystem...",
++ "description": "NPX installer for BYAN v2.0 - Agent creators with v2.0 runtime support",
+  "bin": {
+-   "create-byan-agent": "bin/create-byan-agent.js"
++   "create-byan-agent": "bin/create-byan-agent-v2.js"
+  }
+}
+```
+
+---
+
+## ✅ Pre-Deployment Checklist
+
+- [x] **Installer Created:** `create-byan-agent-v2.js` (492 lines)
+- [x] **Test Script Created:** `test-installer-v2.sh`
+- [x] **Documentation Created:** `INSTALLER-V2-CHANGES.md`
+- [ ] **Package Version Updated:** Change to `2.0.0-alpha.1`
+- [ ] **Bin Path Updated:** Point to `create-byan-agent-v2.js`
+- [ ] **Permissions Set:** `chmod +x` on new installer
+- [ ] **Local Test:** Run in clean test directory
+- [ ] **NPM Publish:** Deploy to registry
+
+---
+
+## 🧪 Testing Scenarios
+
+### Scenario 1: Brand New Project
+
+```bash
+cd /tmp
+mkdir new-project && cd new-project
+git init
+node /home/yan/conception/install/bin/create-byan-agent-v2.js
+```
+
+**Expected:**
+- Prompts for v2.0 installation
+- Creates `src/`, `__tests__/`, `package.json`
+- Creates `_bmad/bmb/` structure
+- 9/9 validation checks pass
+
+### Scenario 2: Existing Node Project
+
+```bash
+cd /tmp
+mkdir existing-project && cd existing-project
+git init
+npm init -y
+echo "console.log('existing')" > index.js
+node /home/yan/conception/install/bin/create-byan-agent-v2.js
+```
+
+**Expected:**
+- Merges into existing `package.json`
+- Preserves existing files
+- Adds Jest config
+- 9/9 validation checks pass
+
+### Scenario 3: Existing BYAN v1.0 Project
+
+```bash
+cd /tmp
+mkdir v1-project && cd v1-project
+mkdir -p _bmad/bmb/agents
+echo "# v1.0 config" > _bmad/bmb/config.yaml
+node /home/yan/conception/install/bin/create-byan-agent-v2.js
+```
+
+**Expected:**
+- Detects existing v1.0 installation
+- Offers to add v2.0 runtime
+- Preserves v1.0 config
+- Updates `byan_version` field
+
+---
+
+## 📦 What Gets Installed
+
+### v1.0 Only Mode (user declines v2.0)
+
+```
+project/
+└── _bmad/
+    └── bmb/
+        ├── agents/
+        │   ├── byan.md
+        │   ├── rachid.md
+        │   └── marc.md
+        ├── workflows/
+        │   └── byan/
+        ├── config.yaml
+        └── ...
+```
+
+### v2.0 Full Mode (user accepts v2.0)
+
+```
+project/
+├── _bmad/                   ← Platform (v1.0)
+│   └── bmb/
+│       ├── agents/
+│       ├── workflows/
+│       └── config.yaml
+├── src/                     ← Runtime (v2.0) ✨
+│   ├── core/
+│   │   ├── context/
+│   │   ├── cache/
+│   │   ├── dispatcher/
+│   │   ├── worker-pool/
+│   │   └── workflow/
+│   ├── observability/
+│   │   ├── logger/
+│   │   ├── metrics/
+│   │   └── dashboard/
+│   └── index.js
+├── __tests__/               ← Tests (v2.0) ✨
+│   ├── context.test.js
+│   ├── cache.test.js
+│   └── ... (9 files)
+└── package.json             ← Updated with Jest ✨
+```
+
+---
+
+## 🚨 Known Issues / Limitations
+
+### None Currently
+
+All validation checks pass. The installer is ready for deployment.
+
+### Future Enhancements
+
+- Add `--dry-run` flag
+- Add `--skip-v2` flag for CI/CD
+- Add uninstall command
+- Add update command (v1.0 → v2.0)
+
+---
+
+## 📊 Deployment Decision Matrix
+
+| Scenario | Action | Command |
+|----------|--------|---------|
+| **Alpha Test** | Publish with `@alpha` tag | `npm publish --tag alpha` |
+| **Beta Test** | Publish with `@beta` tag | `npm publish --tag beta` |
+| **Production** | Publish with `@latest` tag | `npm publish` |
+| **Rollback** | Revert to v1.1.3 | `npm dist-tag add create-byan-agent@1.1.3 latest` |
+
+**Recommendation:** Start with `--tag alpha` for initial testing.
+
+---
+
+## 🎬 Deployment Commands
+
+### Option A: Alpha Release (Recommended)
+
+```bash
+cd /home/yan/conception/install
+
+# 1. Update package.json to 2.0.0-alpha.1
+# 2. Update bin to point to create-byan-agent-v2.js
+# 3. Commit changes
+
+git add .
+git commit -m "feat: add BYAN v2.0 installer with runtime support
+
+- Add create-byan-agent-v2.js (492 lines)
+- Support v2.0 runtime (src/, __tests__)
+- Smart package.json merging
+- Backward compatible with v1.0
+- 9 validation checks
+- Version detection and tracking
+
+Mantras: IA-24, #37, IA-1"
+
+# 4. Publish to npm
+npm publish --tag alpha
+
+# 5. Test installation
+npx create-byan-agent@alpha
+```
+
+### Option B: Direct Production (Not Recommended Yet)
+
+```bash
+npm publish
+```
+
+---
+
+## 🔍 Post-Deployment Verification
+
+### 1. Test NPM Installation
+
+```bash
+# Install globally
+npm install -g create-byan-agent@alpha
+
+# Verify version
+create-byan-agent --version
+# Should show: 2.0.0-alpha.1
+
+# Test in new project
+cd /tmp
+mkdir test-npm && cd test-npm
+git init
+create-byan-agent
+```
+
+### 2. Test NPX Execution
+
+```bash
+cd /tmp
+mkdir test-npx && cd test-npx
+git init
+npx create-byan-agent@alpha
+```
+
+### 3. Verify Files Installed
+
+```bash
+ls -la src/
+ls -la __tests__/
+ls -la _bmad/bmb/
+cat package.json | grep jest
+```
+
+### 4. Run Tests
+
+```bash
+npm install
+npm test
+```
+
+**Expected:** All tests pass (364 tests)
+
+---
+
+## 📞 Rollback Plan
+
+If issues arise:
+
+```bash
+# Revert to v1.1.3
+cd /home/yan/conception/install
+
+# Option 1: Unpublish alpha (if within 72 hours)
+npm unpublish create-byan-agent@2.0.0-alpha.1
+
+# Option 2: Make v1.1.3 the latest again
+npm dist-tag add create-byan-agent@1.1.3 latest
+
+# Option 3: Publish patch version with fix
+# (Update code, bump to 2.0.0-alpha.2, republish)
+```
+
+---
+
+## 🎉 Success Criteria
+
+Installation is successful if:
+
+- ✅ Installer runs without errors
+- ✅ User can choose v1.0 or v2.0
+- ✅ Files copied to correct locations
+- ✅ package.json updated correctly
+- ✅ 9/9 validation checks pass
+- ✅ `npm test` runs successfully
+- ✅ Entry point can be required
+- ✅ No conflicts with existing files
+
+---
+
+## 📝 Next Steps After Deployment
+
+1. **Monitor npm downloads:**
+   ```bash
+   npm info create-byan-agent
+   ```
+
+2. **Gather feedback from alpha testers**
+
+3. **Fix any reported issues**
+
+4. **Promote to beta:**
+   ```bash
+   npm dist-tag add create-byan-agent@2.0.0-alpha.1 beta
+   ```
+
+5. **Eventually promote to latest:**
+   ```bash
+   npm dist-tag add create-byan-agent@2.0.0-alpha.1 latest
+   ```
+
+---
+
+## 📚 Documentation Updates Needed
+
+After deployment, update:
+
+1. **Main README.md:**
+   - Add v2.0 installation instructions
+   - Show v1.0 vs v2.0 comparison
+   - Update examples
+
+2. **CHANGELOG.md:**
+   - Document v2.0 changes
+   - List new features
+   - Note breaking changes (none)
+
+3. **GUIDE-UTILISATION.md:**
+   - Add v2.0 usage guide
+   - Show entry point usage
+   - Add test examples
+
+---
+
+**Status:** ✅ **READY FOR ALPHA DEPLOYMENT**
+
+**Next Action:** Update `package.json` and publish to npm with `--tag alpha`
+
+---
+
+*Deployment guide prepared by Amelia (Dev Agent)*  
+*Date: 2026-02-05*  
+*BYAN v2.0.0-alpha.1*

package/install/DOCS-INDEX.md

@@ -0,0 +1,261 @@
+# BYAN Documentation Index
+
+## 📚 Documentation Versions
+
+### For NPM Package Publication
+
+**Primary README (for npmjs.com):**
+- [`README-NPM-PUBLISH.md`](./README-NPM-PUBLISH.md) - **USE THIS FOR NPM**
+  - Concise version (< 6000 chars)
+  - English only
+  - Quick start focused
+  - Essential info only
+
+**Extended README (for GitHub):**
+- [`README-NPM.md`](./README-NPM.md) - **USE THIS FOR GITHUB README**
+  - Detailed French version
+  - Complete examples
+  - All use cases
+  - Advanced configuration
+
+**Current README (to be replaced):**
+- [`README.md`](./README.md) - Legacy v1.1.1 documentation
+  - Will be replaced by README-NPM-PUBLISH.md
+
+---
+
+## 🎯 Publishing Guide
+
+### Step 1: Prepare Package
+
+```bash
+cd install/
+
+# Copy the NPM-ready README
+cp README-NPM-PUBLISH.md README.md
+
+# Verify package.json
+cat package.json | grep "version\|description"
+```
+
+### Step 2: Verify Content
+
+```bash
+# Check what will be published
+npm pack --dry-run
+
+# Should include:
+# - bin/create-byan-agent-v2.js
+# - templates/
+# - README.md (the NPM version)
+# - CHANGELOG.md
+# - LICENSE
+```
+
+### Step 3: Test Locally
+
+```bash
+# Test installation
+npm pack
+npm install -g create-byan-agent-2.0.0-alpha.1.tgz
+
+# Test execution
+create-byan-agent --version
+```
+
+### Step 4: Publish
+
+```bash
+# Login to npm (if needed)
+npm login
+
+# Publish alpha version
+npm publish --tag alpha
+
+# Or publish stable
+npm publish
+```
+
+---
+
+## 📖 Documentation Files Explained
+
+### User-Facing Documentation
+
+| File | Purpose | Audience | Language |
+|------|---------|----------|----------|
+| `README-NPM-PUBLISH.md` | NPM package page | All users | EN |
+| `README-NPM.md` | GitHub detailed guide | All users | FR |
+| `QUICKSTART.md` | 5-minute setup | Experienced devs | EN |
+| `GUIDE-INSTALLATION-BYAN-SIMPLE.md` | Beginner guide | First-time users | FR |
+
+### Technical Documentation
+
+| File | Purpose | Audience |
+|------|---------|----------|
+| `API-BYAN-V2.md` | API reference | Developers |
+| `DEPLOYMENT-GUIDE-V2.md` | Deployment process | Maintainers |
+| `INSTALLER-V2-CHANGES.md` | v2 changes | Upgraders |
+
+### Internal Documentation
+
+| File | Purpose |
+|------|---------|
+| `FINAL-REPORT.md` | Development summary |
+| `RESUME-EXECUTIF-YAN.md` | Executive summary |
+| `README-V2-INDEX.md` | v2 documentation index |
+
+---
+
+## 🔄 Update Workflow
+
+### When to Update Each README
+
+**Update README-NPM-PUBLISH.md when:**
+- ✅ New major features
+- ✅ Installation process changes
+- ✅ Breaking API changes
+- ✅ New use cases
+- ❌ Minor bug fixes (use CHANGELOG)
+- ❌ Internal refactoring
+
+**Update README-NPM.md when:**
+- ✅ New concepts to explain
+- ✅ Advanced usage examples
+- ✅ Configuration options added
+- ✅ Troubleshooting sections
+- ✅ FAQ additions
+
+**Update README.md (after publishing) when:**
+- ✅ New release published
+- ✅ Copy from README-NPM-PUBLISH.md
+
+---
+
+## 📝 Documentation Standards
+
+### README-NPM-PUBLISH.md Guidelines
+
+**Length:** < 6000 characters (NPM limit)
+
+**Structure:**
+1. Quick Start (< 500 chars)
+2. What is BYAN? (< 800 chars)
+3. Installation (< 500 chars)
+4. Create First Agent (< 1000 chars)
+5. Examples (< 1000 chars)
+6. Key Concepts (< 1500 chars)
+7. Support & Links (< 700 chars)
+
+**Style:**
+- ✅ Direct, action-oriented
+- ✅ Code examples first
+- ✅ Bullet points over paragraphs
+- ✅ Emojis for quick scanning
+- ❌ Long explanations
+- ❌ Marketing language
+
+### README-NPM.md Guidelines
+
+**No length limit** - Be comprehensive
+
+**Structure:**
+1. Detailed introduction
+2. Step-by-step tutorials
+3. Complete examples
+4. All concepts explained
+5. Advanced configuration
+6. Troubleshooting
+7. FAQ
+
+**Style:**
+- ✅ Educational tone
+- ✅ Complete examples
+- ✅ Visual aids (code blocks)
+- ✅ Multiple languages (FR primary)
+
+---
+
+## 🌐 Localization
+
+### Current Languages
+
+- **English**: README-NPM-PUBLISH.md
+- **Français**: README-NPM.md
+
+### Adding New Language
+
+1. Copy README-NPM.md
+2. Rename to README-NPM-{lang}.md
+3. Translate content
+4. Update package.json:
+   ```json
+   "keywords": ["...", "french-docs", "documentation-fr"]
+   ```
+5. Add link to DOCS-INDEX.md
+
+---
+
+## 🔍 SEO & Discoverability
+
+### NPM Keywords (in package.json)
+
+Current keywords optimized for:
+- ✅ AI agent creation
+- ✅ GitHub Copilot integration
+- ✅ Developer automation
+- ✅ Code generation tools
+- ✅ Conversational AI
+
+### GitHub Topics
+
+Add these to repository:
+- `ai-agents`
+- `github-copilot`
+- `code-generation`
+- `developer-tools`
+- `intelligent-assistant`
+- `merise-agile`
+- `tdd`
+
+---
+
+## 📊 Version History
+
+| Version | README Used | Changes |
+|---------|-------------|---------|
+| 1.1.1 | README.md (legacy) | Original BYAN |
+| 2.0.0-alpha.1 | README-NPM-PUBLISH.md | v2 architecture |
+| 2.0.0 | README-NPM-PUBLISH.md | Stable v2 release |
+
+---
+
+## ✅ Pre-Publication Checklist
+
+Before publishing to NPM, verify:
+
+- [ ] README-NPM-PUBLISH.md copied to README.md
+- [ ] package.json version bumped
+- [ ] CHANGELOG.md updated
+- [ ] All examples tested
+- [ ] Links point to correct URLs
+- [ ] Keywords optimized
+- [ ] License file present
+- [ ] No sensitive data in files
+- [ ] Tests passing (npm test)
+- [ ] Build successful (npm pack)
+
+---
+
+## 🔗 Related Documentation
+
+- [BYAN v2 Full Guide](../../README-BYAN-V2.md)
+- [API Reference](../../API-BYAN-V2.md)
+- [Deployment Checklist](../../DEPLOYMENT-CHECKLIST.md)
+- [Quick Reference Card](../../QUICK-REFERENCE-CARD.md)
+
+---
+
+**Maintained by:** BYAN Core Team  
+**Last Updated:** 2026-02-06  
+**Next Review:** Before v2.0.0 stable release