agentic-flow 1.1.2 → 1.1.4

package/docs/PACKAGE_STRUCTURE.md

@@ -0,0 +1,199 @@
+# agentic-flow Package Structure
+
+## Overview
+
+The `agentic-flow` npm package includes all necessary files for agent execution, including 76 pre-built agent definitions in the `.claude/agents/` directory.
+
+## Package Contents
+
+When you install `agentic-flow` via npm, you get:
+
+```
+agentic-flow/
+├── dist/                    # Compiled JavaScript
+│   ├── cli-proxy.js         # Main CLI entry point
+│   ├── agents/              # Agent implementations
+│   ├── router/              # Multi-provider router
+│   └── utils/               # Utilities
+├── .claude/                 # Agent definitions (76 files)
+│   └── agents/
+│       ├── core/            # Core agents (coder, planner, reviewer, etc.)
+│       ├── consensus/       # Distributed consensus agents
+│       ├── github/          # GitHub integration agents
+│       ├── flow-nexus/      # Flow Nexus cloud agents
+│       ├── sparc/           # SPARC methodology agents
+│       └── ...              # More specialized categories
+├── docs/                    # Documentation
+├── README.md
+└── LICENSE
+```
+
+## Agent Loading System
+
+### Package Agents (Bundled)
+
+All 76 agent definitions are included in the npm package at:
+```
+node_modules/agentic-flow/.claude/agents/
+```
+
+These are automatically loaded when you run `npx agentic-flow`.
+
+### Local Agents (User Custom)
+
+You can create custom agents in your project:
+```
+your-project/
+└── .claude/
+    └── agents/
+        └── custom/
+            └── my-agent.md
+```
+
+**Local agents override package agents** with the same relative path.
+
+## Agent Discovery Order
+
+1. **Package agents**: Load from `node_modules/agentic-flow/.claude/agents/`
+2. **Local agents**: Load from `./claude/agents/` (overrides package agents if same path)
+3. **Custom directory**: Use `--agents-dir` flag to specify alternative location
+
+## Verification
+
+To verify your installation includes all agents:
+
+```bash
+# List all available agents
+npx agentic-flow --list
+
+# Should show 73 agents (76 files, some without proper frontmatter)
+```
+
+## Custom Agent Creation
+
+Create custom agents that augment or replace package agents:
+
+```bash
+# Interactive creation
+npx agentic-flow agent create
+
+# Manual creation
+mkdir -p .claude/agents/custom
+cat > .claude/agents/custom/my-agent.md << 'EOF'
+---
+name: my-agent
+description: My custom agent
+---
+
+You are a specialized agent for [purpose].
+Follow these guidelines:
+- [guideline 1]
+- [guideline 2]
+EOF
+```
+
+## Package Maintenance
+
+### Building
+
+```bash
+npm run build
+```
+
+### Verifying Package Structure
+
+```bash
+./scripts/verify-package.sh
+```
+
+### Creating Package
+
+```bash
+npm pack
+```
+
+### Testing Installation
+
+```bash
+# Install in test directory
+mkdir -p /tmp/test-install
+cd /tmp/test-install
+npm install /path/to/agentic-flow-1.1.2.tgz
+
+# Verify agents loaded
+./node_modules/.bin/agentic-flow --list
+```
+
+## Environment Configuration
+
+The package automatically loads `.env` files from:
+1. Current directory
+2. Parent directories (recursively up to root)
+
+This ensures API keys work from any directory:
+
+```bash
+# Works from project root
+cd /workspaces/myproject
+npx agentic-flow --agent coder --task "test" --provider gemini
+
+# Also works from subdirectory (finds parent .env)
+cd /workspaces/myproject/src
+npx agentic-flow --agent coder --task "test" --provider gemini
+```
+
+## Files Included in Package
+
+See `package.json`:
+```json
+{
+  "files": [
+    "dist",
+    "docs",
+    ".claude",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+## Files Excluded (.npmignore)
+
+- Source files (`src/`, `*.ts`)
+- Tests (`tests/`, `validation/`)
+- Development files (`.env`, `tsconfig.json`)
+- Runtime state directories (`.claude-flow/`, `.swarm/`, `memory/`)
+- ONNX models (`*.onnx`, `models/`)
+
+## Agent Categories
+
+The 76 included agents span:
+
+- **Core** (5): coder, planner, researcher, reviewer, tester
+- **Consensus** (7): Byzantine, CRDT, Gossip, Raft, Quorum, etc.
+- **GitHub** (14): PR management, issue tracking, release automation
+- **Flow Nexus** (9): Cloud sandboxes, neural networks, workflows
+- **SPARC** (4): Specification, Pseudocode, Architecture, Refinement
+- **Optimization** (5): Resource allocation, load balancing, benchmarks
+- **Goal Planning** (2): GOAP, sublinear algorithms
+- **Swarm** (3): Hierarchical, mesh, adaptive coordination
+- **Payments** (1): Agentic payment authorization
+- **Templates** (10): Automation, orchestration, migration
+- **Testing** (2): TDD, production validation
+- **Specialized** (varies): Analysis, architecture, data, development, DevOps, documentation
+
+## Total Agent Count
+
+- **76 agent files** in `.claude/agents/`
+- **73 valid agents** (3 files missing required frontmatter)
+- **All core agents** (coder, planner, researcher, reviewer, tester) working
+
+## Summary
+
+✅ All 76 agent definitions are packaged and distributed via npm
+✅ Agent loading works automatically from `node_modules/`
+✅ Local `.claude/agents/` can override package agents
+✅ Environment variable loading works recursively
+✅ Package structure verified and tested
+
+The `.claude/` directory is a first-class part of the npm package, ensuring all users have immediate access to the complete agent library upon installation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 111 MCP tools, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols.",
   "type": "module",
   "main": "dist/index.js",

package/.claude/commands/coordination/README.md

@@ -1,9 +0,0 @@
-# Coordination Commands
-
-Commands for coordination operations in Claude Flow.
-
-## Available Commands
-
-- [swarm-init](./swarm-init.md)
-- [agent-spawn](./agent-spawn.md)
-- [task-orchestrate](./task-orchestrate.md)

package/.claude/commands/coordination/agent-spawn.md

@@ -1,25 +0,0 @@
-# agent-spawn
-
-Spawn a new agent in the current swarm.
-
-## Usage
-```bash
-npx claude-flow agent spawn [options]
-```
-
-## Options
-- `--type <type>` - Agent type (coder, researcher, analyst, tester, coordinator)
-- `--name <name>` - Custom agent name
-- `--skills <list>` - Specific skills (comma-separated)
-
-## Examples
-```bash
-# Spawn coder agent
-npx claude-flow agent spawn --type coder
-
-# With custom name
-npx claude-flow agent spawn --type researcher --name "API Expert"
-
-# With specific skills
-npx claude-flow agent spawn --type coder --skills "python,fastapi,testing"
-```

package/.claude/commands/coordination/init.md

@@ -1,44 +0,0 @@
-# Initialize Coordination Framework
-
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
-
-## MCP Tool Usage in Claude Code
-
-**Tool:** `mcp__claude-flow__swarm_init`
-
-## Parameters
-```json
-{"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}
-```
-
-## Description
-Set up a coordination topology to guide Claude Code's approach to complex tasks
-
-## Details
-This tool creates a coordination framework that helps Claude Code:
-- Break down complex problems systematically
-- Approach tasks from multiple perspectives
-- Maintain consistency across large projects
-- Work more efficiently through structured coordination
-
-Remember: This does NOT create actual coding agents. It creates a coordination pattern for Claude Code to follow.
-
-## Example Usage
-
-**In Claude Code:**
-1. Use the tool: `mcp__claude-flow__swarm_init`
-2. With parameters: `{"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}`
-3. Claude Code then executes the coordinated plan using its native tools
-
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
-
-## See Also
-- Main documentation: /claude.md
-- Other commands in this category
-- Workflow examples in /workflows/

package/.claude/commands/coordination/orchestrate.md

@@ -1,43 +0,0 @@
-# Coordinate Task Execution
-
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
-
-## MCP Tool Usage in Claude Code
-
-**Tool:** `mcp__claude-flow__task_orchestrate`
-
-## Parameters
-```json
-{"task": "Implement authentication system", "strategy": "parallel", "priority": "high"}
-```
-
-## Description
-Break down and coordinate complex tasks for systematic execution by Claude Code
-
-## Details
-Orchestration strategies:
-- **parallel**: Claude Code works on independent components simultaneously
-- **sequential**: Step-by-step execution for dependent tasks
-- **adaptive**: Dynamically adjusts based on task complexity
-
-The orchestrator creates a plan that Claude Code follows using its native tools.
-
-## Example Usage
-
-**In Claude Code:**
-1. Use the tool: `mcp__claude-flow__task_orchestrate`
-2. With parameters: `{"task": "Implement authentication system", "strategy": "parallel", "priority": "high"}`
-3. Claude Code then executes the coordinated plan using its native tools
-
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
-
-## See Also
-- Main documentation: /claude.md
-- Other commands in this category
-- Workflow examples in /workflows/

package/.claude/commands/coordination/spawn.md

@@ -1,45 +0,0 @@
-# Create Cognitive Patterns
-
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
-
-## MCP Tool Usage in Claude Code
-
-**Tool:** `mcp__claude-flow__agent_spawn`
-
-## Parameters
-```json
-{"type": "researcher", "name": "Literature Analysis", "capabilities": ["deep-analysis"]}
-```
-
-## Description
-Define cognitive patterns that represent different approaches Claude Code can take
-
-## Details
-Agent types represent thinking patterns, not actual coders:
-- **researcher**: Systematic exploration approach
-- **coder**: Implementation-focused thinking
-- **analyst**: Data-driven decision making
-- **architect**: Big-picture system design
-- **reviewer**: Quality and consistency checking
-
-These patterns guide how Claude Code approaches different aspects of your task.
-
-## Example Usage
-
-**In Claude Code:**
-1. Use the tool: `mcp__claude-flow__agent_spawn`
-2. With parameters: `{"type": "researcher", "name": "Literature Analysis", "capabilities": ["deep-analysis"]}`
-3. Claude Code then executes the coordinated plan using its native tools
-
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
-
-## See Also
-- Main documentation: /claude.md
-- Other commands in this category
-- Workflow examples in /workflows/

package/.claude/commands/coordination/swarm-init.md

@@ -1,85 +0,0 @@
-# swarm init
-
-Initialize a Claude Flow swarm with specified topology and configuration.
-
-## Usage
-
-```bash
-npx claude-flow swarm init [options]
-```
-
-## Options
-
-- `--topology, -t <type>` - Swarm topology: mesh, hierarchical, ring, star (default: hierarchical)
-- `--max-agents, -m <number>` - Maximum number of agents (default: 8)
-- `--strategy, -s <type>` - Execution strategy: balanced, parallel, sequential (default: parallel)
-- `--auto-spawn` - Automatically spawn agents based on task complexity
-- `--memory` - Enable cross-session memory persistence
-- `--github` - Enable GitHub integration features
-
-## Examples
-
-### Basic initialization
-
-```bash
-npx claude-flow swarm init
-```
-
-### Mesh topology for research
-
-```bash
-npx claude-flow swarm init --topology mesh --max-agents 5 --strategy balanced
-```
-
-### Hierarchical for development
-
-```bash
-npx claude-flow swarm init --topology hierarchical --max-agents 10 --strategy parallel --auto-spawn
-```
-
-### GitHub-focused swarm
-
-```bash
-npx claude-flow swarm init --topology star --github --memory
-```
-
-## Topologies
-
-### Mesh
-
-- All agents connect to all others
-- Best for: Research, exploration, brainstorming
-- Communication: High overhead, maximum information sharing
-
-### Hierarchical
-
-- Tree structure with clear command chain
-- Best for: Development, structured tasks, large projects
-- Communication: Efficient, clear responsibilities
-
-### Ring
-
-- Agents connect in a circle
-- Best for: Pipeline processing, sequential workflows
-- Communication: Low overhead, ordered processing
-
-### Star
-
-- Central coordinator with satellite agents
-- Best for: Simple tasks, centralized control
-- Communication: Minimal overhead, clear coordination
-
-## Integration with Claude Code
-
-Once initialized, use MCP tools in Claude Code:
-
-```javascript
-mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 8 }
-```
-
-## See Also
-
-- `agent spawn` - Create swarm agents
-- `task orchestrate` - Coordinate task execution
-- `swarm status` - Check swarm state
-- `swarm monitor` - Real-time monitoring

package/.claude/commands/coordination/task-orchestrate.md

@@ -1,25 +0,0 @@
-# task-orchestrate
-
-Orchestrate complex tasks across the swarm.
-
-## Usage
-```bash
-npx claude-flow task orchestrate [options]
-```
-
-## Options
-- `--task <description>` - Task description
-- `--strategy <type>` - Orchestration strategy
-- `--priority <level>` - Task priority (low, medium, high, critical)
-
-## Examples
-```bash
-# Orchestrate development task
-npx claude-flow task orchestrate --task "Implement user authentication"
-
-# High priority task
-npx claude-flow task orchestrate --task "Fix production bug" --priority critical
-
-# With specific strategy
-npx claude-flow task orchestrate --task "Refactor codebase" --strategy parallel
-```

package/.claude/commands/memory/README.md

@@ -1,9 +0,0 @@
-# Memory Commands
-
-Commands for memory operations in Claude Flow.
-
-## Available Commands
-
-- [memory-usage](./memory-usage.md)
-- [memory-persist](./memory-persist.md)
-- [memory-search](./memory-search.md)

package/.claude/commands/memory/memory-persist.md

@@ -1,25 +0,0 @@
-# memory-persist
-
-Persist memory across sessions.
-
-## Usage
-```bash
-npx claude-flow memory persist [options]
-```
-
-## Options
-- `--export <file>` - Export to file
-- `--import <file>` - Import from file
-- `--compress` - Compress memory data
-
-## Examples
-```bash
-# Export memory
-npx claude-flow memory persist --export memory-backup.json
-
-# Import memory
-npx claude-flow memory persist --import memory-backup.json
-
-# Compressed export
-npx claude-flow memory persist --export memory.gz --compress
-```

package/.claude/commands/memory/memory-search.md

@@ -1,25 +0,0 @@
-# memory-search
-
-Search through stored memory.
-
-## Usage
-```bash
-npx claude-flow memory search [options]
-```
-
-## Options
-- `--query <text>` - Search query
-- `--pattern <regex>` - Pattern matching
-- `--limit <n>` - Result limit
-
-## Examples
-```bash
-# Search memory
-npx claude-flow memory search --query "authentication"
-
-# Pattern search
-npx claude-flow memory search --pattern "api-.*"
-
-# Limited results
-npx claude-flow memory search --query "config" --limit 10
-```

package/.claude/commands/memory/memory-usage.md

@@ -1,25 +0,0 @@
-# memory-usage
-
-Manage persistent memory storage.
-
-## Usage
-```bash
-npx claude-flow memory usage [options]
-```
-
-## Options
-- `--action <type>` - Action (store, retrieve, list, clear)
-- `--key <key>` - Memory key
-- `--value <data>` - Data to store (JSON)
-
-## Examples
-```bash
-# Store memory
-npx claude-flow memory usage --action store --key "project-config" --value '{"api": "v2"}'
-
-# Retrieve memory
-npx claude-flow memory usage --action retrieve --key "project-config"
-
-# List all keys
-npx claude-flow memory usage --action list
-```

package/.claude/commands/memory/neural.md

@@ -1,47 +0,0 @@
-# Neural Pattern Training
-
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
-
-## MCP Tool Usage in Claude Code
-
-**Tool:** `mcp__claude-flow__neural_train`
-
-## Parameters
-```json
-{
-  "pattern_type": "coordination",
-  "training_data": "task decomposition patterns",
-  "epochs": 50
-}
-```
-
-## Description
-Improve coordination patterns through neural network training
-
-## Details
-Training improves:
-- Task breakdown effectiveness
-- Coordination pattern selection
-- Resource allocation strategies
-- Overall coordination efficiency
-
-## Example Usage
-
-**In Claude Code:**
-1. Train coordination patterns: Use tool `mcp__claude-flow__neural_train` with parameters `{"pattern_type": "coordination", "training_data": "successful task patterns", "epochs": 50}`
-2. Train optimization patterns: Use tool `mcp__claude-flow__neural_train` with parameters `{"pattern_type": "optimization", "training_data": "performance metrics", "epochs": 30}`
-3. Check training status: Use tool `mcp__claude-flow__neural_status`
-4. Analyze patterns: Use tool `mcp__claude-flow__neural_patterns` with parameters `{"action": "analyze"}`
-
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
-
-## See Also
-- Main documentation: /CLAUDE.md
-- Other commands in this category
-- Workflow examples in /workflows/

package/.claude/commands/memory/usage.md

@@ -1,46 +0,0 @@
-# Memory Management
-
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
-
-## MCP Tool Usage in Claude Code
-
-**Tool:** `mcp__claude-flow__memory_usage`
-
-## Parameters
-```json
-{
-  "action": "retrieve",
-  "namespace": "default"
-}
-```
-
-## Description
-Track persistent memory usage across Claude Code sessions
-
-## Details
-Memory helps Claude Code:
-- Maintain context between sessions
-- Remember project decisions
-- Track implementation patterns
-- Store coordination strategies that worked well
-
-## Example Usage
-
-**In Claude Code:**
-1. Store memory: Use tool `mcp__claude-flow__memory_usage` with parameters `{"action": "store", "key": "project_context", "value": "authentication system design"}`
-2. Retrieve memory: Use tool `mcp__claude-flow__memory_usage` with parameters `{"action": "retrieve", "key": "project_context"}`
-3. List memories: Use tool `mcp__claude-flow__memory_usage` with parameters `{"action": "list", "namespace": "default"}`
-4. Search memories: Use tool `mcp__claude-flow__memory_search` with parameters `{"pattern": "auth*"}`
-
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
-
-## See Also
-- Main documentation: /CLAUDE.md
-- Other commands in this category
-- Workflow examples in /workflows/