@sparkleideas/ruv-swarm 1.0.18-patch.1

package/src/github-coordinator/README.md

@@ -0,0 +1,193 @@
+# GitHub Coordinator for ruv-swarm
+
+Simple GitHub-based coordination for multiple Claude Code swarms working on the same repository.
+
+## Quick Start
+
+### Option 1: GitHub CLI (Recommended)
+
+The simplest approach uses the GitHub CLI (`gh`) that you already have:
+
+```bash
+# Install gh CLI if not already installed
+# https://cli.github.com/
+
+# Use the coordinator
+npx ruv-swarm github-coordinate
+
+# Or use directly in your swarm
+const GHCoordinator = require('./gh-cli-coordinator');
+const coordinator = new GHCoordinator({
+  owner: 'ruvnet',
+  repo: 'ruv-FANN'
+});
+
+# Get available tasks
+const tasks = await coordinator.getAvailableTasks();
+
+# Claim a task
+await coordinator.claimTask('my-swarm-id', issueNumber);
+
+# Update progress
+await coordinator.updateTaskProgress('my-swarm-id', issueNumber, 'Working on authentication...');
+```
+
+### Option 2: Claude Code Hooks
+
+Add automatic GitHub coordination to your Claude Code sessions:
+
+1. Add to `.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "pre-task": "npx ruv-swarm hook github pre-task",
+    "post-edit": "npx ruv-swarm hook github post-edit",
+    "post-task": "npx ruv-swarm hook github post-task"
+  }
+}
+```
+
+2. Set environment variables:
+```bash
+export GITHUB_OWNER=ruvnet
+export GITHUB_REPO=ruv-FANN
+export CLAUDE_SWARM_ID=my-swarm-123  # Optional, auto-generated if not set
+```
+
+3. Now Claude Code will automatically:
+   - Claim GitHub issues when starting tasks
+   - Update issues with progress
+   - Release issues when done
+
+### Option 3: GitHub MCP Server
+
+If you have a GitHub MCP server, you can use it directly:
+
+```javascript
+// Use GitHub MCP tools
+mcp__github__issues_list({ state: 'open', labels: ['swarm-available'] })
+mcp__github__issues_update({ number: 123, labels: ['swarm-claimed'] })
+mcp__github__issues_comment({ number: 123, body: 'Progress update...' })
+```
+
+## How It Works
+
+### Task Coordination via GitHub Labels
+
+The system uses GitHub labels to coordinate work:
+
+- `swarm-available` - Tasks ready to be claimed
+- `swarm-{id}` - Task claimed by a specific swarm
+- `swarm-conflict` - Multiple swarms trying to work on same area
+
+### Workflow
+
+1. **Task Discovery**: Swarms check for open issues without swarm labels
+2. **Task Claiming**: Add a `swarm-{id}` label to claim an issue
+3. **Progress Updates**: Post comments with progress updates
+4. **Task Completion**: Remove label or close issue when done
+
+### Conflict Prevention
+
+- Each swarm has a unique ID
+- Issues can only have one `swarm-*` label
+- Comments show which swarm is working on what
+- Dashboard shows all active swarms and their tasks
+
+## Examples
+
+### Basic Coordination
+
+```javascript
+// Initialize coordinator
+const coordinator = new GHCoordinator({
+  owner: 'ruvnet',
+  repo: 'ruv-FANN',
+  labelPrefix: 'swarm-'  // default
+});
+
+// Get coordination status
+const status = await coordinator.getCoordinationStatus();
+console.log(`${status.swarmTasks} tasks being worked on`);
+console.log(`${status.availableTasks} tasks available`);
+
+// Show swarm assignments
+for (const [swarmId, tasks] of Object.entries(status.swarmStatus)) {
+  console.log(`Swarm ${swarmId} is working on:`);
+  tasks.forEach(task => console.log(`  - #${task.number}: ${task.title}`));
+}
+```
+
+### With Claude Code Integration
+
+When using the hooks, Claude Code will automatically coordinate:
+
+```bash
+# Start a task - automatically claims related GitHub issue
+claude> Can you fix the authentication bug?
+🎯 Pre-task: Looking for GitHub issues related to: fix authentication bug
+✅ Claimed GitHub issue #123: Fix JWT token validation
+
+# Make changes - automatically updates issue
+claude> [edits auth.js]
+📝 Updated GitHub issue #123 with edit progress
+
+# Complete task - automatically updates/releases issue
+claude> I've fixed the authentication issue
+✅ Task Completed on GitHub issue #123
+```
+
+### Manual Coordination Commands
+
+```bash
+# Check coordination status
+npx ruv-swarm github status
+
+# List available tasks
+npx ruv-swarm github tasks --available
+
+# Claim a specific task
+npx ruv-swarm github claim 123
+
+# Release a task
+npx ruv-swarm github release 123
+
+# Show dashboard URLs
+npx ruv-swarm github dashboard
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GITHUB_OWNER` - Repository owner
+- `GITHUB_REPO` - Repository name
+- `GITHUB_TOKEN` - Personal access token (optional, uses gh CLI auth)
+- `CLAUDE_SWARM_ID` - Unique swarm identifier
+
+### Label Configuration
+
+Customize the label prefix in the coordinator:
+
+```javascript
+const coordinator = new GHCoordinator({
+  labelPrefix: 'ai-swarm-'  // Use custom prefix
+});
+```
+
+## Benefits
+
+1. **Simple**: Uses existing GitHub features (labels, comments)
+2. **Visible**: All coordination visible in GitHub UI
+3. **No Extra Infrastructure**: Just needs `gh` CLI
+4. **Conflict-Free**: Labels prevent duplicate work
+5. **Auditable**: Full history in GitHub
+
+## Limitations
+
+- Requires GitHub CLI or API access
+- Limited to GitHub's rate limits
+- Basic conflict detection (label-based)
+- No real-time updates (polling-based)
+
+For more advanced coordination, consider using the full GitHubCoordinator with a database backend or a dedicated MCP server.

package/src/github-coordinator/claude-hooks.js

@@ -0,0 +1,162 @@
+/**
+ * Claude Code Hooks for GitHub Coordination
+ * Automatically coordinates swarm activities with GitHub
+ */
+
+const GHCoordinator = require('./gh-cli-coordinator');
+// const fs = require('fs').promises; // Unused - will be used in future implementation
+const path = require('path');
+
+class ClaudeGitHubHooks {
+  constructor(options = {}) {
+    this.coordinator = new GHCoordinator(options);
+    this.swarmId = options.swarmId || this.generateSwarmId();
+    this.activeTask = null;
+  }
+
+  generateSwarmId() {
+    // Generate swarm ID from environment or random
+    return process.env.CLAUDE_SWARM_ID || `claude-${Date.now().toString(36)}`;
+  }
+
+  /**
+   * Pre-task hook: Claim a GitHub issue before starting work
+   */
+  async preTask(taskDescription) {
+    console.log(`🎯 Pre-task: Looking for GitHub issues related to: ${taskDescription}`);
+
+    try {
+      // Search for related issues
+      const tasks = await this.coordinator.getAvailableTasks({ state: 'open' });
+
+      // Find best matching task (simple keyword matching for now)
+      const keywords = taskDescription.toLowerCase().split(' ');
+      const matchedTask = tasks.find(task => {
+        const taskText = `${task.title} ${task.body || ''}`.toLowerCase();
+        return keywords.some(keyword => taskText.includes(keyword));
+      });
+
+      if (matchedTask) {
+        const claimed = await this.coordinator.claimTask(this.swarmId, matchedTask.number);
+        if (claimed) {
+          this.activeTask = matchedTask.number;
+          console.log(`✅ Claimed GitHub issue #${matchedTask.number}: ${matchedTask.title}`);
+          return { claimed: true, issue: matchedTask.number };
+        }
+      }
+
+      console.log('ℹ️ No matching GitHub issue found, proceeding without claim');
+      return { claimed: false };
+    } catch (error) {
+      console.error('❌ Pre-task hook error:', error.message);
+      return { error: error.message };
+    }
+  }
+
+  /**
+   * Post-edit hook: Update GitHub issue with progress
+   */
+  async postEdit(filePath, changes) {
+    if (!this.activeTask) {
+      return;
+    }
+
+    try {
+      const message = `Updated \`${path.basename(filePath)}\`\n\n${changes.summary || 'File modified'}`;
+      await this.coordinator.updateTaskProgress(this.swarmId, this.activeTask, message);
+      console.log(`📝 Updated GitHub issue #${this.activeTask} with edit progress`);
+    } catch (error) {
+      console.error('❌ Post-edit hook error:', error.message);
+    }
+  }
+
+  /**
+   * Post-task hook: Complete or release the GitHub issue
+   */
+  async postTask(taskId, result) {
+    if (!this.activeTask) {
+      return;
+    }
+
+    try {
+      if (result.completed) {
+        const message = `✅ **Task Completed**\n\n${result.summary || 'Task completed successfully'}`;
+        await this.coordinator.updateTaskProgress(this.swarmId, this.activeTask, message);
+
+        // Option to auto-close issue (disabled by default)
+        if (result.autoClose) {
+          console.log(`🏁 Closing GitHub issue #${this.activeTask}`);
+          // Use gh CLI to close issue
+        }
+      } else {
+        await this.coordinator.releaseTask(this.swarmId, this.activeTask);
+        console.log(`🔓 Released GitHub issue #${this.activeTask}`);
+      }
+
+      this.activeTask = null;
+    } catch (error) {
+      console.error('❌ Post-task hook error:', error.message);
+    }
+  }
+
+  /**
+   * Conflict detection hook
+   */
+  async detectConflicts() {
+    try {
+      const status = await this.coordinator.getCoordinationStatus();
+
+      // Check if multiple swarms are working on similar files
+      // const conflicts = []; // Unused - will be used in future implementation
+
+      // Simple conflict detection based on swarm count
+      if (Object.keys(status.swarmStatus).length > 1) {
+        console.log('⚠️ Multiple swarms detected, checking for conflicts...');
+
+        // More sophisticated conflict detection could be added here
+        // For now, just warn about multiple active swarms
+        return {
+          hasConflicts: false,
+          warningCount: Object.keys(status.swarmStatus).length - 1,
+          message: 'Multiple swarms active, coordinate through GitHub issues',
+        };
+      }
+
+      return { hasConflicts: false };
+    } catch (error) {
+      console.error('❌ Conflict detection error:', error.message);
+      return { error: error.message };
+    }
+  }
+
+  /**
+   * Get coordination dashboard URL
+   */
+  async getDashboardUrl() {
+    const baseUrl = `https://github.com/${this.coordinator.config.owner}/${this.coordinator.config.repo}`;
+    return {
+      issues: `${baseUrl}/issues?q=is:issue+is:open+label:${this.coordinator.config.labelPrefix}${this.swarmId}`,
+      allSwarms: `${baseUrl}/issues?q=is:issue+is:open+label:${this.coordinator.config.labelPrefix}`,
+      board: `${baseUrl}/projects`,
+    };
+  }
+}
+
+// Hook registration for Claude Code
+async function registerHooks() {
+  const hooks = new ClaudeGitHubHooks({
+    owner: process.env.GITHUB_OWNER || 'ruvnet',
+    repo: process.env.GITHUB_REPO || 'ruv-FANN',
+  });
+
+  // Register with Claude Code's hook system
+  return {
+    'pre-task': (args) => hooks.preTask(args.description),
+    'post-edit': (args) => hooks.postEdit(args.file, args.changes),
+    'post-task': (args) => hooks.postTask(args.taskId, args.result),
+    'check-conflicts': () => hooks.detectConflicts(),
+    'get-dashboard': () => hooks.getDashboardUrl(),
+  };
+}
+
+module.exports = { ClaudeGitHubHooks, registerHooks };

