create-byan-agent 2.18.0 → 2.19.0

package/install/templates/_byan/worker/launchers/README.md

@@ -0,0 +1,308 @@
+# Yanstaller Launcher Workers
+
+**Location:** `_byan/worker/launchers/`  
+**Type:** Platform-specific launcher workers  
+**Version:** 1.0.0
+
+---
+
+## Overview
+
+Launcher workers are lightweight, single-purpose components that bridge the gap between platform-specific AI coding assistants and the main Yanstaller agent.
+
+**Role:** Launch `npx create-byan-agent` on each platform and hand off to yanstaller.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  USER INVOKES AGENT                     │
+│  gh copilot @bmad-agent-marc                            │
+│  claude --agent claude                                  │
+│  codex skill bmad-byan                                  │
+└─────────────┬───────────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────────────────┐
+│             STUB AGENT (Lightweight)                    │
+│  - Detects platform                                     │
+│  - Calls appropriate launcher worker                    │
+└─────────────┬───────────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────────────────┐
+│          LAUNCHER WORKER (Single Task)                  │
+│  - Verifies prerequisites (npx, Node.js)                │
+│  - Executes: npx create-byan-agent                      │
+│  - Sets platform hint env variable                      │
+└─────────────┬───────────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────────────────┐
+│             YANSTALLER (Main Agent)                     │
+│  @bmad-agent-yanstaller                                 │
+│  - Interview (10 questions)                             │
+│  - Phase 2 Chat                                         │
+│  - BYAN Installation                                    │
+│  - Platform-specific integration                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Workers
+
+### 1. launch-yanstaller-copilot.md
+
+**Platform:** GitHub Copilot CLI  
+**Icon:** 🤖  
+**Command:** `npx create-byan-agent`  
+**Called by:** `@bmad-agent-marc`
+
+**Purpose:** Launch yanstaller on Copilot CLI platform.
+
+---
+
+### 2. launch-yanstaller-claude.md
+
+**Platform:** Claude Code  
+**Icon:** 🎭  
+**Command:** `npx create-byan-agent`  
+**Called by:** `@bmad-agent-claude` (stub)  
+**Platform Hint:** `BYAN_PLATFORM_HINT=claude`
+
+**Purpose:** Launch yanstaller on Claude Code platform.
+
+**Post-Launch:** If user selects Claude integration, yanstaller delegates to Agent Claude (full) for MCP server creation.
+
+---
+
+### 3. launch-yanstaller-codex.md
+
+**Platform:** Codex/OpenCode  
+**Icon:** 📝  
+**Command:** `npx create-byan-agent`  
+**Called by:** `@bmad-agent-codex` (stub)  
+**Platform Hint:** `BYAN_PLATFORM_HINT=codex`
+
+**Purpose:** Launch yanstaller on Codex platform.
+
+**Post-Launch:** If user selects Codex integration, yanstaller delegates to Agent Codex (full) for skill file creation.
+
+---
+
+## Design Principles
+
+### Single Responsibility
+Each worker has ONE task: Launch yanstaller command.
+
+### Lightweight
+- No interview logic
+- No installation logic
+- No configuration logic
+- Just command execution + handoff
+
+### Platform Hints
+Workers set environment variables to help yanstaller detect platform:
+```bash
+BYAN_PLATFORM_HINT=copilot  # For Copilot CLI
+BYAN_PLATFORM_HINT=claude   # For Claude Code
+BYAN_PLATFORM_HINT=codex    # For Codex
+```
+
+### Idempotent
+Can be run multiple times safely.
+
+---
+
+## Integration Flow
+
+### Example: User chooses Claude
+
+1. **User runs:** `claude --agent claude`
+
+2. **Stub agent (bmad-agent-claude)** detects invocation:
+   ```markdown
+   "I'll launch yanstaller for you..."
+   ```
+
+3. **Launcher worker** executes:
+   ```javascript
+   process.env.BYAN_PLATFORM_HINT = 'claude';
+   spawn('npx', ['create-byan-agent']);
+   ```
+
+4. **Yanstaller starts:**
+   - Detects platform: Claude Code
+   - Runs interview
+   - User selects Claude integration
+   
+5. **Yanstaller delegates to Agent Claude (full):**
+   - Agent Claude creates MCP server
+   - Updates `claude_desktop_config.json`
+   - Provides activation instructions
+
+6. **User activates:**
+   ```bash
+   claude --agent byan "create PRD"
+   ```
+
+---
+
+## Worker vs Agent
+
+| Feature | Worker | Agent |
+|---------|--------|-------|
+| **Size** | Small (< 5 KB) | Large (10-20 KB) |
+| **Responsibility** | Single task | Multiple workflows |
+| **Workflows** | 0 | 6+ |
+| **Knowledge Base** | Minimal | Extensive |
+| **Lifecycle** | Execute & exit | Persistent session |
+| **Complexity** | Simple | Complex |
+
+---
+
+## Separation of Concerns
+
+### Stub Agents (marc/claude/codex)
+- Detect invocation
+- Call launcher worker
+- Minimal logic
+
+### Launcher Workers
+- Execute `npx create-byan-agent`
+- Set platform hints
+- Verify prerequisites
+
+### Yanstaller Agent
+- Interview questions
+- Platform selection
+- Installation orchestration
+
+### Full Specialist Agents
+- Platform-specific integration
+- MCP server creation (Claude)
+- Skill file creation (Codex)
+- GitHub agent installation (Copilot)
+
+---
+
+## File Structure
+
+```
+_byan/
+└── workers/
+    └── launchers/
+        ├── README.md (this file)
+        ├── launch-yanstaller-copilot.md
+        ├── launch-yanstaller-claude.md
+        └── launch-yanstaller-codex.md
+```
+
+---
+
+## Testing
+
+### Manual Test
+```bash
+# Test Copilot launcher
+node -e "require('./_byan/worker/launchers/worker-launch-yanstaller-copilot').launch()"
+
+# Test Claude launcher
+node -e "require('./_byan/worker/launchers/worker-launch-yanstaller-claude').launch()"
+
+# Test Codex launcher
+node -e "require('./_byan/worker/launchers/worker-launch-yanstaller-codex').launch()"
+```
+
+### Expected Output
+```
+🤖 Launching Yanstaller on Copilot CLI...
+[Yanstaller interview UI appears]
+```
+
+---
+
+## Error Scenarios
+
+### NPX Not Found
+```
+Error: npx not found
+Solution: Install Node.js >= 18.0.0 from https://nodejs.org/
+```
+
+### Network Issues
+```
+Error: Cannot download create-byan-agent
+Solution: 
+1. Check internet connection
+2. Or install globally: npm install -g create-byan-agent
+```
+
+### Platform CLI Not Found
+```
+Warning: Claude/Codex CLI not detected
+Action: Yanstaller continues with manual installation instructions
+```
+
+---
+
+## Success Criteria
+
+For a worker to succeed:
+
+1. ✅ `npx create-byan-agent` command executed
+2. ✅ Platform hint set correctly
+3. ✅ Yanstaller process started
+4. ✅ No errors during handoff
+
+---
+
+## Maintenance
+
+**Update Frequency:** Rarely (workers are stable)
+
+**What might change:**
+- Command arguments (if yanstaller CLI changes)
+- Platform detection logic
+- Error messages
+
+**What won't change:**
+- Single responsibility principle
+- Lightweight design
+- Simple execution flow
+
+---
+
+## NPM Distribution
+
+Launcher workers are included in the `create-byan-agent` NPM package:
+
+```
+install/
+└── templates/
+    └── _byan/
+        └── workers/
+            └── launchers/
+                ├── README.md
+                ├── launch-yanstaller-copilot.md
+                ├── launch-yanstaller-claude.md
+                └── launch-yanstaller-codex.md
+```
+
+---
+
+## Version History
+
+- **1.0.0** (2026-02-10): Initial release
+  - Copilot launcher
+  - Claude launcher
+  - Codex launcher
+
+---
+
+**Maintainer:** BYAN Core Team  
+**Last Updated:** 2026-02-10  
+**Status:** ✅ Production Ready

