π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
checkpoint: File edit:
rUva1332c0935ce
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.jsonnew file mode 100644index 0000000000..d5371f4571--- /dev/null+++ b/plugin/.claude-plugin/plugin.json@@ -0,0 +1,45 @@+{+ "name": "claude-flow",+ "description": "Multi-agent swarm coordination, memory management, SPARC methodology, and intelligent hooks for Claude Code. Provides 60+ skills, 100+ commands, and 80+ specialized agents.",+ "version": "3.0.0",+ "author": {+ "name": "ruvnet",+ "url": "https://github.com/ruvnet"+ },+ "homepage": "https://github.com/ruvnet/claude-flow",+ "repository": "https://github.com/ruvnet/claude-flow",+ "license": "MIT",+ "keywords": [+ "swarm",+ "multi-agent",+ "coordination",+ "memory",+ "hooks",+ "sparc",+ "mcp",+ "ai-agents"+ ],+ "categories": [+ "Development",+ "Productivity",+ "AI Agents",+ "Workflow Automation"+ ],+ "engines": {+ "claude-code": ">=1.0.0"+ },+ "capabilities": {+ "skills": true,+ "commands": true,+ "agents": true,+ "hooks": true,+ "mcpServers": true+ },+ "main": {+ "skills": "./skills",+ "commands": "./commands",+ "agents": "./agents",+ "hooks": "./hooks/hooks.json",+ "mcp": "./.mcp.json"+ }+}diff --git a/plugin/agents b/plugin/agentsnew file mode 120000index 0000000000..590114992a--- /dev/null+++ b/plugin/agents@@ -0,0 +1 @@+../v2/.claude/agents\ No newline at end of filediff --git a/plugin/commands b/plugin/commandsnew file mode 120000index 0000000000..0b631dd5b7--- /dev/null+++ b/plugin/commands@@ -0,0 +1 @@+../.claude/commands\ No newline at end of filediff --git a/plugin/hooks/hooks.json b/plugin/hooks/hooks.jsonnew file mode 100644index 0000000000..d9a9f0c01b--- /dev/null+++ b/plugin/hooks/hooks.json@@ -0,0 +1,223 @@+{+ "$schema": "https://code.claude.com/schemas/hooks.json",+ "description": "Claude Flow hooks configuration - Maps to official Claude Code hook events",+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "^(Write|Edit|MultiEdit)$",+ "description": "Pre-edit hook for file modifications",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks pre-edit --file \"$TOOL_INPUT_file_path\"",+ "timeout": 5000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^Bash$",+ "description": "Pre-command hook for bash execution",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks pre-command --command \"$TOOL_INPUT_command\"",+ "timeout": 3000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^Task$",+ "description": "Pre-task hook for agent spawning",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks pre-task --description \"$TOOL_INPUT_prompt\"",+ "timeout": 5000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^(Grep|Glob|Read)$",+ "description": "Pre-search hook for caching",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks pre-search --query \"$TOOL_INPUT_pattern\"",+ "timeout": 2000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^mcp__claude-flow__.*$",+ "description": "Pre-MCP hook for swarm coordination",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks mcp-pre --tool \"$TOOL_NAME\"",+ "timeout": 3000,+ "continueOnError": true+ }+ ]+ }+ ],+ "PostToolUse": [+ {+ "matcher": "^(Write|Edit|MultiEdit)$",+ "description": "Post-edit hook for formatting and learning",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks post-edit --file \"$TOOL_INPUT_file_path\" --success \"$TOOL_SUCCESS\" --train-patterns",+ "timeout": 5000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^Bash$",+ "description": "Post-command hook for metrics",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks post-command --command \"$TOOL_INPUT_command\" --success \"$TOOL_SUCCESS\" --exit-code \"$TOOL_EXIT_CODE\"",+ "timeout": 3000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^Task$",+ "description": "Post-task hook for performance analysis",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks post-task --task-id \"$TOOL_RESULT_agent_id\" --success \"$TOOL_SUCCESS\" --analyze-performance",+ "timeout": 5000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^(Grep|Glob|Read)$",+ "description": "Post-search hook for caching results",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks post-search --query \"$TOOL_INPUT_pattern\" --cache-results",+ "timeout": 2000,+ "continueOnError": true+ }+ ]+ },+ {+ "matcher": "^mcp__claude-flow__.*$",+ "description": "Post-MCP hook for coordination state",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks mcp-post --tool \"$TOOL_NAME\" --success \"$TOOL_SUCCESS\"",+ "timeout": 3000,+ "continueOnError": true+ }+ ]+ }+ ],+ "UserPromptSubmit": [+ {+ "description": "Route tasks to optimal agents",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks route --task \"$PROMPT\" --include-explanation",+ "timeout": 5000,+ "continueOnError": true+ }+ ]+ }+ ],+ "SessionStart": [+ {+ "description": "Initialize session and restore context",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks session-start --session-id \"$SESSION_ID\" --load-context",+ "timeout": 10000,+ "continueOnError": true+ }+ ]+ }+ ],+ "Stop": [+ {+ "description": "Evaluate if task is complete",+ "hooks": [+ {+ "type": "prompt",+ "prompt": "Evaluate if the current task has been completed successfully. Consider: 1) Were all requested changes made? 2) Did tests pass? 3) Is there follow-up work needed? Respond with {\"decision\": \"stop\"} if complete, or {\"decision\": \"continue\", \"reason\": \"...\"} if more work is needed."+ }+ ]+ }+ ],+ "SubagentStop": [+ {+ "description": "Evaluate if subagent task is complete",+ "hooks": [+ {+ "type": "prompt",+ "prompt": "Evaluate if the subagent has completed its assigned task. Check if the work output meets the requirements. Respond with {\"decision\": \"stop\"} if complete, or {\"decision\": \"continue\", \"reason\": \"...\"} if more work is needed."+ }+ ]+ }+ ],+ "Notification": [+ {+ "description": "Handle notifications with swarm status",+ "hooks": [+ {+ "type": "command",+ "command": "npx claude-flow@alpha hooks notify --message \"$NOTIFICATION_MESSAGE\" --swarm-status",+ "timeout": 3000,+ "continueOnError": true+ }+ ]+ }+ ],+ "PermissionRequest": [+ {+ "matcher": "^mcp__claude-flow__.*$",+ "description": "Auto-allow claude-flow MCP tools",+ "hooks": [+ {+ "type": "command",+ "command": "echo '{\"decision\": \"allow\", \"reason\": \"claude-flow MCP tool auto-approved\"}'",+ "timeout": 1000+ }+ ]+ }+ ]+ },+ "v3HookMapping": {+ "_comment": "Maps V3 internal hook events to official Claude Code hooks",+ "PreToolUse": "PreToolUse",+ "PostToolUse": "PostToolUse",+ "PreEdit": "PreToolUse (matcher: Edit|Write)",+ "PostEdit": "PostToolUse (matcher: Edit|Write)",+ "PreCommand": "PreToolUse (matcher: Bash)",+ "PostCommand": "PostToolUse (matcher: Bash)",+ "PreTask": "UserPromptSubmit",+ "PostTask": "PostToolUse (matcher: Task)",+ "SessionStart": "SessionStart",+ "SessionEnd": "Stop",+ "AgentSpawn": "PostToolUse (matcher: Task)",+ "AgentTerminate": "SubagentStop",+ "PreRoute": "UserPromptSubmit",+ "PostRoute": "PostToolUse",+ "PatternLearned": "PostToolUse (internal)",+ "PatternConsolidated": "Stop (internal)"+ }+}diff --git a/plugin/skills b/plugin/skillsnew file mode 120000index 0000000000..454b8427cd--- /dev/null+++ b/plugin/skills@@ -0,0 +1 @@+../.claude/skills\ No newline at end of filediff --git a/v3/@claude-flow/cli/src/init/types.ts b/v3/@claude-flow/cli/src/init/types.tsnew file mode 100644index 0000000000..6bbb7336d0--- /dev/null+++ b/v3/@claude-flow/cli/src/init/types.ts@@ -0,0 +1,379 @@+/**+ * V3 Init System Types+ * Configuration options for initializing Claude Code integration+ */++/**+ * Components that can be initialized+ */+export interface InitComponents {+ /** Create .claude/settings.json with hooks */+ settings: boolean;+ /** Copy skills to .claude/skills/ */+ skills: boolean;+ /** Copy commands to .claude/commands/ */+ commands: boolean;+ /** Copy agents to .claude/agents/ */+ agents: boolean;+ /** Create helper scripts in .claude/helpers/ */+ helpers: boolean;+ /** Configure statusline */+ statusline: boolean;+ /** Create MCP configuration */+ mcp: boolean;+ /** Create .claude-flow/ directory (V3 runtime) */+ runtime: boolean;+}++/**+ * Hook configuration options+ */+export interface HooksConfig {+ /** Enable PreToolUse hooks */+ preToolUse: boolean;+ /** Enable PostToolUse hooks */+ postToolUse: boolean;+ /** Enable UserPromptSubmit for routing */+ userPromptSubmit: boolean;+ /** Enable SessionStart hooks */+ sessionStart: boolean;+ /** Enable Stop hooks */+ stop: boolean;+ /** Enable Notification hooks */+ notification: boolean;+ /** Enable PermissionRequest auto-allow for claude-flow */+ permissionRequest: boolean;+ /** Hook timeout in milliseconds */+ timeout: number;+ /** Continue on hook error */+ continueOnError: boolean;+}++/**+ * Skills configuration+ */+export interface SkillsConfig {+ /** Include core skills (swarm, memory, sparc) */+ core: boolean;+ /** Include AgentDB skills */+ agentdb: boolean;+ /** Include GitHub integration skills */+ github: boolean;+ /** Include Flow Nexus skills */+ flowNexus: boolean;+ /** Include V3 implementation skills */+ v3: boolean;+ /** Include all available skills */+ all: boolean;+}++/**+ * Commands configuration+ */+export interface CommandsConfig {+ /** Include core commands */+ core: boolean;+ /** Include analysis commands */+ analysis: boolean;+ /** Include automation commands */+ automation: boolean;+ /** Include github commands */+ github: boolean;+ /** Include hooks commands */+ hooks: boolean;+ /** Include monitoring commands */+ monitoring: boolean;+ /** Include optimization commands */+ optimization: boolean;+ /** Include SPARC commands */+ sparc: boolean;+ /** Include all commands */+ all: boolean;+}++/**+ * Agents configuration+ */+export interface AgentsConfig {+ /** Include core agents (coder, tester, reviewer) */+ core: boolean;+ /** Include consensus agents */+ consensus: boolean;+ /** Include GitHub agents */+ github: boolean;+ /** Include hive-mind agents */+ hiveMind: boolean;+ /** Include SPARC agents */+ sparc: boolean;+ /** Include swarm coordinators */+ swarm: boolean;+ /** Include all agents */+ all: boolean;+}++/**+ * Statusline configuration+ */+export interface StatuslineConfig {+ /** Enable statusline */+ enabled: boolean;+ /** Show V3 progress */+ showProgress: boolean;+ /** Show security status */+ showSecurity: boolean;+ /** Show swarm activity */+ showSwarm: boolean;+ /** Show hooks metrics */+ showHooks: boolean;+ /** Show performance targets */+ showPerformance: boolean;+ /** Refresh interval in milliseconds */+ refreshInterval: number;+}++/**+ * MCP configuration+ */+export interface MCPConfig {+ /** Include claude-flow MCP server */+ claudeFlow: boolean;+ /** Include ruv-swarm MCP server */+ ruvSwarm: boolean;+ /** Include flow-nexus MCP server */+ flowNexus: boolean;+ /** Auto-start MCP server */+ autoStart: boolean;+ /** Server port */+ port: number;+}++/**+ * Runtime configuration (.claude-flow/)+ */+export interface RuntimeConfig {+ /** Swarm topology */+ topology: 'mesh' | 'hierarchical' | 'hierarchical-mesh' | 'adaptive';+ /** Maximum agents */+ maxAgents: number;+ /** Memory backend */+ memoryBackend: 'memory' | 'sqlite' | 'agentdb' | 'hybrid';+ /** Enable HNSW indexing */+ enableHNSW: boolean;+ /** Enable neural learning */+ enableNeural: boolean;+}++/**+ * Complete init options+ */+export interface InitOptions {+ /** Target directory */+ targetDir: string;+ /** Force overwrite existing files */+ force: boolean;+ /** Run in interactive mode */+ interactive: boolean;+ /** Components to initialize */+ components: InitComponents;+ /** Hooks configuration */+ hooks: HooksConfig;+ /** Skills configuration */+ skills: SkillsConfig;+ /** Commands configuration */+ commands: CommandsConfig;+ /** Agents configuration */+ agents: AgentsConfig;+ /** Statusline configuration */+ statusline: StatuslineConfig;+ /** MCP configuration */+ mcp: MCPConfig;+ /** Runtime configuration */+ runtime: RuntimeConfig;+}++/**+ * Default init options - full V3 setup+ */+export const DEFAULT_INIT_OPTIONS: InitOptions = {+ targetDir: process.cwd(),+ force: false,+ interactive: true,+ components: {+ settings: true,+ skills: true,+ commands: true,+ agents: true,+ helpers: true,+ statusline: true,+ mcp: true,+ runtime: true,+ },+ hooks: {+ preToolUse: true,+ postToolUse: true,+ userPromptSubmit: true,+ sessionStart: true,+ stop: true,+ notification: true,+ permissionRequest: true,+ timeout: 5000,+ continueOnError: true,+ },+ skills: {+ core: true,+ agentdb: true,+ github: true,+ flowNexus: false,+ v3: true,+ all: false,+ },+ commands: {+ core: true,+ analysis: true,+ automation: true,+ github: true,+ hooks: true,+ monitoring: true,+ optimization: true,+ sparc: true,+ all: false,+ },+ agents: {+ core: true,+ consensus: false,+ github: true,+ hiveMind: true,+ sparc: true,+ swarm: true,+ all: false,+ },+ statusline: {+ enabled: true,+ showProgress: true,+ showSecurity: true,+ showSwarm: true,+ showHooks: true,+ showPerformance: true,+ refreshInterval: 5000,+ },+ mcp: {+ claudeFlow: true,+ ruvSwarm: false,+ flowNexus: false,+ autoStart: false,+ port: 3000,+ },+ runtime: {+ topology: 'hierarchical-mesh',+ maxAgents: 15,+ memoryBackend: 'hybrid',+ enableHNSW: true,+ enableNeural: true,+ },+};++/**+ * Minimal init options+ */+export const MINIMAL_INIT_OPTIONS: InitOptions = {+ ...DEFAULT_INIT_OPTIONS,+ components: {+ settings: true,+ skills: true,+ commands: false,+ agents: false,+ helpers: false,+ statusline: false,+ mcp: true,+ runtime: true,+ },+ hooks: {+ ...DEFAULT_INIT_OPTIONS.hooks,+ userPromptSubmit: false,+ stop: false,+ notification: false,+ },+ skills: {+ core: true,+ agentdb: false,+ github: false,+ flowNexus: false,+ v3: false,+ all: false,+ },+ agents: {+ core: true,+ consensus: false,+ github: false,+ hiveMind: false,+ sparc: false,+ swarm: false,+ all: false,+ },+ runtime: {+ topology: 'mesh',+ maxAgents: 5,+ memoryBackend: 'memory',+ enableHNSW: false,+ enableNeural: false,+ },+};++/**+ * Full init options (everything enabled)+ */+export const FULL_INIT_OPTIONS: InitOptions = {+ ...DEFAULT_INIT_OPTIONS,+ components: {+ settings: true,+ skills: true,+ commands: true,+ agents: true,+ helpers: true,+ statusline: true,+ mcp: true,+ runtime: true,+ },+ skills: {+ core: true,+ agentdb: true,+ github: true,+ flowNexus: true,+ v3: true,+ all: true,+ },+ commands: {+ ...DEFAULT_INIT_OPTIONS.commands,+ all: true,+ },+ agents: {+ ...DEFAULT_INIT_OPTIONS.agents,+ all: true,+ },+ mcp: {+ claudeFlow: true,+ ruvSwarm: true,+ flowNexus: true,+ autoStart: false,+ port: 3000,+ },+};++/**+ * Init result+ */+export interface InitResult {+ success: boolean;+ created: {+ directories: string[];+ files: string[];+ };+ skipped: string[];+ errors: string[];+ summary: {+ skillsCount: number;+ commandsCount: number;+ agentsCount: number;+ hooksEnabled: number;+ };+}diff --git a/v3/@claude-flow/hooks/src/bridge/official-hooks-bridge.ts b/v3/@claude-flow/hooks/src/bridge/official-hooks-bridge.tsnew file mode 100644index 0000000000..70e4670344--- /dev/null+++ b/v3/@claude-flow/hooks/src/bridge/official-hooks-bridge.ts@@ -0,0 +1,378 @@+/**+ * Official Claude Code Hooks Bridge+ *+ * Maps V3 internal hook events to official Claude Code hook events.+ * This bridge enables seamless integration between claude-flow's+ * internal hook system and the official Claude Code plugin API.+ *+ * @module v3/hooks/bridge/official-hooks-bridge+ */++import { HookEvent, HookPriority, type HookHandler, type HookContext, type HookResult } from '../types.js';++/**+ * Official Claude Code hook event types+ * Based on https://code.claude.com/docs/en/hooks+ */+export type OfficialHookEvent =+ | 'PreToolUse'+ | 'PostToolUse'+ | 'UserPromptSubmit'+ | 'PermissionRequest'+ | 'Notification'+ | 'Stop'+ | 'SubagentStop'+ | 'PreCompact'+ | 'SessionStart';++/**+ * Official hook input structure (received via stdin)+ */+export interface OfficialHookInput {+ session_id: string;+ transcript_path: string;+ cwd: string;+ permission_mode: string;+ hook_event_name: OfficialHookEvent;++ // Tool-specific fields+ tool_name?: string;+ tool_input?: Record<string, unknown>;+ tool_output?: unknown;+ tool_success?: boolean;+ tool_exit_code?: number;++ // Prompt-specific fields+ prompt?: string;++ // Notification-specific fields+ notification_message?: string;+ notification_level?: 'info' | 'warning' | 'error';+}++/**+ * Official hook output structure (returned via stdout)+ */+export interface OfficialHookOutput {+ /** Decision for permission/flow control */+ decision?: 'allow' | 'deny' | 'block' | 'ask' | 'approve' | 'stop' | 'continue';++ /** Reason for the decision */+ reason?: string;++ /** Whether to continue processing (false stops Claude) */+ continue?: boolean;++ /** Modified tool input (for PreToolUse) */+ updatedInput?: Record<string, unknown>;++ /** Suppress the tool call result display */+ suppressOutput?: boolean;+}++/**+ * Mapping from V3 HookEvent to Official hook events+ */+export const V3_TO_OFFICIAL_HOOK_MAP: Record<HookEvent, OfficialHookEvent | null> = {+ // Direct mappings+ [HookEvent.PreToolUse]: 'PreToolUse',+ [HookEvent.PostToolUse]: 'PostToolUse',+ [HookEvent.SessionStart]: 'SessionStart',++ // File operations map to tool hooks with matchers+ [HookEvent.PreEdit]: 'PreToolUse', // matcher: Edit|Write|MultiEdit+ [HookEvent.PostEdit]: 'PostToolUse', // matcher: Edit|Write|MultiEdit+ [HookEvent.PreRead]: 'PreToolUse', // matcher: Read+ [HookEvent.PostRead]: 'PostToolUse', // matcher: Read++ // Command operations map to tool hooks+ [HookEvent.PreCommand]: 'PreToolUse', // matcher: Bash+ [HookEvent.PostCommand]: 'PostToolUse', // matcher: Bash++ // Task operations+ [HookEvent.PreTask]: 'UserPromptSubmit',+ [HookEvent.PostTask]: 'PostToolUse', // matcher: Task+ [HookEvent.TaskProgress]: null, // Internal only++ // Session operations+ [HookEvent.SessionEnd]: 'Stop',+ [HookEvent.SessionRestore]: 'SessionStart',++ // Agent operations+ [HookEvent.AgentSpawn]: 'PostToolUse', // matcher: Task+ [HookEvent.AgentTerminate]: 'SubagentStop',++ // Routing (internal)+ [HookEvent.PreRoute]: 'UserPromptSubmit',+ [HookEvent.PostRoute]: null, // Internal only++ // Learning (internal)+ [HookEvent.PatternLearned]: null, // Internal only+ [HookEvent.PatternConsolidated]: null, // Internal only+};++/**+ * Tool matchers for V3 events that map to PreToolUse/PostToolUse+ */+export const V3_TOOL_MATCHERS: Partial<Record<HookEvent, string>> = {+ [HookEvent.PreEdit]: '^(Write|Edit|MultiEdit)$',+ [HookEvent.PostEdit]: '^(Write|Edit|MultiEdit)$',+ [HookEvent.PreRead]: '^Read$',+ [HookEvent.PostRead]: '^Read$',+ [HookEvent.PreCommand]: '^Bash$',+ [HookEvent.PostCommand]: '^Bash$',+ [HookEvent.PreTask]: '^Task$',+ [HookEvent.PostTask]: '^Task$',+ [HookEvent.AgentSpawn]: '^Task$',+};++/**+ * Bridge class for converting between V3 and official hooks+ */+export class OfficialHooksBridge {+ /**+ * Convert official hook input to V3 HookContext+ */+ static toV3Context(input: OfficialHookInput): HookContext {+ const event = this.officialToV3Event(input.hook_event_name, input.tool_name);++ const context: HookContext = {+ event,+ timestamp: new Date(),+ metadata: {+ session_id: input.session_id,+ transcript_path: input.transcript_path,+ cwd: input.cwd,+ permission_mode: input.permission_mode,+ },+ };++ // Add tool information+ if (input.tool_name) {+ context.tool = {+ name: input.tool_name,+ parameters: input.tool_input ?? {},+ };+ }++ // Add file information for file operations+ if (input.tool_name && ['Write', 'Edit', 'MultiEdit', 'Read'].includes(input.tool_name)) {+ context.file = {+ path: (input.tool_input?.file_path as string) ?? '',+ operation: input.tool_name === 'Read' ? 'read' : 'modify',+ };+ }++ // Add command information for Bash+ if (input.tool_name === 'Bash') {+ context.command = {+ raw: (input.tool_input?.command as string) ?? '',+ workingDirectory: input.cwd,+ exitCode: input.tool_exit_code,+ output: typeof input.tool_output === 'string' ? input.tool_output : undefined,+ };+ }++ // Add task information for Task tool+ if (input.tool_name === 'Task') {+ context.task = {+ id: `task-${Date.now()}`,+ description: (input.tool_input?.prompt as string) ?? '',+ agent: input.tool_input?.subagent_type as string,+ };+ }++ // Add session information+ context.session = {+ id: input.session_id,+ startedAt: new Date(),+ };++ // Add prompt for UserPromptSubmit+ if (input.prompt) {+ context.routing = {+ task: input.prompt,+ };+ }++ return context;+ }++ /**+ * Convert V3 HookResult to official hook output+ */+ static toOfficialOutput(result: HookResult, event: OfficialHookEvent): OfficialHookOutput {+ const output: OfficialHookOutput = {};++ // Map abort to decision+ if (result.abort) {+ output.decision = event === 'PermissionRequest' ? 'deny' : 'block';+ output.continue = false;+ } else if (result.success) {+ output.decision = event === 'PermissionRequest' ? 'allow' : 'continue';+ output.continue = true;+ }++ // Add reason+ if (result.error) {+ output.reason = result.error;+ } else if (result.message) {+ output.reason = result.message;+ }++ // Pass through updated input if present+ if (result.data?.updatedInput) {+ output.updatedInput = result.data.updatedInput as Record<string, unknown>;+ }++ return output;+ }++ /**+ * Convert official hook event to V3 HookEvent+ */+ static officialToV3Event(officialEvent: OfficialHookEvent, toolName?: string): HookEvent {+ // Handle tool-specific mappings+ if (officialEvent === 'PreToolUse' && toolName) {+ if (['Write', 'Edit', 'MultiEdit'].includes(toolName)) {+ return HookEvent.PreEdit;+ }+ if (toolName === 'Read') {+ return HookEvent.PreRead;+ }+ if (toolName === 'Bash') {+ return HookEvent.PreCommand;+ }+ if (toolName === 'Task') {+ return HookEvent.PreTask;+ }+ return HookEvent.PreToolUse;+ }++ if (officialEvent === 'PostToolUse' && toolName) {+ if (['Write', 'Edit', 'MultiEdit'].includes(toolName)) {+ return HookEvent.PostEdit;+ }+ if (toolName === 'Read') {+ return HookEvent.PostRead;+ }+ if (toolName === 'Bash') {+ return HookEvent.PostCommand;+ }+ if (toolName === 'Task') {+ return HookEvent.PostTask;+ }+ return HookEvent.PostToolUse;+ }++ // Direct mappings+ const mapping: Record<OfficialHookEvent, HookEvent> = {+ PreToolUse: HookEvent.PreToolUse,+ PostToolUse: HookEvent.PostToolUse,+ UserPromptSubmit: HookEvent.PreTask,+ PermissionRequest: HookEvent.PreToolUse,+ Notification: HookEvent.PostTask, // Closest match+ Stop: HookEvent.SessionEnd,+ SubagentStop: HookEvent.AgentTerminate,+ PreCompact: HookEvent.SessionEnd, // Closest match+ SessionStart: HookEvent.SessionStart,+ };++ return mapping[officialEvent] ?? HookEvent.PreToolUse;+ }++ /**+ * Get tool matcher for a V3 event+ */+ static getToolMatcher(event: HookEvent): string | null {+ return V3_TOOL_MATCHERS[event] ?? null;+ }++ /**+ * Check if V3 event maps to an official hook+ */+ static hasOfficialMapping(event: HookEvent): boolean {+ return V3_TO_OFFICIAL_HOOK_MAP[event] !== null;+ }++ /**+ * Create a CLI command for a V3 hook handler+ */+ static createCLICommand(event: HookEvent, handler: string): string {+ const baseCommand = 'npx claude-flow@alpha hooks';++ switch (event) {+ case HookEvent.PreEdit:+ return `${baseCommand} pre-edit --file "$TOOL_INPUT_file_path"`;+ case HookEvent.PostEdit:+ return `${baseCommand} post-edit --file "$TOOL_INPUT_file_path" --success "$TOOL_SUCCESS" --train-patterns`;+ case HookEvent.PreCommand:+ return `${baseCommand} pre-command --command "$TOOL_INPUT_command"`;+ case HookEvent.PostCommand:+ return `${baseCommand} post-command --command "$TOOL_INPUT_command" --success "$TOOL_SUCCESS"`;+ case HookEvent.PreTask:+ return `${baseCommand} pre-task --description "$PROMPT"`;+ case HookEvent.PostTask:+ return `${baseCommand} post-task --task-id "$TOOL_RESULT_agent_id" --analyze-performance`;+ case HookEvent.SessionStart:+ return `${baseCommand} session-start --session-id "$SESSION_ID" --load-context`;+ case HookEvent.SessionEnd:+ return `${baseCommand} session-end --session-id "$SESSION_ID" --export-metrics`;+ default:+ return `${baseCommand} ${handler}`;+ }+ }+}++/**+ * Process stdin from official Claude Code hook system+ */+export async function processOfficialHookInput(): Promise<OfficialHookInput | null> {+ return new Promise((resolve) => {+ let data = '';++ process.stdin.setEncoding('utf8');+ process.stdin.on('readable', () => {+ let chunk;+ while ((chunk = process.stdin.read()) !== null) {+ data += chunk;+ }+ });++ process.stdin.on('end', () => {+ try {+ resolve(JSON.parse(data));+ } catch {+ resolve(null);+ }+ });++ // Handle case where no stdin (testing)+ setTimeout(() => {+ if (!data) {+ resolve(null);+ }+ }, 100);+ });+}++/**+ * Output result to official Claude Code hook system+ */+export function outputOfficialHookResult(output: OfficialHookOutput): void {+ console.log(JSON.stringify(output));+}++/**+ * Execute a V3 handler and bridge to official output+ */+export async function executeWithBridge(+ input: OfficialHookInput,+ handler: HookHandler+): Promise<OfficialHookOutput> {+ const context = OfficialHooksBridge.toV3Context(input);+ const result = await handler(context);+ return OfficialHooksBridge.toOfficialOutput(result, input.hook_event_name);+}++export default OfficialHooksBridge;diff --git a/v3/@claude-flow/hooks/src/index.ts b/v3/@claude-flow/hooks/src/index.tsindex af6cf0a867..ca8d9085d0 100644--- a/v3/@claude-flow/hooks/src/index.ts+++ b/v3/@claude-flow/hooks/src/index.ts@@ -63,6 +63,19 @@ export {type MCPTool,} from './mcp/index.js';+// Official Claude Code Hooks Bridge+export {+ OfficialHooksBridge,+ V3_TO_OFFICIAL_HOOK_MAP,+ V3_TOOL_MATCHERS,+ processOfficialHookInput,+ outputOfficialHookResult,+ executeWithBridge,+ type OfficialHookEvent,+ type OfficialHookInput,+ type OfficialHookOutput,+} from './bridge/official-hooks-bridge.js';+// Versionexport const VERSION = '3.0.0-alpha.1';diff --git a/v3/implementation/PLUGIN_INTEGRATION.md b/v3/implementation/PLUGIN_INTEGRATION.mdnew file mode 100644index 0000000000..9082f41cc3--- /dev/null+++ b/v3/implementation/PLUGIN_INTEGRATION.md@@ -0,0 +1,240 @@+# 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`)++```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:++```yaml+---+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:++```typescript+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)++```bash+# Add plugin marketplace+/plugin marketplace add claude-flow https://github.com/ruvnet/claude-flow++# Install plugin+/plugin install claude-flow+```++### Manual Installation++```bash+# Clone and link+git clone https://github.com/ruvnet/claude-flow+claude --plugin-dir ./claude-flow/plugin+```++### Via npx Init++```bash+npx claude-flow@alpha init --hooks+```++## Configuration++### Enable All Hooks++Add to `.claude/settings.json`:++```json+{+ "hooks": {+ "PreToolUse": [...],+ "PostToolUse": [...],+ "UserPromptSubmit": [...],+ "SessionStart": [...],+ "Stop": [...]+ }+}+```++### Selective Hooks++Enable only specific hooks by choosing matchers:++```json+{+ "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++```json+{+ "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