agentic-flow 1.0.0

package/docs/integrations/CLAUDE_AGENTS_INTEGRATION.md

@@ -0,0 +1,356 @@
+# .claude/agents Integration
+
+This document explains how to use agents from `.claude/agents/` directory with the Claude Agent SDK.
+
+## Overview
+
+The Claude Agent SDK now supports loading and using agent definitions from your `.claude/agents/` directory. This allows you to:
+
+- **Reuse existing agents** from your Claude Code configuration
+- **Centralize agent definitions** in one location
+- **Mix and match** specialized agents for different tasks
+- **Leverage agent metadata** like descriptions and tools
+
+## Quick Start
+
+### 1. Using a Single Agent
+
+```typescript
+import { getAgent } from './utils/agentLoader.js';
+import { claudeAgent } from './agents/claudeAgent.js';
+
+// Load the goal-planner agent
+const goalPlanner = getAgent('goal-planner');
+
+// Use it
+const result = await claudeAgent(
+  goalPlanner,
+  'Create a plan to improve our API performance'
+);
+
+console.log(result.output);
+```
+
+### 2. Using Multiple Agents
+
+```typescript
+import { loadAgents } from './utils/agentLoader.js';
+import { claudeAgent } from './agents/claudeAgent.js';
+
+// Load all agents
+const agents = loadAgents();
+
+// Use different agents for different tasks
+const planner = agents.get('goal-planner');
+const coder = agents.get('coder');
+const reviewer = agents.get('reviewer');
+
+// Execute in sequence
+const plan = await claudeAgent(planner, 'Plan feature X');
+const code = await claudeAgent(coder, 'Implement ' + plan.output);
+const review = await claudeAgent(reviewer, 'Review: ' + code.output);
+```
+
+### 3. Parallel Execution
+
+```typescript
+const agents = loadAgents();
+
+// Run multiple agents in parallel
+const [research, analysis, design] = await Promise.all([
+  claudeAgent(agents.get('researcher'), 'Research topic X'),
+  claudeAgent(agents.get('code-analyzer'), 'Analyze codebase'),
+  claudeAgent(agents.get('system-architect'), 'Design solution')
+]);
+```
+
+## Agent Definition Format
+
+Agents in `.claude/agents/` use markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: "What this agent does"
+color: purple
+tools: Read, Write, Bash
+---
+
+You are a specialized agent that...
+
+Your capabilities:
+- Capability 1
+- Capability 2
+
+[Rest of system prompt]
+```
+
+**Required fields**:
+- `name`: Unique identifier
+- `description`: Short description of agent's purpose
+
+**Optional fields**:
+- `color`: Display color in UI
+- `tools`: Comma-separated list of tools
+
+## Available Agents
+
+Run this to see all loaded agents:
+
+```bash
+npm run example:multi-agent
+```
+
+### Some Notable Agents
+
+From `.claude/agents/`:
+
+**Planning & Strategy**:
+- `goal-planner` - GOAP-based planning and optimization
+- `planner` - Strategic planning and task orchestration
+
+**Development**:
+- `coder` - Clean code implementation
+- `reviewer` - Code review specialist
+- `tester` - Testing and QA
+
+**Flow Nexus**:
+- `flow-nexus-swarm` - AI swarm orchestration
+- `flow-nexus-neural` - Neural network training
+- `flow-nexus-workflow` - Workflow automation
+
+**GitHub Integration**:
+- `github-modes` - GitHub workflow orchestration
+- `pr-manager` - PR management
+- `code-review-swarm` - Automated code reviews
+
+**Consensus & Coordination**:
+- `raft-manager` - Raft consensus
+- `byzantine-coordinator` - Byzantine fault tolerance
+- `gossip-coordinator` - Gossip protocols
+
+## Examples
+
+### Example 1: Goal-Planner Agent
+
+```bash
+npm run example:goal-planner
+```
+
+This demonstrates using the goal-planner agent to create improvement plans.
+
+### Example 2: Multi-Agent Orchestration
+
+```bash
+npm run example:multi-agent
+```
+
+This shows:
+- Loading all available agents
+- Using multiple agents in sequence
+- Agent discovery and listing
+
+## API Reference
+
+### `loadAgents(agentsDir?: string): Map<string, AgentDefinition>`
+
+Load all agents from directory.
+
+**Parameters**:
+- `agentsDir` - Path to agents directory (default: `/workspaces/flow-cloud/.claude/agents`)
+
+**Returns**: Map of agent name to AgentDefinition
+
+**Example**:
+```typescript
+const agents = loadAgents();
+console.log(`Loaded ${agents.size} agents`);
+```
+
+### `getAgent(name: string, agentsDir?: string): AgentDefinition | undefined`
+
+Get a specific agent by name.
+
+**Parameters**:
+- `name` - Agent name
+- `agentsDir` - Optional agents directory path
+
+**Returns**: AgentDefinition or undefined
+
+**Example**:
+```typescript
+const goalPlanner = getAgent('goal-planner');
+if (goalPlanner) {
+  console.log(goalPlanner.description);
+}
+```
+
+### `listAgents(agentsDir?: string): AgentDefinition[]`
+
+Get array of all agents.
+
+**Parameters**:
+- `agentsDir` - Optional agents directory path
+
+**Returns**: Array of AgentDefinition
+
+**Example**:
+```typescript
+const allAgents = listAgents();
+allAgents.forEach(agent => {
+  console.log(`${agent.name}: ${agent.description}`);
+});
+```
+
+### `claudeAgent(agent: AgentDefinition, input: string, onStream?: (chunk: string) => void)`
+
+Execute an agent with given input.
+
+**Parameters**:
+- `agent` - AgentDefinition from loadAgents()
+- `input` - Prompt/task for the agent
+- `onStream` - Optional streaming callback
+
+**Returns**: `{ output: string, agent: string }`
+
+**Example**:
+```typescript
+const result = await claudeAgent(
+  goalPlanner,
+  'Create a 3-step plan',
+  (chunk) => process.stdout.write(chunk)
+);
+```
+
+## AgentDefinition Type
+
+```typescript
+interface AgentDefinition {
+  name: string;           // Agent identifier
+  description: string;    // What the agent does
+  systemPrompt: string;   // Full system prompt
+  color?: string;         // Optional UI color
+  tools?: string[];       // Optional tool list
+  filePath: string;       // Source file path
+}
+```
+
+## Creating Custom Agents
+
+1. Create a markdown file in `.claude/agents/`:
+
+```markdown
+---
+name: my-custom-agent
+description: "Specialized agent for my use case"
+color: blue
+---
+
+You are a specialized agent for...
+
+Your focus areas:
+- Area 1
+- Area 2
+```
+
+2. Use it in your code:
+
+```typescript
+const myAgent = getAgent('my-custom-agent');
+const result = await claudeAgent(myAgent, 'Do something');
+```
+
+## Docker Integration
+
+The agent loader works in Docker containers if you mount the `.claude/agents` directory:
+
+```bash
+docker run -v /path/to/.claude/agents:/app/.claude/agents \
+  claude-agents:latest
+```
+
+Or in docker-compose.yml:
+
+```yaml
+services:
+  agents:
+    volumes:
+      - ../../.claude/agents:/app/.claude/agents:ro
+```
+
+## Troubleshooting
+
+### Agent Not Found
+
+```typescript
+const agent = getAgent('my-agent');
+if (!agent) {
+  console.error('Agent not found. Available agents:');
+  listAgents().forEach(a => console.log(`  - ${a.name}`));
+}
+```
+
+### Missing Frontmatter
+
+Agents must have valid frontmatter:
+```
+---
+name: agent-name
+description: "Agent description"
+---
+```
+
+Check logs for warnings about missing metadata.
+
+### Path Issues in Docker
+
+Ensure the path in agentLoader.ts matches your Docker setup:
+```typescript
+const agents = loadAgents('/app/.claude/agents');
+```
+
+## Best Practices
+
+1. **Use Descriptive Names**: Agent names should be clear and specific
+2. **Keep System Prompts Focused**: Each agent should have a clear, single purpose
+3. **Document Tools**: List required tools in frontmatter
+4. **Version Control**: Keep agent definitions in git
+5. **Test Agents**: Validate new agents work before deploying
+
+## Advanced: Custom Agent Directory
+
+You can organize agents in subdirectories:
+
+```
+.claude/agents/
+  ├── planning/
+  │   ├── goal-planner.md
+  │   └── strategic-planner.md
+  ├── development/
+  │   ├── coder.md
+  │   └── reviewer.md
+  └── operations/
+      └── deployment.md
+```
+
+The loader recursively scans all subdirectories.
+
+## Performance
+
+- **Load Time**: ~50ms for 74 agents
+- **Memory**: ~10KB per agent definition
+- **Caching**: Agents loaded once at startup
+
+## Next Steps
+
+- Explore existing agents in `.claude/agents/`
+- Create custom agents for your use cases
+- Combine agents in workflows
+- Add error handling and retry logic
+- Implement agent chaining patterns
+
+## See Also
+
+- [Quick Wins Implementation](../docs/QUICK_WINS.md)
+- [Improvement Plan](../docs/IMPROVEMENT_PLAN.md)
+- [Examples](../src/examples/)