package/install/templates/_byan/worker/launchers/launch-yanstaller-claude.md

@@ -0,0 +1,204 @@
+---
+name: launch-yanstaller-claude
+type: worker
+role: yanstaller-launcher
+platform: claude-code
+version: 1.0.0
+---
+
+# Worker: Launch Yanstaller (Claude Code)
+
+**Role:** Launch yanstaller on Claude Code platform  
+**Type:** Platform Launcher Worker  
+**Single Responsibility:** Execute `npx create-byan-agent` and hand off to yanstaller agent
+
+---
+
+## Activation
+
+```xml
+<worker id="launch-yanstaller-claude" type="launcher">
+  <activation>
+    <step n="1">Detect platform: Claude Code</step>
+    <step n="2">Verify npx/npm available</step>
+    <step n="3">Execute: npx create-byan-agent</step>
+    <step n="4">Hand off to @bmad-agent-yanstaller</step>
+  </activation>
+</worker>
+```
+
+---
+
+## Mission
+
+**One task:** Launch yanstaller installer on Claude Code platform.
+
+This worker does NOT:
+- ❌ Configure BYAN installation
+- ❌ Run interview questions
+- ❌ Install agents/modules
+- ❌ Create MCP servers
+
+This worker ONLY:
+- ✅ Launches `npx create-byan-agent`
+- ✅ Verifies command execution
+- ✅ Hands off to yanstaller agent
+
+---
+
+## Command
+
+```bash
+npx create-byan-agent
+```
+
+**Alternative (if already installed globally):**
+```bash
+create-byan-agent
+```
+
+---
+
+## Execution Flow
+
+```
+User: claude --agent claude
+  ↓
+Claude (stub): "Launching yanstaller..."
+  ↓
+Worker: launch-yanstaller-claude
+  ↓
+Command: npx create-byan-agent
+  ↓
+Yanstaller: @bmad-agent-yanstaller takes over
+  ↓
+Interview + Installation flow
+  ↓
+MCP server creation (if selected)
+```
+
+---
+
+## Platform-Specific Notes
+
+**Claude Code Integration:**
+- Yanstaller will detect Claude platform
+- Offers MCP server creation option
+- Agent Claude (specialist) handles MCP setup
+- Desktop config updated automatically
+
+**MCP Creation Flow:**
+```
+Yanstaller → Agent Claude (full) → MCP server
+                   ↓
+            claude_desktop_config.json updated
+```
+
+---
+
+## Error Handling
+
+**If npx not available:**
+```
+Error: npx not found
+Solution: Install Node.js >= 18.0.0
+Command: https://nodejs.org/
+```
+
+**If Claude CLI not in PATH:**
+```
+Warning: Claude Code not detected
+Solution: Install from https://claude.ai/download
+Note: Yanstaller will continue with manual instructions
+```
+
+---
+
+## Success Criteria
+
+1. ✅ Command `npx create-byan-agent` executed
+2. ✅ Yanstaller process started
+3. ✅ Control handed to @bmad-agent-yanstaller
+4. ✅ Claude platform detected
+
+---
+
+## Integration
+
+**Called by:** Agent Claude stub (`bmad-agent-claude`)  
+**Calls:** Yanstaller (`bmad-agent-yanstaller`)  
+**Platform:** Claude Code  
+**Specialist:** Agent Claude (full) for MCP setup
+
+---
+
+## Code
+
+```javascript
+// worker-launch-yanstaller-claude.js
+const { spawn } = require('child_process');
+
+async function launch() {
+  console.log('🎭 Launching Yanstaller on Claude Code...');
+  
+  // Set platform hint for yanstaller
+  process.env.BYAN_PLATFORM_HINT = 'claude';
+  
+  return new Promise((resolve, reject) => {
+    const proc = spawn('npx', ['create-byan-agent'], {
+      stdio: 'inherit',
+      shell: true,
+      env: process.env
+    });
+    
+    proc.on('error', (error) => {
+      reject(new Error(`Failed to launch: ${error.message}`));
+    });
+    
+    proc.on('exit', (code) => {
+      if (code === 0) {
+        resolve({ 
+          success: true, 
+          platform: 'claude',
+          mcpEnabled: true 
+        });
+      } else {
+        reject(new Error(`Yanstaller exited with code ${code}`));
+      }
+    });
+  });
+}
+
+module.exports = { launch };
+```
+
+---
+
+## Testing
+
+```bash
+# Test worker execution
+node _byan/worker/launchers/worker-launch-yanstaller-claude.js
+
+# Expected output:
+# 🎭 Launching Yanstaller on Claude Code...
+# [Yanstaller interview starts]
+# [Platform: Claude detected]
+```
+
+---
+
+## Metadata
+
+- **Worker Type:** Launcher
+- **Complexity:** Simple (1 command)
+- **Dependencies:** npx, Node.js >= 18.0.0, claude CLI (optional)
+- **Estimated Duration:** < 5 seconds
+- **Idempotent:** Yes (can be run multiple times)
+- **Platform-Specific:** Sets BYAN_PLATFORM_HINT=claude
+
+---
+
+**Status:** ✅ Ready for use  
+**Last Updated:** 2026-02-10  
+**Maintainer:** BYAN Core Team