package/src/github-coordinator/gh-cli-coordinator.js

@@ -0,0 +1,260 @@
+/**
+ * GitHub CLI-based Coordinator for @sparkleideas/ruv-swarm
+ * Uses gh CLI for all GitHub operations - simpler and more reliable
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs').promises;
+const path = require('path');
+const Database = require('better-sqlite3');
+
+class GHCoordinator {
+  constructor(options = {}) {
+    this.config = {
+      owner: options.owner || process.env.GITHUB_OWNER,
+      repo: options.repo || process.env.GITHUB_REPO,
+      dbPath: options.dbPath || path.join(__dirname, '..', '..', 'data', 'gh-coordinator.db'),
+      labelPrefix: options.labelPrefix || 'swarm-',
+      ...options,
+    };
+
+    this.db = null;
+    this.initialize();
+  }
+
+  async initialize() {
+    // Check if gh CLI is available
+    try {
+      execSync('gh --version', { stdio: 'ignore' });
+    } catch {
+      throw new Error('GitHub CLI (gh) is not installed. Install it from https://cli.github.com/');
+    }
+
+    // Setup database for local coordination state
+    await this.setupDatabase();
+  }
+
+  async setupDatabase() {
+    const dataDir = path.dirname(this.config.dbPath);
+    await fs.mkdir(dataDir, { recursive: true });
+
+    this.db = new Database(this.config.dbPath);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS swarm_tasks (
+        issue_number INTEGER PRIMARY KEY,
+        swarm_id TEXT,
+        locked_at INTEGER,
+        lock_expires INTEGER
+      );
+
+      CREATE TABLE IF NOT EXISTS swarm_registry (
+        swarm_id TEXT PRIMARY KEY,
+        user TEXT,
+        capabilities TEXT,
+        last_seen INTEGER DEFAULT (strftime('%s', 'now'))
+      );
+    `);
+  }
+
+  /**
+   * Get available tasks from GitHub issues
+   */
+  async getAvailableTasks(filters = {}) {
+    let cmd = `gh issue list --repo ${this.config.owner}/${this.config.repo} --json number,title,labels,assignees,state,body --limit 100`;
+
+    if (filters.label) {
+      cmd += ` --label "${filters.label}"`;
+    }
+    if (filters.state) {
+      cmd += ` --state ${filters.state}`;
+    }
+
+    const output = execSync(cmd, { encoding: 'utf8' });
+    const issues = JSON.parse(output);
+
+    // Filter out already assigned tasks
+    const availableIssues = issues.filter(issue => {
+      // Check if issue has swarm assignment label
+      const hasSwarmLabel = issue.labels.some(l => l.name.startsWith(this.config.labelPrefix));
+      // Check if issue is assigned
+      const isAssigned = issue.assignees.length > 0;
+
+      return !hasSwarmLabel && !isAssigned;
+    });
+
+    return availableIssues;
+  }
+
+  /**
+   * Claim a task for a swarm
+   */
+  async claimTask(swarmId, issueNumber) {
+    try {
+      // Add swarm label to issue
+      const label = `${this.config.labelPrefix}${swarmId}`;
+      execSync(`gh issue edit ${issueNumber} --repo ${this.config.owner}/${this.config.repo} --add-label "${label}"`, { stdio: 'ignore' });
+
+      // Add comment to issue
+      const comment = `🐝 Task claimed by swarm: ${swarmId}\n\nThis task is being worked on by an automated swarm agent. Updates will be posted as progress is made.`;
+      execSync(`gh issue comment ${issueNumber} --repo ${this.config.owner}/${this.config.repo} --body "${comment}"`, { stdio: 'ignore' });
+
+      // Record in local database
+      this.db.prepare(`
+        INSERT OR REPLACE INTO swarm_tasks (issue_number, swarm_id, locked_at, lock_expires)
+        VALUES (?, ?, strftime('%s', 'now'), strftime('%s', 'now', '+1 hour'))
+      `).run(issueNumber, swarmId);
+
+      return true;
+    } catch (error) {
+      console.error(`Failed to claim task ${issueNumber}:`, error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Release a task
+   */
+  async releaseTask(swarmId, issueNumber) {
+    try {
+      const label = `${this.config.labelPrefix}${swarmId}`;
+      execSync(`gh issue edit ${issueNumber} --repo ${this.config.owner}/${this.config.repo} --remove-label "${label}"`, { stdio: 'ignore' });
+
+      this.db.prepare('DELETE FROM swarm_tasks WHERE issue_number = ?').run(issueNumber);
+      return true;
+    } catch (error) {
+      console.error(`Failed to release task ${issueNumber}:`, error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Update task progress
+   */
+  async updateTaskProgress(swarmId, issueNumber, message) {
+    try {
+      const comment = `🔄 **Progress Update from swarm ${swarmId}**\n\n${message}`;
+      execSync(`gh issue comment ${issueNumber} --repo ${this.config.owner}/${this.config.repo} --body "${comment}"`, { stdio: 'ignore' });
+      return true;
+    } catch (error) {
+      console.error(`Failed to update task ${issueNumber}:`, error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Create a task allocation PR
+   */
+  async createAllocationPR(allocations) {
+    const branch = `swarm-allocation-${Date.now()}`;
+
+    // Create allocation file
+    const allocationContent = {
+      timestamp: new Date().toISOString(),
+      allocations,
+    };
+
+    const allocationPath = '.github/swarm-allocations.json';
+    await fs.writeFile(allocationPath, JSON.stringify(allocationContent, null, 2));
+
+    // Create PR using gh CLI
+    try {
+      execSync(`git checkout -b ${branch}`, { stdio: 'ignore' });
+      execSync(`git add ${allocationPath}`, { stdio: 'ignore' });
+      execSync('git commit -m "Update swarm task allocations"', { stdio: 'ignore' });
+      execSync(`git push origin ${branch}`, { stdio: 'ignore' });
+
+      const prBody = `## Swarm Task Allocation Update
+
+This PR updates the task allocation for active swarms.
+
+### Allocations:
+${allocations.map(a => `- Issue #${a.issue}: Assigned to swarm ${a.swarm_id}`).join('\n')}
+
+This is an automated update from the swarm coordinator.`;
+
+      const output = execSync(`gh pr create --repo ${this.config.owner}/${this.config.repo} --title "Update swarm task allocations" --body "${prBody}" --base main --head ${branch}`, { encoding: 'utf8' });
+
+      return output.trim();
+    } catch (error) {
+      console.error('Failed to create allocation PR:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Get swarm coordination status
+   */
+  async getCoordinationStatus() {
+    // Get issues with swarm labels
+    const cmd = `gh issue list --repo ${this.config.owner}/${this.config.repo} --json number,title,labels,assignees --limit 100`;
+    const output = execSync(cmd, { encoding: 'utf8' });
+    const issues = JSON.parse(output);
+
+    const swarmTasks = issues.filter(issue =>
+      issue.labels.some(l => l.name.startsWith(this.config.labelPrefix)),
+    );
+
+    // Group by swarm
+    const swarmStatus = {};
+    swarmTasks.forEach(issue => {
+      const swarmLabel = issue.labels.find(l => l.name.startsWith(this.config.labelPrefix));
+      if (swarmLabel) {
+        const swarmId = swarmLabel.name.replace(this.config.labelPrefix, '');
+        if (!swarmStatus[swarmId]) {
+          swarmStatus[swarmId] = [];
+        }
+        swarmStatus[swarmId].push({
+          number: issue.number,
+          title: issue.title,
+        });
+      }
+    });
+
+    return {
+      totalIssues: issues.length,
+      swarmTasks: swarmTasks.length,
+      availableTasks: issues.length - swarmTasks.length,
+      swarmStatus,
+    };
+  }
+
+  /**
+   * Clean up stale locks
+   */
+  async cleanupStaleLocks() {
+    const staleTasks = this.db.prepare(`
+      SELECT issue_number, swarm_id FROM swarm_tasks 
+      WHERE lock_expires < strftime('%s', 'now')
+    `).all();
+
+    for (const task of staleTasks) {
+      await this.releaseTask(task.swarm_id, task.issue_number);
+    }
+
+    return staleTasks.length;
+  }
+}
+
+// Example usage with gh CLI - commented out to avoid no-unused-vars warning
+// async function example() {
+//   const coordinator = new GHCoordinator({
+//     owner: 'ruvnet',
+//     repo: 'ruv-FANN',
+//   });
+//
+//   // Get available tasks
+//   const tasks = await coordinator.getAvailableTasks({ state: 'open' });
+//   console.log(`Found ${tasks.length} available tasks`);
+//
+//   // Claim a task for a swarm
+//   if (tasks.length > 0) {
+//     const claimed = await coordinator.claimTask('swarm-123', tasks[0].number);
+//     console.log(`Claimed task #${tasks[0].number}: ${claimed}`);
+//   }
+//
+//   // Get coordination status
+//   const status = await coordinator.getCoordinationStatus();
+//   console.log('Coordination status:', status);
+// }
+
+module.exports = GHCoordinator;

package/src/hooks/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * CLI handler for @sparkleideas/ruv-swarm hooks
+ * Usage: npx @sparkleideas/ruv-swarm hook <type> [options]
+ */
+
+import { handleHook } from './index.js';
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Skip if not a hook command
+  if (args[0] !== 'hook') {
+    return;
+  }
+
+  const [, hookType] = args;
+  const options = parseArgs(args.slice(2));
+
+  try {
+    const result = await handleHook(hookType, options);
+
+    // Output JSON response for Claude Code to parse
+    console.log(JSON.stringify(result, null, 2));
+
+    // Exit with appropriate code
+    if (result.continue === false) {
+      process.exit(2); // Blocking error
+    } else {
+      process.exit(0); // Success
+    }
+  } catch (error) {
+    console.error(JSON.stringify({
+      continue: true,
+      error: error.message,
+      stack: process.env.DEBUG ? error.stack : undefined,
+    }));
+    process.exit(1); // Non-blocking error
+  }
+}
+
+function parseArgs(args) {
+  const options = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.substring(2);
+
+      // Check if next arg is a value or another flag
+      if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+        // Next arg is the value
+        options[toCamelCase(key)] = args[i + 1];
+        i++; // Skip the value in next iteration
+      } else {
+        // Boolean flag
+        options[toCamelCase(key)] = true;
+      }
+    } else if (!args[i - 1]?.startsWith('--')) {
+      // Positional argument
+      if (!options._) {
+        options._ = [];
+      }
+      options._.push(arg);
+    }
+  }
+
+  return options;
+}
+
+function toCamelCase(str) {
+  return str.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { main };