c-breakout-claude 1.0.0

package/docs/quickstart.md

@@ -0,0 +1,268 @@
+# C-Breakout Orchestrate Mode - Quick Start Guide
+
+## What is Orchestrate Mode?
+
+An intelligent project orchestration system that:
+- **Analyzes** your project and breaks it into tasks
+- **Classifies** tasks by type (planner, dev, deploy)
+- **Assigns** specialized agents with minimal tools
+- **Saves 43-50%** on tokens vs standard distribute mode
+
+## When to Use It
+
+✅ **Use orchestrate for:**
+- Complex projects (10+ tasks)
+- Full features (planning → development → deployment)
+- Multi-file changes
+- Projects requiring research + implementation
+
+❌ **Don't use orchestrate for:**
+- Simple single tasks (use standard `/c-breakout distribute`)
+- Pure calculation tasks (too much overhead)
+- Quick file summaries (use `/c-breakout summarize`)
+
+## Basic Usage
+
+```bash
+/c-breakout orchestrate "Implement user authentication system"
+```
+
+That's it! The orchestrator will:
+1. Analyze your project
+2. Create specialized agents
+3. Execute in coordinated waves
+4. Aggregate results
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────────────────────────┐
+│   ORCHESTRATOR (Sonnet)             │
+│   • Reads project files             │
+│   • Creates work breakdown          │
+│   • Classifies tasks                │
+│   • Monitors execution              │
+└─────────────────┬───────────────────┘
+                  │
+        ┌─────────┼──────────┐
+        ▼         ▼          ▼
+    ┌────────┐ ┌──────┐ ┌─────────┐
+    │PLANNER │ │ DEV  │ │ DEPLOY  │
+    │agents  │ │agents│ │ agents  │
+    └────────┘ └──────┘ └─────────┘
+```
+
+### Agent Types
+
+| Type | Tools | Use For | Overhead |
+|------|-------|---------|----------|
+| **PLANNER** | Read, Grep, WebSearch | Research, analysis, exploration | ~12K tokens |
+| **DEV** | Read, Write, Edit, Bash | Implementation, testing | ~10K tokens |
+| **DEPLOY** | Bash, Read | Running scripts, deployment | ~8K tokens |
+
+### Execution Waves
+
+Tasks execute in waves based on dependencies:
+
+```
+Wave 1: [P001, P002, P003]  ← All planner tasks (parallel)
+         ↓
+Wave 2: [D001, D002, D003]  ← Dev tasks blocked by planners (parallel)
+         ↓
+Wave 3: [DPL001]            ← Deploy task blocked by dev (sequential)
+```
+
+## Example Scenarios
+
+### Scenario 1: Full Feature Implementation
+
+```bash
+/c-breakout orchestrate "Add user profile management with CRUD operations"
+```
+
+**What happens:**
+1. Orchestrator reads `src/` to understand current structure
+2. Creates plan:
+   - PLANNER: Research current user model
+   - PLANNER: Analyze API patterns
+   - DEV: Create user profile model
+   - DEV: Implement CRUD endpoints
+   - DEV: Write tests
+   - DEPLOY: Run migrations
+3. Launches 6 specialized agents
+4. Reports results
+
+**Cost:** ~$0.60 (vs $1.20 without orchestrate)
+
+### Scenario 2: Refactoring Project
+
+```bash
+/c-breakout orchestrate "Refactor authentication to use JWT tokens"
+```
+
+**Plan:**
+- PLANNER agents: Analyze current auth, research JWT best practices
+- DEV agents: Implement JWT service, update endpoints, update tests
+- DEPLOY agents: Update environment configs, run migrations
+
+### Scenario 3: Full Stack Feature
+
+```bash
+/c-breakout orchestrate "Add real-time notifications with WebSocket support"
+```
+
+**Plan:**
+- PLANNER: Research WebSocket libraries, analyze current architecture
+- DEV: Implement WebSocket server, create notification service, add client handlers, write tests
+- DEPLOY: Update server configs, deploy with new dependencies
+
+## Cost Comparison
+
+### 100-Task Project
+
+| Method | Token Overhead | Cost (Haiku) | Savings |
+|--------|----------------|--------------|---------|
+| No orchestrator | 1,900,000 | $1.52 | Baseline |
+| **With orchestrator** | **1,074,000** | **$0.86** | **43.5%** |
+
+### Why It's Cheaper
+
+- **Full context agents:** 19K tokens each (includes all skills, tools)
+- **Specialized agents:** 8-12K tokens (only tools they need)
+- **Orchestrator overhead:** ~74K tokens (one-time cost)
+
+## Monitoring Progress
+
+Check status anytime:
+
+```bash
+/c-breakout status
+```
+
+Output:
+```
+=== C-Breakout Status ===
+Run ID: 20260131_152030
+Mode: orchestrate
+
+Wave 2/3 executing...
+Progress: 15/25 agents (60%)
+
+| Agent | Type | Status | Task |
+|-------|------|--------|------|
+| P001 | planner | completed ✓ | Research auth patterns |
+| P002 | planner | completed ✓ | Analyze current code |
+| D001 | dev | running | Implement JWT service |
+| D002 | dev | running | Update endpoints |
+| D003 | dev | pending | Write tests |
+```
+
+## Getting Results
+
+```bash
+/c-breakout results
+```
+
+See aggregated results by agent type with costs and completion status.
+
+## Tips for Best Results
+
+### 1. Be Specific in Project Goal
+
+✅ **Good:**
+```bash
+/c-breakout orchestrate "Implement user authentication with JWT, including login, logout, token refresh, and password reset endpoints"
+```
+
+❌ **Too vague:**
+```bash
+/c-breakout orchestrate "Add auth"
+```
+
+### 2. Let Orchestrator Analyze First
+
+The orchestrator reads your codebase before planning. Make sure:
+- Your project has clear structure
+- Key files are in standard locations
+- README or docs exist for context
+
+### 3. Review the Plan
+
+Before execution starts, review the plan:
+- Check agent classifications are correct
+- Verify dependencies make sense
+- Ensure no tasks are missing
+
+### 4. Trust the Specialization
+
+Don't worry if dev agents can't access WebSearch - they shouldn't need it!
+If an agent legitimately needs a blocked tool, it will fail and you can adjust.
+
+## Troubleshooting
+
+### "Orchestrator planning failed"
+
+The orchestrator couldn't create a valid plan.
+- Make project goal more specific
+- Ensure project files are readable
+- Fall back to standard distribute mode
+
+### "Agent needs blocked tool"
+
+An agent was misclassified and needs a tool it doesn't have.
+- Check the error message
+- Manually reclassify the task
+- Or use standard distribute mode for that task
+
+### "Dependency deadlock"
+
+Circular dependencies detected.
+- Review the execution waves
+- Manually reorder tasks if needed
+- Report the issue to improve orchestrator
+
+## Advanced Usage
+
+### Force Specific Agent Types
+
+If orchestrator misclassifies, you can manually specify in your goal:
+
+```bash
+/c-breakout orchestrate "Add caching layer. Use PLANNER agents to research Redis vs Memcached, then DEV agents to implement chosen solution."
+```
+
+### Adjust Concurrency
+
+For larger projects:
+
+```bash
+# Edit config to increase parallel execution
+max_concurrent: 200  # Run more agents simultaneously
+```
+
+## Summary
+
+**Use orchestrate mode for:**
+- 10+ task projects
+- Full lifecycle work (plan → dev → deploy)
+- Cost optimization (43-50% savings)
+- Better reliability (specialized agents)
+
+**Command:**
+```bash
+/c-breakout orchestrate "Your specific project goal here"
+```
+
+**Monitor:**
+```bash
+/c-breakout status
+```
+
+**Get results:**
+```bash
+/c-breakout results
+```
+
+That's it! The orchestrator handles the complexity for you.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "c-breakout-claude",
+  "version": "1.0.0",
+  "description": "Distributed task execution orchestrator for Claude Code with intelligent agent specialization",
+  "main": "index.js",
+  "bin": {
+    "c-breakout": "./bin/c-breakout-cli.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "uninstall": "node scripts/uninstall.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "orchestration",
+    "distributed",
+    "agents",
+    "swarm",
+    "parallel",
+    "skill"
+  ],
+  "author": "krellnpm01",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/krellgit/c-breakout"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "skills/",
+    "docs/",
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "claude-code": ">=0.1.0"
+  },
+  "homepage": "https://github.com/krellgit/c-breakout#readme",
+  "bugs": {
+    "url": "https://github.com/krellgit/c-breakout/issues"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CLAUDE_DIR = path.join(os.homedir(), '.claude', 'commands');
+const SKILL_SOURCE = path.join(__dirname, '..', 'skills', 'c-breakout.md');
+const SKILL_DEST = path.join(CLAUDE_DIR, 'c-breakout.md');
+
+console.log('📦 Installing C-Breakout skill for Claude Code...\n');
+
+// Ensure .claude/commands directory exists
+if (!fs.existsSync(CLAUDE_DIR)) {
+  console.log('Creating ~/.claude/commands directory...');
+  fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+}
+
+// Check if skill already exists
+if (fs.existsSync(SKILL_DEST)) {
+  console.log('⚠️  C-Breakout skill already exists at:', SKILL_DEST);
+  console.log('Creating backup...');
+  const backup = SKILL_DEST + '.backup.' + Date.now();
+  fs.copyFileSync(SKILL_DEST, backup);
+  console.log('✓ Backup created:', backup);
+}
+
+// Copy skill file
+try {
+  fs.copyFileSync(SKILL_SOURCE, SKILL_DEST);
+  console.log('✓ C-Breakout skill installed to:', SKILL_DEST);
+} catch (error) {
+  console.error('✗ Failed to install skill:', error.message);
+  process.exit(1);
+}
+
+console.log('\n╔════════════════════════════════════════════════════════════╗');
+console.log('║  C-Breakout Installation Complete! 🎉                     ║');
+console.log('╚════════════════════════════════════════════════════════════╝');
+console.log('\n📚 Quick Start:\n');
+console.log('   # In Claude Code, use:');
+console.log('   /c-breakout orchestrate "Your project goal"');
+console.log('');
+console.log('   # Or naturally in conversation:');
+console.log('   "Orchestrate implementing user authentication"');
+console.log('');
+console.log('📖 Documentation:');
+console.log('   npm docs @claude-code/c-breakout');
+console.log('');
+console.log('🔧 Configuration:');
+console.log('   ~/.claude/commands/c-breakout.md');
+console.log('');
+console.log('💡 Learn more:');
+console.log('   https://github.com/yourusername/c-breakout');
+console.log('');

package/scripts/uninstall.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const SKILL_PATH = path.join(os.homedir(), '.claude', 'commands', 'c-breakout.md');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+console.log('🗑️  Uninstalling C-Breakout skill...\n');
+
+if (!fs.existsSync(SKILL_PATH)) {
+  console.log('ℹ️  C-Breakout skill not found. Nothing to uninstall.');
+  process.exit(0);
+}
+
+rl.question('Remove ~/.claude/commands/c-breakout.md? [y/N] ', (answer) => {
+  if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+    try {
+      fs.unlinkSync(SKILL_PATH);
+      console.log('✓ C-Breakout skill removed');
+    } catch (error) {
+      console.error('✗ Failed to remove skill:', error.message);
+      process.exit(1);
+    }
+  } else {
+    console.log('Skipped removal. Skill remains at:', SKILL_PATH);
+  }
+  rl.close();
+});