ruvnet--ruflo/v3/implementation/PLUGIN_INTEGRATION.md

Claude Flow Plugin Integration

Overview

This document describes how claude-flow integrates with the official Claude Code plugin system.

Plugin Structure

plugin/
├── .claude-plugin/
│   └── plugin.json          # Official plugin manifest
├── .mcp.json                 # MCP server bundle
├── hooks/
│   └── hooks.json            # Hook configurations
├── skills -> ../.claude/skills     # 60+ skills
├── commands -> ../.claude/commands # 100+ commands
└── agents -> ../v2/.claude/agents  # 80+ agents

Official Claude Code Integration Points

1. Plugin Manifest (plugin.json)

{
  "name": "claude-flow",
  "version": "3.0.0",
  "capabilities": {
    "skills": true,
    "commands": true,
    "agents": true,
    "hooks": true,
    "mcpServers": true
  }
}

2. Hook Event Mapping

V3 Internal Event	Official Claude Code Event	Tool Matcher
PreEdit	PreToolUse	^(Write|Edit|MultiEdit)$
PostEdit	PostToolUse	^(Write|Edit|MultiEdit)$
PreCommand	PreToolUse	^Bash$
PostCommand	PostToolUse	^Bash$
PreTask	UserPromptSubmit	-
PostTask	PostToolUse	^Task$
SessionStart	SessionStart	-
SessionEnd	Stop	-
AgentSpawn	PostToolUse	^Task$
AgentTerminate	SubagentStop	-
PreRoute	UserPromptSubmit	-

3. MCP Server Bundle

The plugin bundles three MCP servers:

1. claude-flow (required): Core swarm coordination
2. ruv-swarm (optional): Enhanced topology patterns
3. flow-nexus (optional): Cloud orchestration

4. Skills Integration

Skills follow the official SKILL.md format:

---
name: skill-name
description: What this skill does
allowed-tools: Read, Write, Bash
---

# Skill Name

[Instructions for Claude]

V3 Hooks Bridge

The @claude-flow/hooks package includes an official hooks bridge:

import {
  OfficialHooksBridge,
  processOfficialHookInput,
  outputOfficialHookResult,
  executeWithBridge,
} from '@claude-flow/hooks';

// Process input from Claude Code
const input = await processOfficialHookInput();

// Convert to V3 context
const context = OfficialHooksBridge.toV3Context(input);

// Execute V3 handler
const result = await handler(context);

// Convert back to official output
const output = OfficialHooksBridge.toOfficialOutput(result, input.hook_event_name);
outputOfficialHookResult(output);

Installation

Via Plugin Command (Recommended)

# Add plugin marketplace
/plugin marketplace add claude-flow https://github.com/ruvnet/claude-flow

# Install plugin
/plugin install claude-flow

Manual Installation

# Clone and link
git clone https://github.com/ruvnet/claude-flow
claude --plugin-dir ./claude-flow/plugin

Via npx Init

npx claude-flow@alpha init --hooks

Configuration

Enable All Hooks

Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "UserPromptSubmit": [...],
    "SessionStart": [...],
    "Stop": [...]
  }
}

Selective Hooks

Enable only specific hooks by choosing matchers:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^(Write|Edit)$",
        "hooks": [{ "type": "command", "command": "npx claude-flow@alpha hooks pre-edit" }]
      }
    ]
  }
}

MCP Tool Access

After installation, MCP tools are available:

• mcp__claude-flow__swarm_init
• mcp__claude-flow__agent_spawn
• mcp__claude-flow__task_orchestrate
• mcp__claude-flow__memory_usage
• mcp__claude-flow__hooks_route
• mcp__claude-flow__hooks_metrics

Marketplace Publishing

Create Marketplace Entry

{
  "name": "claude-flow-marketplace",
  "plugins": [
    {
      "name": "claude-flow",
      "description": "Multi-agent swarm coordination",
      "version": "3.0.0",
      "path": "plugin"
    }
  ]
}

Host on GitHub

1. Push to repository
2. Add marketplace: /plugin marketplace add name https://github.com/user/repo
3. Users install: /plugin install claude-flow@name

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code                              │
├─────────────────────────────────────────────────────────────┤
│  Official Hooks API                                          │
│  ┌─────────────┬─────────────┬─────────────┬──────────────┐ │
│  │ PreToolUse  │ PostToolUse │ SessionStart│ UserPrompt   │ │
│  └──────┬──────┴──────┬──────┴──────┬──────┴──────┬───────┘ │
│         │             │             │             │          │
│         ▼             ▼             ▼             ▼          │
│  ┌──────────────────────────────────────────────────────────┐│
│  │              Official Hooks Bridge                        ││
│  │  (v3/@claude-flow/hooks/src/bridge/official-hooks-bridge)││
│  └──────────────────────────────────────────────────────────┘│
│         │             │             │             │          │
│         ▼             ▼             ▼             ▼          │
│  ┌─────────────┬─────────────┬─────────────┬──────────────┐ │
│  │ PreEdit     │ PostEdit    │ SessionStart│ PreTask      │ │
│  │ PreCommand  │ PostCommand │ SessionEnd  │ PostTask     │ │
│  └─────────────┴─────────────┴─────────────┴──────────────┘ │
│                     V3 Hooks System                          │
├─────────────────────────────────────────────────────────────┤
│                    @claude-flow/hooks                        │
│  ┌───────────┬───────────┬───────────┬───────────────────┐  │
│  │ Registry  │ Executor  │ Daemons   │ MCP Tools         │  │
│  └───────────┴───────────┴───────────┴───────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│              Skills │ Commands │ Agents │ MCP Servers       │
└─────────────────────────────────────────────────────────────┘

Benefits

1. Seamless Integration: V3 hooks map directly to official events
2. Full Feature Access: 60+ skills, 100+ commands, 80+ agents
3. MCP Bundling: All servers configured in one file
4. Marketplace Ready: Standard plugin format for distribution
5. Backward Compatible: Works with existing .claude/ configurations