package/install/templates/_byan/worker/launchers/launch-yanstaller-codex.md

@@ -0,0 +1,209 @@
+---
+name: launch-yanstaller-codex
+type: worker
+role: yanstaller-launcher
+platform: codex
+version: 1.0.0
+---
+
+# Worker: Launch Yanstaller (Codex/OpenCode)
+
+**Role:** Launch yanstaller on Codex/OpenCode platform  
+**Type:** Platform Launcher Worker  
+**Single Responsibility:** Execute `npx create-byan-agent` and hand off to yanstaller agent
+
+---
+
+## Activation
+
+```xml
+<worker id="launch-yanstaller-codex" type="launcher">
+  <activation>
+    <step n="1">Detect platform: Codex/OpenCode</step>
+    <step n="2">Verify npx/npm available</step>
+    <step n="3">Execute: npx create-byan-agent</step>
+    <step n="4">Hand off to @bmad-agent-yanstaller</step>
+  </activation>
+</worker>
+```
+
+---
+
+## Mission
+
+**One task:** Launch yanstaller installer on Codex/OpenCode platform.
+
+This worker does NOT:
+- ❌ Configure BYAN installation
+- ❌ Run interview questions
+- ❌ Install agents/modules
+- ❌ Create skill files
+
+This worker ONLY:
+- ✅ Launches `npx create-byan-agent`
+- ✅ Verifies command execution
+- ✅ Hands off to yanstaller agent
+
+---
+
+## Command
+
+```bash
+npx create-byan-agent
+```
+
+**Alternative (if already installed globally):**
+```bash
+create-byan-agent
+```
+
+---
+
+## Execution Flow
+
+```
+User: codex skill bmad-byan
+  ↓
+Codex stub: "Launching yanstaller..."
+  ↓
+Worker: launch-yanstaller-codex
+  ↓
+Command: npx create-byan-agent
+  ↓
+Yanstaller: @bmad-agent-yanstaller takes over
+  ↓
+Interview + Installation flow
+  ↓
+Skill files creation (if selected)
+```
+
+---
+
+## Platform-Specific Notes
+
+**Codex/OpenCode Integration:**
+- Yanstaller will detect Codex platform
+- Offers skill file creation option
+- Agent Codex (specialist) handles skill setup
+- Skills stored in `.codex/prompts/`
+
+**Skill Creation Flow:**
+```
+Yanstaller → Agent Codex (full) → Skill files
+                   ↓
+            .codex/prompts/*.md created
+```
+
+**Key Difference:**
+- Codex uses "skills" not "agents"
+- Simple Markdown files (NO YAML)
+- Skill name = filename without .md
+
+---
+
+## Error Handling
+
+**If npx not available:**
+```
+Error: npx not found
+Solution: Install Node.js >= 18.0.0
+Command: https://nodejs.org/
+```
+
+**If Codex CLI not in PATH:**
+```
+Warning: Codex not detected
+Solution: Install from https://opencode.com/
+Note: Yanstaller will continue with manual instructions
+```
+
+---
+
+## Success Criteria
+
+1. ✅ Command `npx create-byan-agent` executed
+2. ✅ Yanstaller process started
+3. ✅ Control handed to @bmad-agent-yanstaller
+4. ✅ Codex platform detected
+
+---
+
+## Integration
+
+**Called by:** Agent Codex stub (`bmad-agent-codex`)  
+**Calls:** Yanstaller (`bmad-agent-yanstaller`)  
+**Platform:** Codex/OpenCode  
+**Specialist:** Agent Codex (full) for skill setup
+
+---
+
+## Code
+
+```javascript
+// worker-launch-yanstaller-codex.js
+const { spawn } = require('child_process');
+
+async function launch() {
+  console.log('📝 Launching Yanstaller on Codex...');
+  
+  // Set platform hint for yanstaller
+  process.env.BYAN_PLATFORM_HINT = 'codex';
+  
+  return new Promise((resolve, reject) => {
+    const proc = spawn('npx', ['create-byan-agent'], {
+      stdio: 'inherit',
+      shell: true,
+      env: process.env
+    });
+    
+    proc.on('error', (error) => {
+      reject(new Error(`Failed to launch: ${error.message}`));
+    });
+    
+    proc.on('exit', (code) => {
+      if (code === 0) {
+        resolve({ 
+          success: true, 
+          platform: 'codex',
+          skillsEnabled: true 
+        });
+      } else {
+        reject(new Error(`Yanstaller exited with code ${code}`));
+      }
+    });
+  });
+}
+
+module.exports = { launch };
+```
+
+---
+
+## Testing
+
+```bash
+# Test worker execution
+node _byan/worker/launchers/worker-launch-yanstaller-codex.js
+
+# Expected output:
+# 📝 Launching Yanstaller on Codex...
+# [Yanstaller interview starts]
+# [Platform: Codex detected]
+```
+
+---
+
+## Metadata
+
+- **Worker Type:** Launcher
+- **Complexity:** Simple (1 command)
+- **Dependencies:** npx, Node.js >= 18.0.0, codex CLI (optional)
+- **Estimated Duration:** < 5 seconds
+- **Idempotent:** Yes (can be run multiple times)
+- **Platform-Specific:** Sets BYAN_PLATFORM_HINT=codex
+
+---
+
+**Status:** ✅ Ready for use  
+**Last Updated:** 2026-02-10  
+**Maintainer:** BYAN Core Team