@sparkleideas/teammate-plugin 1.0.0-alpha.11

package/README.md

@@ -0,0 +1,713 @@
+# @claude-flow/teammate-plugin
+
+Native **TeammateTool** integration plugin for Claude Flow. Bridges Claude Code v2.1.19+ multi-agent orchestration capabilities with Claude Flow's swarm system.
+
+[![npm version](https://badge.fury.io/js/%40claude-flow%2Fteammate-plugin.svg)](https://badge.fury.io/js/%40claude-flow%2Fteammate-plugin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Requirements
+
+| Requirement | Minimum Version | Recommended |
+|-------------|-----------------|-------------|
+| **Claude Code** | **>= 2.1.19** | Latest |
+| Node.js | >= 18.0.0 | >= 20.0.0 |
+| npm | >= 9.0.0 | >= 10.0.0 |
+
+> **IMPORTANT:** This plugin requires Claude Code version **2.1.19 or higher**. The TeammateTool functionality was introduced in this version and is not available in earlier releases.
+
+### Version Check
+
+```bash
+# Check your Claude Code version
+claude --version
+
+# Should output: 2.1.19 or higher
+```
+
+If your version is below 2.1.19, update Claude Code:
+
+```bash
+claude update
+```
+
+## Installation
+
+### Via Claude Code CLI (Recommended)
+
+Install directly using Claude Code's plugin system:
+
+```bash
+# Install from npm registry
+claude plugins install @claude-flow/teammate-plugin
+
+# Or install from Claude Flow plugin registry (IPFS-backed)
+claude plugins install teammate-plugin --registry claude-flow
+```
+
+### Via npm
+
+```bash
+npm install @claude-flow/teammate-plugin
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @claude-flow/teammate-plugin
+```
+
+### Via Claude Flow CLI
+
+```bash
+# Install via claude-flow plugin manager
+npx @claude-flow/cli@latest plugins install --name @claude-flow/teammate-plugin
+
+# Or add to your claude-flow.config.json
+npx @claude-flow/cli@latest config set plugins.teammate-plugin.enabled true
+```
+
+### Verify Installation
+
+```bash
+# Check plugin is loaded
+claude plugins list
+
+# Or via claude-flow
+npx @claude-flow/cli@latest plugins list
+```
+
+## Quick Start
+
+```typescript
+import { createTeammateBridge } from '@claude-flow/teammate-plugin';
+
+// Initialize the bridge
+const bridge = await createTeammateBridge();
+
+// Check compatibility
+const version = bridge.getVersionInfo();
+console.log(`Claude Code: ${version.claudeCode}`);
+console.log(`Compatible: ${version.compatible}`);
+
+if (!version.compatible) {
+  console.error('Please upgrade Claude Code to >= 2.1.19');
+  process.exit(1);
+}
+
+// Create a team
+const team = await bridge.spawnTeam({
+  name: 'my-dev-team',
+  topology: 'hierarchical',
+  maxTeammates: 6,
+  planModeRequired: true,
+});
+
+// Spawn teammates (returns AgentInput for Claude Code Task tool)
+const coder = await bridge.spawnTeammate({
+  name: 'coder-1',
+  role: 'coder',
+  prompt: 'Implement the authentication feature using JWT',
+  teamName: 'my-dev-team',
+  model: 'sonnet',
+  allowedTools: ['Edit', 'Write', 'Read', 'Bash'],
+});
+
+// The agentInput can be passed to Claude Code's Task tool
+const agentInput = bridge.buildAgentInput({
+  name: 'tester-1',
+  role: 'tester',
+  prompt: 'Write tests for the authentication feature',
+  teamName: 'my-dev-team',
+  model: 'haiku',
+});
+
+console.log('Pass this to Task tool:', agentInput);
+```
+
+## Features
+
+### Core Features (from TeammateTool)
+
+| Feature | Description | TeammateTool Operation |
+|---------|-------------|------------------------|
+| Team Management | Create, discover, load teams | `spawnTeam`, `discoverTeams` |
+| Teammate Spawning | Spawn agents with native support | `AgentInput` schema |
+| Join/Leave Workflow | Request-approve-reject pattern | `requestJoin`, `approveJoin`, `rejectJoin` |
+| Messaging | Direct and broadcast messages | `write`, `broadcast` |
+| Plan Approval | Submit, vote, execute plans | `approvePlan`, `rejectPlan` |
+| Swarm Launch | Launch multi-agent execution | `launchSwarm`, `teammateCount` |
+| Shutdown | Graceful teammate termination | `requestShutdown`, `approveShutdown` |
+
+### Extended Features (Plugin Additions)
+
+| Feature | Description |
+|---------|-------------|
+| Delegation | Delegate authority between teammates |
+| Team Context | Shared variables, permissions, environment |
+| Permission Updates | Dynamic permission changes mid-execution |
+| Session Memory | Persist teammate context across sessions |
+| Remote Sync | Push team to Claude.ai (experimental) |
+| Transcript Sharing | Share message history between teammates |
+| Teleport | Resume teams across terminal instances |
+| Plan Control | Pause, resume, modify plans mid-execution |
+
+## API Reference
+
+### TeammateBridge
+
+The main class for interacting with TeammateTool.
+
+#### Initialization
+
+```typescript
+import { createTeammateBridge, TeammateBridge } from '@claude-flow/teammate-plugin';
+
+// Factory function (recommended)
+const bridge = await createTeammateBridge({
+  fallbackToMCP: true,  // Fallback to MCP if TeammateTool unavailable
+  memory: {
+    autoPersist: true,
+    persistIntervalMs: 60000,
+  },
+});
+
+// Or direct instantiation
+const bridge = new TeammateBridge(config);
+await bridge.initialize();
+```
+
+#### Team Management
+
+```typescript
+// Create team
+const team = await bridge.spawnTeam({
+  name: 'my-team',
+  topology: 'hierarchical',  // 'flat' | 'hierarchical' | 'mesh'
+  maxTeammates: 8,
+  planModeRequired: true,
+  autoApproveJoin: true,
+  delegationEnabled: true,
+});
+
+// Discover existing teams
+const teams = await bridge.discoverTeams();
+// ['team-1', 'team-2', ...]
+
+// Load existing team
+const existingTeam = await bridge.loadTeam('team-1');
+
+// Get team state
+const state = bridge.getTeamState('my-team');
+```
+
+#### Teammate Spawning
+
+```typescript
+// Spawn teammate
+const teammate = await bridge.spawnTeammate({
+  name: 'coder-1',
+  role: 'coder',
+  prompt: 'Implement feature X',
+  teamName: 'my-team',
+  model: 'sonnet',  // 'sonnet' | 'opus' | 'haiku'
+  allowedTools: ['Edit', 'Write', 'Read'],
+  mode: 'default',  // 'default' | 'plan' | 'delegate' | etc.
+});
+
+// Build AgentInput for Task tool
+const agentInput = bridge.buildAgentInput({
+  name: 'reviewer-1',
+  role: 'reviewer',
+  prompt: 'Review code changes',
+  teamName: 'my-team',
+});
+// Pass agentInput to Claude Code's Task tool
+```
+
+#### Messaging
+
+```typescript
+// Send direct message
+const message = await bridge.sendMessage(
+  'my-team',
+  'sender-id',
+  'recipient-id',
+  {
+    type: 'task',
+    payload: { action: 'implement', target: 'auth' },
+    priority: 'high',
+  }
+);
+
+// Broadcast to all teammates
+await bridge.broadcast('my-team', 'coordinator-id', {
+  type: 'status',
+  payload: { phase: 'implementation' },
+});
+
+// Read mailbox
+const messages = await bridge.readMailbox('my-team', 'teammate-id');
+```
+
+#### Plan Approval
+
+```typescript
+// Submit plan
+const plan = await bridge.submitPlan('my-team', {
+  description: 'Implement authentication feature',
+  proposedBy: 'coordinator-id',
+  steps: [
+    { order: 1, action: 'Create user model', tools: ['Edit'], assignee: 'coder-1' },
+    { order: 2, action: 'Add JWT middleware', tools: ['Edit'], assignee: 'coder-1' },
+    { order: 3, action: 'Write unit tests', tools: ['Edit'], assignee: 'tester-1' },
+  ],
+  requiredApprovals: 2,
+});
+
+// Approve plan
+await bridge.approvePlan('my-team', plan.id, 'reviewer-id');
+
+// Launch swarm (after approval)
+const exitPlanInput = await bridge.launchSwarm('my-team', plan.id, 3);
+// Pass exitPlanInput to ExitPlanMode tool
+```
+
+#### Delegation
+
+```typescript
+// Delegate authority
+const delegation = await bridge.delegateToTeammate(
+  'my-team',
+  'lead-id',
+  'dev-id',
+  ['approve_plan', 'spawn_teammate']
+);
+
+// Revoke delegation
+await bridge.revokeDelegation('my-team', 'lead-id', 'dev-id');
+```
+
+#### Team Context
+
+```typescript
+// Update context
+await bridge.updateTeamContext('my-team', {
+  sharedVariables: {
+    apiEndpoint: 'https://api.example.com',
+    version: '1.0.0',
+  },
+  inheritedPermissions: ['read', 'write'],
+  environmentVariables: {
+    NODE_ENV: 'development',
+  },
+});
+
+// Get context
+const context = bridge.getTeamContext('my-team');
+```
+
+#### Session Memory
+
+```typescript
+// Save teammate memory
+await bridge.saveTeammateMemory('my-team', 'teammate-id');
+
+// Load teammate memory
+const memory = await bridge.loadTeammateMemory('my-team', 'teammate-id');
+
+// Share transcript
+await bridge.shareTranscript('my-team', 'from-id', 'to-id', {
+  start: 0,
+  end: 10,
+});
+```
+
+#### Teleport
+
+```typescript
+// Check if teleport is possible
+const { canTeleport, blockers } = await bridge.canTeleport('my-team', {
+  workingDirectory: '/path/to/new/dir',
+  gitBranch: 'feature/auth',
+});
+
+// Teleport team
+if (canTeleport) {
+  const result = await bridge.teleportTeam('my-team', {
+    workingDirectory: '/path/to/new/dir',
+    gitBranch: 'feature/auth',
+  });
+}
+```
+
+### MCP Tools
+
+The plugin provides 16 MCP tools for use with Claude Code's MCP server:
+
+```typescript
+import { TEAMMATE_MCP_TOOLS, handleMCPTool } from '@claude-flow/teammate-plugin';
+
+// List all tools
+console.log(TEAMMATE_MCP_TOOLS.map(t => t.name));
+// [
+//   'teammate_spawn_team',
+//   'teammate_discover_teams',
+//   'teammate_spawn',
+//   'teammate_send_message',
+//   'teammate_broadcast',
+//   'teammate_submit_plan',
+//   'teammate_approve_plan',
+//   'teammate_launch_swarm',
+//   'teammate_delegate',
+//   'teammate_update_context',
+//   'teammate_save_memory',
+//   'teammate_share_transcript',
+//   'teammate_push_remote',
+//   'teammate_teleport',
+//   'teammate_get_status',
+//   'teammate_cleanup',
+// ]
+
+// Handle tool call
+const result = await handleMCPTool(bridge, 'teammate_spawn_team', {
+  name: 'my-team',
+  topology: 'hierarchical',
+});
+```
+
+## Events
+
+The bridge emits events for all operations:
+
+```typescript
+bridge.on('team:spawned', ({ team, config }) => {
+  console.log(`Team ${team} created`);
+});
+
+bridge.on('teammate:spawned', ({ teammate, agentInput }) => {
+  console.log(`Teammate ${teammate.name} spawned`);
+});
+
+bridge.on('plan:approved', ({ team, plan }) => {
+  console.log(`Plan ${plan.id} approved`);
+});
+
+bridge.on('delegate:granted', ({ team, from, to, permissions }) => {
+  console.log(`${from} delegated to ${to}: ${permissions.join(', ')}`);
+});
+
+bridge.on('teleport:completed', ({ team, result }) => {
+  console.log(`Team ${team} teleported successfully`);
+});
+```
+
+## Error Handling
+
+```typescript
+import { TeammateError, TeammateErrorCode } from '@claude-flow/teammate-plugin';
+
+try {
+  await bridge.launchSwarm('my-team', 'plan-id');
+} catch (error) {
+  if (error instanceof TeammateError) {
+    switch (error.code) {
+      case TeammateErrorCode.PLAN_NOT_APPROVED:
+        console.log('Plan needs approval first');
+        break;
+      case TeammateErrorCode.TEAM_NOT_FOUND:
+        console.log(`Team not found: ${error.teamName}`);
+        break;
+      case TeammateErrorCode.VERSION_INCOMPATIBLE:
+        console.log('Claude Code version too old');
+        break;
+    }
+  }
+}
+```
+
+## Configuration
+
+```typescript
+import { createTeammateBridge, DEFAULT_PLUGIN_CONFIG } from '@claude-flow/teammate-plugin';
+
+const bridge = await createTeammateBridge({
+  autoInitialize: true,
+  fallbackToMCP: true,
+
+  recovery: {
+    maxRetries: 3,
+    retryDelayMs: 1000,
+    exponentialBackoff: true,
+    fallbackToMCP: true,
+    autoCleanupOnError: true,
+  },
+
+  delegation: {
+    maxDepth: 3,
+    autoExpireMs: 3600000,  // 1 hour
+    requireApproval: false,
+  },
+
+  remoteSync: {
+    enabled: false,
+    autoSync: false,
+    syncInterval: 30000,
+    preserveOnDisconnect: true,
+  },
+
+  teleport: {
+    autoResume: true,
+    gitAware: true,
+    preserveMailbox: true,
+    preserveMemory: true,
+  },
+
+  memory: {
+    autoPersist: true,
+    persistIntervalMs: 60000,
+    maxSizeMb: 100,
+  },
+
+  mailbox: {
+    pollingIntervalMs: 1000,
+    maxMessages: 1000,
+    retentionMs: 3600000,
+  },
+});
+```
+
+## Integration with Claude Flow
+
+```typescript
+import { createTeammateBridge } from '@claude-flow/teammate-plugin';
+import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';
+
+// Create bridge
+const bridge = await createTeammateBridge();
+
+// Map Claude Flow topology to team config
+const teamConfig = {
+  name: 'cf-team',
+  topology: 'hierarchical',  // Maps to Claude Flow's hierarchical
+  maxTeammates: 8,
+  planModeRequired: true,
+};
+
+// Create team
+const team = await bridge.spawnTeam(teamConfig);
+
+// Map Claude Flow agent types to teammate configs
+const agentMapping = {
+  'coder': { role: 'coder', tools: ['Edit', 'Write', 'Read', 'Bash'] },
+  'tester': { role: 'tester', tools: ['Read', 'Bash', 'Glob'] },
+  'reviewer': { role: 'reviewer', tools: ['Read', 'Grep', 'Glob'] },
+  'architect': { role: 'architect', tools: ['Read', 'Glob', 'Grep'] },
+};
+
+// Spawn teammates with Claude Flow agent types
+for (const [type, config] of Object.entries(agentMapping)) {
+  await bridge.spawnTeammate({
+    name: `${type}-1`,
+    role: config.role,
+    prompt: `You are a ${type}...`,
+    teamName: 'cf-team',
+    allowedTools: config.tools,
+  });
+}
+```
+
+## File Structure
+
+Teams are stored in `~/.claude/teams/`:
+
+```
+~/.claude/teams/
+├── my-team/
+│   ├── config.json        # Team configuration
+│   ├── state.json         # Team state (teammates, plans)
+│   ├── remote.json        # Remote session info (if synced)
+│   ├── mailbox/
+│   │   ├── teammate-1.json
+│   │   └── teammate-2.json
+│   └── memory/
+│       ├── teammate-1.json
+│       └── teammate-2.json
+└── other-team/
+    └── ...
+```
+
+## Environment Variables
+
+The plugin uses these Claude Code environment variables:
+
+```bash
+CLAUDE_CODE_TEAM_NAME          # Current team context
+CLAUDE_CODE_PLAN_MODE_REQUIRED # Require plan approval
+CLAUDE_CODE_TMUX_SESSION       # tmux session name
+CLAUDE_CODE_TMUX_PREFIX        # tmux prefix key
+CLAUDE_CODE_TEAMMATE_COMMAND   # Custom spawn command
+```
+
+## Troubleshooting
+
+### Plugin reports TeammateTool not available
+
+```typescript
+const version = bridge.getVersionInfo();
+if (!version.compatible) {
+  console.log(`Claude Code version: ${version.claudeCode}`);
+  console.log(`Required: >= 2.1.19`);
+  console.log('Run: claude update');
+}
+```
+
+### Mailbox messages not received
+
+Check that mailbox polling is running:
+
+```typescript
+// Mailbox is polled automatically, but you can read manually
+const messages = await bridge.readMailbox('my-team', 'teammate-id');
+```
+
+### Plan approval stuck
+
+Ensure enough teammates have voted:
+
+```typescript
+const team = bridge.getTeamState('my-team');
+const plan = team.activePlans.find(p => p.id === planId);
+
+console.log(`Approvals: ${plan.approvals.length}/${plan.requiredApprovals}`);
+console.log(`Rejections: ${plan.rejections.length}`);
+```
+
+## Testing the Plugin
+
+### Run Unit Tests
+
+```bash
+cd v3/plugins/teammate-plugin
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Verify Plugin Functionality
+
+```typescript
+import { createTeammateBridge, TEAMMATE_MCP_TOOLS } from '@claude-flow/teammate-plugin';
+
+async function verifyPlugin() {
+  console.log('=== Plugin Verification ===\n');
+
+  // 1. Check MCP tools are exported
+  console.log(`✓ MCP Tools available: ${TEAMMATE_MCP_TOOLS.length}`);
+
+  // 2. Initialize bridge
+  const bridge = await createTeammateBridge();
+  console.log('✓ Bridge initialized');
+
+  // 3. Check version compatibility
+  const version = bridge.getVersionInfo();
+  console.log(`✓ Claude Code version: ${version.claudeCode || 'not detected'}`);
+  console.log(`✓ Plugin version: ${version.plugin}`);
+  console.log(`✓ Compatible: ${version.compatible}`);
+
+  // 4. Test team creation (if compatible)
+  if (version.compatible) {
+    const team = await bridge.spawnTeam({ name: 'test-team' });
+    console.log(`✓ Team created: ${team.name}`);
+
+    // Cleanup
+    await bridge.cleanup('test-team');
+    console.log('✓ Cleanup successful');
+  }
+
+  console.log('\n=== All checks passed! ===');
+}
+
+verifyPlugin().catch(console.error);
+```
+
+### Verify via CLI
+
+```bash
+# Check plugin is registered
+npx @claude-flow/cli@latest plugins list | grep teammate
+
+# Check plugin info
+npx @claude-flow/cli@latest plugins info teammate-plugin
+
+# Test MCP tools
+npx @claude-flow/cli@latest mcp tools | grep teammate
+```
+
+## Plugin Registry (IPFS)
+
+This plugin is published to the Claude Flow Plugin Registry on IPFS for decentralized distribution.
+
+### Registry Entry
+
+```json
+{
+  "name": "teammate-plugin",
+  "package": "@claude-flow/teammate-plugin",
+  "version": "1.0.0-alpha.1",
+  "description": "Native TeammateTool integration for Claude Code v2.1.19+",
+  "author": "Claude Flow Team",
+  "license": "MIT",
+  "repository": "https://github.com/ruvnet/claude-flow",
+  "keywords": ["claude-code", "teammate", "multi-agent", "swarm"],
+  "requirements": {
+    "claudeCode": ">=2.1.19",
+    "node": ">=18.0.0"
+  },
+  "mcpTools": 21,
+  "features": [
+    "team-management",
+    "teammate-spawning",
+    "messaging",
+    "plan-approval",
+    "delegation",
+    "remote-sync",
+    "bmssp-optimization"
+  ]
+}
+```
+
+### Install from Registry
+
+```bash
+# Install from IPFS-backed registry
+npx @claude-flow/cli@latest plugins install teammate-plugin --registry ipfs
+
+# Or specify registry CID directly
+npx @claude-flow/cli@latest plugins install teammate-plugin --cid <registry-cid>
+```
+
+### Verify Registry Integrity
+
+```bash
+# Check plugin hash matches registry
+npx @claude-flow/cli@latest plugins verify teammate-plugin
+
+# View registry metadata
+npx @claude-flow/cli@latest plugins registry info
+```
+
+## License
+
+MIT
+
+## Related
+
+- [Claude Flow](https://github.com/ruvnet/claude-flow) - Multi-agent orchestration framework
+- [Claude Code](https://github.com/anthropics/claude-code) - Anthropic's CLI for Claude
+- [ADR-027](../implementation/adrs/ADR-027-teammate-tool-integration.md) - Architecture decision record

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@sparkleideas/teammate-plugin",
+  "version": "1.0.0-alpha.11",
+  "description": "Native TeammateTool integration plugin for Claude Flow - bridges Claude Code v2.1.19+ multi-agent capabilities",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./bridge": {
+      "import": "./dist/teammate-bridge.js",
+      "types": "./dist/teammate-bridge.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp-tools.js",
+      "types": "./dist/mcp-tools.d.ts"
+    },
+    "./topology": {
+      "import": "./dist/topology-optimizer.js",
+      "types": "./dist/topology-optimizer.d.ts"
+    },
+    "./semantic": {
+      "import": "./dist/semantic-router.js",
+      "types": "./dist/semantic-router.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm run test"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-flow",
+    "teammate",
+    "multi-agent",
+    "swarm",
+    "orchestration",
+    "mcp"
+  ],
+  "author": "rUv <ruv@ruv.net>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/claude-flow.git",
+    "directory": "v3/plugins/teammate-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/claude-flow/issues"
+  },
+  "homepage": "https://github.com/ruvnet/claude-flow#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-code": ">=2.1.19"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-code": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "eventemitter3": "^5.0.1",
+    "@ruvnet/bmssp": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "eslint": "^8.55.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0"
+  },
+  "claude-code": {
+    "minimumVersion": "2.1.19",
+    "requiredFeatures": [
+      "TeammateTool",
+      "team_name",
+      "launchSwarm"
+    ],
+    "optionalFeatures": [
+      "pushToRemote",
+      "delegate_mode",
+      "teleport"
+    ]
+  }
+}