agentic-flow 1.8.15 → 1.9.0

package/agentic-flow/docs/CLAUDE.md

@@ -0,0 +1,352 @@
+# Claude Code Configuration - SPARC Development Environment
+
+## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
+
+**ABSOLUTE RULES**:
+1. ALL operations MUST be concurrent/parallel in a single message
+2. **NEVER save working files, text/mds and tests to the root folder**
+3. ALWAYS organize files in appropriate subdirectories
+4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
+
+### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
+
+**MANDATORY PATTERNS:**
+- **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
+- **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
+- **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
+- **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
+- **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
+
+### 🎯 CRITICAL: Claude Code Task Tool for Agent Execution
+
+**Claude Code's Task tool is the PRIMARY way to spawn agents:**
+```javascript
+// ✅ CORRECT: Use Claude Code's Task tool for parallel agent execution
+[Single Message]:
+  Task("Research agent", "Analyze requirements and patterns...", "researcher")
+  Task("Coder agent", "Implement core features...", "coder")
+  Task("Tester agent", "Create comprehensive tests...", "tester")
+  Task("Reviewer agent", "Review code quality...", "reviewer")
+  Task("Architect agent", "Design system architecture...", "system-architect")
+```
+
+**MCP tools are ONLY for coordination setup:**
+- `mcp__claude-flow__swarm_init` - Initialize coordination topology
+- `mcp__claude-flow__agent_spawn` - Define agent types for coordination
+- `mcp__claude-flow__task_orchestrate` - Orchestrate high-level workflows
+
+### 📁 File Organization Rules
+
+**NEVER save to root folder. Use these directories:**
+- `/src` - Source code files
+- `/tests` - Test files
+- `/docs` - Documentation and markdown files
+- `/config` - Configuration files
+- `/scripts` - Utility scripts
+- `/examples` - Example code
+
+## Project Overview
+
+This project uses SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology with Claude-Flow orchestration for systematic Test-Driven Development.
+
+## SPARC Commands
+
+### Core Commands
+- `npx claude-flow sparc modes` - List available modes
+- `npx claude-flow sparc run <mode> "<task>"` - Execute specific mode
+- `npx claude-flow sparc tdd "<feature>"` - Run complete TDD workflow
+- `npx claude-flow sparc info <mode>` - Get mode details
+
+### Batchtools Commands
+- `npx claude-flow sparc batch <modes> "<task>"` - Parallel execution
+- `npx claude-flow sparc pipeline "<task>"` - Full pipeline processing
+- `npx claude-flow sparc concurrent <mode> "<tasks-file>"` - Multi-task processing
+
+### Build Commands
+- `npm run build` - Build project
+- `npm run test` - Run tests
+- `npm run lint` - Linting
+- `npm run typecheck` - Type checking
+
+## SPARC Workflow Phases
+
+1. **Specification** - Requirements analysis (`sparc run spec-pseudocode`)
+2. **Pseudocode** - Algorithm design (`sparc run spec-pseudocode`)
+3. **Architecture** - System design (`sparc run architect`)
+4. **Refinement** - TDD implementation (`sparc tdd`)
+5. **Completion** - Integration (`sparc run integration`)
+
+## Code Style & Best Practices
+
+- **Modular Design**: Files under 500 lines
+- **Environment Safety**: Never hardcode secrets
+- **Test-First**: Write tests before implementation
+- **Clean Architecture**: Separate concerns
+- **Documentation**: Keep updated
+
+## 🚀 Available Agents (54 Total)
+
+### Core Development
+`coder`, `reviewer`, `tester`, `planner`, `researcher`
+
+### Swarm Coordination
+`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager`
+
+### Consensus & Distributed
+`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager`
+
+### Performance & Optimization
+`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent`
+
+### GitHub & Repository
+`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm`
+
+### SPARC Methodology
+`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement`
+
+### Specialized Development
+`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
+
+### Testing & Validation
+`tdd-london-swarm`, `production-validator`
+
+### Migration & Planning
+`migration-planner`, `swarm-init`
+
+## 🎯 Claude Code vs MCP Tools
+
+### Claude Code Handles ALL EXECUTION:
+- **Task tool**: Spawn and run agents concurrently for actual work
+- File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
+- Code generation and programming
+- Bash commands and system operations
+- Implementation work
+- Project navigation and analysis
+- TodoWrite and task management
+- Git operations
+- Package management
+- Testing and debugging
+
+### MCP Tools ONLY COORDINATE:
+- Swarm initialization (topology setup)
+- Agent type definitions (coordination patterns)
+- Task orchestration (high-level planning)
+- Memory management
+- Neural features
+- Performance tracking
+- GitHub integration
+
+**KEY**: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.
+
+## 🚀 Quick Setup
+
+```bash
+# Add MCP servers (Claude Flow required, others optional)
+claude mcp add claude-flow npx claude-flow@alpha mcp start
+claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional: Enhanced coordination
+claude mcp add flow-nexus npx flow-nexus@latest mcp start  # Optional: Cloud features
+```
+
+## MCP Tool Categories
+
+### Coordination
+`swarm_init`, `agent_spawn`, `task_orchestrate`
+
+### Monitoring
+`swarm_status`, `agent_list`, `agent_metrics`, `task_status`, `task_results`
+
+### Memory & Neural
+`memory_usage`, `neural_status`, `neural_train`, `neural_patterns`
+
+### GitHub Integration
+`github_swarm`, `repo_analyze`, `pr_enhance`, `issue_triage`, `code_review`
+
+### System
+`benchmark_run`, `features_detect`, `swarm_monitor`
+
+### Flow-Nexus MCP Tools (Optional Advanced Features)
+Flow-Nexus extends MCP capabilities with 70+ cloud-based orchestration tools:
+
+**Key MCP Tool Categories:**
+- **Swarm & Agents**: `swarm_init`, `swarm_scale`, `agent_spawn`, `task_orchestrate`
+- **Sandboxes**: `sandbox_create`, `sandbox_execute`, `sandbox_upload` (cloud execution)
+- **Templates**: `template_list`, `template_deploy` (pre-built project templates)
+- **Neural AI**: `neural_train`, `neural_patterns`, `seraphina_chat` (AI assistant)
+- **GitHub**: `github_repo_analyze`, `github_pr_manage` (repository management)
+- **Real-time**: `execution_stream_subscribe`, `realtime_subscribe` (live monitoring)
+- **Storage**: `storage_upload`, `storage_list` (cloud file management)
+
+**Authentication Required:**
+- Register: `mcp__flow-nexus__user_register` or `npx flow-nexus@latest register`
+- Login: `mcp__flow-nexus__user_login` or `npx flow-nexus@latest login`
+- Access 70+ specialized MCP tools for advanced orchestration
+
+## 🚀 Agent Execution Flow with Claude Code
+
+### The Correct Pattern:
+
+1. **Optional**: Use MCP tools to set up coordination topology
+2. **REQUIRED**: Use Claude Code's Task tool to spawn agents that do actual work
+3. **REQUIRED**: Each agent runs hooks for coordination
+4. **REQUIRED**: Batch all operations in single messages
+
+### Example Full-Stack Development:
+
+```javascript
+// Single message with all agent spawning via Claude Code's Task tool
+[Parallel Agent Execution]:
+  Task("Backend Developer", "Build REST API with Express. Use hooks for coordination.", "backend-dev")
+  Task("Frontend Developer", "Create React UI. Coordinate with backend via memory.", "coder")
+  Task("Database Architect", "Design PostgreSQL schema. Store schema in memory.", "code-analyzer")
+  Task("Test Engineer", "Write Jest tests. Check memory for API contracts.", "tester")
+  Task("DevOps Engineer", "Setup Docker and CI/CD. Document in memory.", "cicd-engineer")
+  Task("Security Auditor", "Review authentication. Report findings via hooks.", "reviewer")
+  
+  // All todos batched together
+  TodoWrite { todos: [...8-10 todos...] }
+  
+  // All file operations together
+  Write "backend/server.js"
+  Write "frontend/App.jsx"
+  Write "database/schema.sql"
+```
+
+## 📋 Agent Coordination Protocol
+
+### Every Agent Spawned via Task Tool MUST:
+
+**1️⃣ BEFORE Work:**
+```bash
+npx claude-flow@alpha hooks pre-task --description "[task]"
+npx claude-flow@alpha hooks session-restore --session-id "swarm-[id]"
+```
+
+**2️⃣ DURING Work:**
+```bash
+npx claude-flow@alpha hooks post-edit --file "[file]" --memory-key "swarm/[agent]/[step]"
+npx claude-flow@alpha hooks notify --message "[what was done]"
+```
+
+**3️⃣ AFTER Work:**
+```bash
+npx claude-flow@alpha hooks post-task --task-id "[task]"
+npx claude-flow@alpha hooks session-end --export-metrics true
+```
+
+## 🎯 Concurrent Execution Examples
+
+### ✅ CORRECT WORKFLOW: MCP Coordinates, Claude Code Executes
+
+```javascript
+// Step 1: MCP tools set up coordination (optional, for complex tasks)
+[Single Message - Coordination Setup]:
+  mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 6 }
+  mcp__claude-flow__agent_spawn { type: "researcher" }
+  mcp__claude-flow__agent_spawn { type: "coder" }
+  mcp__claude-flow__agent_spawn { type: "tester" }
+
+// Step 2: Claude Code Task tool spawns ACTUAL agents that do the work
+[Single Message - Parallel Agent Execution]:
+  // Claude Code's Task tool spawns real agents concurrently
+  Task("Research agent", "Analyze API requirements and best practices. Check memory for prior decisions.", "researcher")
+  Task("Coder agent", "Implement REST endpoints with authentication. Coordinate via hooks.", "coder")
+  Task("Database agent", "Design and implement database schema. Store decisions in memory.", "code-analyzer")
+  Task("Tester agent", "Create comprehensive test suite with 90% coverage.", "tester")
+  Task("Reviewer agent", "Review code quality and security. Document findings.", "reviewer")
+  
+  // Batch ALL todos in ONE call
+  TodoWrite { todos: [
+    {id: "1", content: "Research API patterns", status: "in_progress", priority: "high"},
+    {id: "2", content: "Design database schema", status: "in_progress", priority: "high"},
+    {id: "3", content: "Implement authentication", status: "pending", priority: "high"},
+    {id: "4", content: "Build REST endpoints", status: "pending", priority: "high"},
+    {id: "5", content: "Write unit tests", status: "pending", priority: "medium"},
+    {id: "6", content: "Integration tests", status: "pending", priority: "medium"},
+    {id: "7", content: "API documentation", status: "pending", priority: "low"},
+    {id: "8", content: "Performance optimization", status: "pending", priority: "low"}
+  ]}
+  
+  // Parallel file operations
+  Bash "mkdir -p app/{src,tests,docs,config}"
+  Write "app/package.json"
+  Write "app/src/server.js"
+  Write "app/tests/server.test.js"
+  Write "app/docs/API.md"
+```
+
+### ❌ WRONG (Multiple Messages):
+```javascript
+Message 1: mcp__claude-flow__swarm_init
+Message 2: Task("agent 1")
+Message 3: TodoWrite { todos: [single todo] }
+Message 4: Write "file.js"
+// This breaks parallel coordination!
+```
+
+## Performance Benefits
+
+- **84.8% SWE-Bench solve rate**
+- **32.3% token reduction**
+- **2.8-4.4x speed improvement**
+- **27+ neural models**
+
+## Hooks Integration
+
+### Pre-Operation
+- Auto-assign agents by file type
+- Validate commands for safety
+- Prepare resources automatically
+- Optimize topology by complexity
+- Cache searches
+
+### Post-Operation
+- Auto-format code
+- Train neural patterns
+- Update memory
+- Analyze performance
+- Track token usage
+
+### Session Management
+- Generate summaries
+- Persist state
+- Track metrics
+- Restore context
+- Export workflows
+
+## Advanced Features (v2.0.0)
+
+- 🚀 Automatic Topology Selection
+- ⚡ Parallel Execution (2.8-4.4x speed)
+- 🧠 Neural Training
+- 📊 Bottleneck Analysis
+- 🤖 Smart Auto-Spawning
+- 🛡️ Self-Healing Workflows
+- 💾 Cross-Session Memory
+- 🔗 GitHub Integration
+
+## Integration Tips
+
+1. Start with basic swarm init
+2. Scale agents gradually
+3. Use memory for context
+4. Monitor progress regularly
+5. Train patterns from success
+6. Enable hooks automation
+7. Use GitHub tools first
+
+## Support
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues
+- Flow-Nexus Platform: https://flow-nexus.ruv.io (registration required for cloud features)
+
+---
+
+Remember: **Claude Flow coordinates, Claude Code creates!**
+
+# important-instruction-reminders
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+Never save working files, text/mds and tests to the root folder.

package/agentic-flow/docs/INDEX.md

@@ -0,0 +1,279 @@
+# Agentic Flow Documentation Index
+
+Complete documentation for the Agentic Flow multi-agent orchestration system.
+
+## 📋 Quick Navigation
+
+### 🚀 Start Here
+- **[README](../README.md)** - Project overview and getting started
+- **[CLAUDE.md](CLAUDE.md)** - Claude Code configuration and SPARC methodology
+- **[PACKAGE_STRUCTURE.md](architecture/PACKAGE_STRUCTURE.md)** - Package organization and structure
+- **[STANDALONE_PROXY_GUIDE.md](guides/STANDALONE_PROXY_GUIDE.md)** - Standalone proxy server setup
+
+---
+
+## 📚 Documentation Categories
+
+### 📖 [User Guides](guides/)
+Practical guides and tutorials for using the system.
+
+- [Agent SDK Guide](guides/agent-sdk.md) - Building custom agents
+- [Docker Agent Usage](guides/DOCKER_AGENT_USAGE.md) - Running agents in containers
+- [Alternative LLM Models](guides/ALTERNATIVE_LLM_MODELS.md) - Using different language models
+- [Implementation Examples](guides/IMPLEMENTATION_EXAMPLES.md) - Real-world patterns
+- [NPM Publishing Guide](guides/NPM-PUBLISH.md) - Package publishing
+- [ONNX CLI Usage](guides/ONNX_CLI_USAGE.md) - ONNX command-line interface
+- [ONNX Optimization Guide](guides/ONNX_OPTIMIZATION_GUIDE.md) - Performance optimization
+- [OpenRouter Deployment](guides/OPENROUTER_DEPLOYMENT.md) - OpenRouter setup
+
+### 🏗️ [Architecture](architecture/)
+System design, planning, and technical architecture.
+
+- [Executive Summary](architecture/EXECUTIVE_SUMMARY.md) - High-level overview
+- [Integration Status](architecture/INTEGRATION-STATUS.md) - Current integration status
+- [Research Summary](architecture/RESEARCH_SUMMARY.md) - Technical research findings
+- [Multi-Model Router Plan](architecture/MULTI_MODEL_ROUTER_PLAN.md) - Router architecture
+- [Improvement Plan](architecture/IMPROVEMENT_PLAN.md) - System improvement roadmap
+- [Quick Wins](architecture/QUICK_WINS.md) - High-impact improvements
+
+### 🔌 [Integrations](integrations/)
+Integration guides for external services and frameworks.
+
+- [Claude Agents Integration](integrations/CLAUDE_AGENTS_INTEGRATION.md) - Claude agents setup
+- [Claude Flow Integration](integrations/CLAUDE_FLOW_INTEGRATION.md) - Claude Flow orchestration
+- [Flow Nexus Integration](integrations/FLOW-NEXUS-INTEGRATION.md) - Cloud platform integration
+- [FastMCP CLI Integration](integrations/FASTMCP_CLI_INTEGRATION.md) - MCP command-line tools
+- [FastMCP Implementation Plan](integrations/fastmcp-implementation-plan.md) - Detailed MCP strategy
+- [FastMCP POC Integration](integrations/fastmcp-poc-integration.md) - Proof of concept
+
+### 🔧 [Router Documentation](router/)
+Multi-model router configuration and usage.
+
+- [Router Overview](router/README.md) - Router system overview
+- [Router User Guide](router/ROUTER_USER_GUIDE.md) - Using the router
+- [Router Config Reference](router/ROUTER_CONFIG_REFERENCE.md) - Configuration options
+- [Top 20 Models Matrix](router/TOP20_MODELS_MATRIX.md) - Model comparison guide
+
+### ✅ [Testing & Validation](testing/)
+Current test results and development testing documentation.
+
+- [Testing Overview](testing/README.md) - Current testing documentation
+- [Agent System Validation](testing/AGENT-SYSTEM-VALIDATION.md) - Multi-agent testing
+- [Final Testing Summary](testing/FINAL-TESTING-SUMMARY.md) - Comprehensive coverage
+- [Regression Test Results](testing/REGRESSION-TEST-RESULTS.md) - Regression testing
+- [Streaming & MCP Validation](testing/STREAMING-AND-MCP-VALIDATION.md) - Integration tests
+
+For production validation reports, see [Validation Reports](validation-reports/)
+
+### 🔍 [MCP Validation](mcp-validation/)
+Model Context Protocol implementation and validation.
+
+- [MCP Validation Overview](mcp-validation/README.md) - MCP testing documentation
+- [Implementation Summary](mcp-validation/IMPLEMENTATION-SUMMARY.md) - MCP implementation
+- [CLI Validation Report](mcp-validation/MCP-CLI-VALIDATION-REPORT.md) - CLI tool testing
+- [Strange Loops Test](mcp-validation/strange-loops-test.md) - Advanced patterns
+
+### 📦 [Version Releases](version-releases/)
+Version-specific release notes and publishing documentation.
+
+- [Release Overview](version-releases/README.md) - Release documentation index
+- [v1.5.11 Publication Report](version-releases/PUBLICATION_REPORT_v1.5.11.md) - Latest release
+- [v1.5.9 Release Summary](version-releases/v1.5.9-RELEASE-SUMMARY.md) - Previous release
+- [v1.5.9 Docker Verification](version-releases/v1.5.9-DOCKER-VERIFICATION.md) - Docker validation
+
+### 🧠 [ReasoningBank](reasoningbank/)
+Cognitive memory system with pattern recognition and adaptive learning.
+
+- [ReasoningBank Overview](reasoningbank/README.md) - Feature documentation index
+- [Architecture](reasoningbank/REASONINGBANK_ARCHITECTURE.md) - System architecture
+- [Backends](reasoningbank/REASONINGBANK_BACKENDS.md) - Storage backend options
+- [Validation](reasoningbank/REASONINGBANK_VALIDATION.md) - Testing and validation
+- [Benchmarks](reasoningbank/REASONINGBANK-BENCHMARK-RESULTS.md) - Performance metrics
+
+### ✅ [Validation Reports](validation-reports/)
+Comprehensive testing, benchmarking, and quality assurance reports.
+
+- [Validation Overview](validation-reports/README.md) - Testing documentation index
+- [Performance Benchmarks](validation-reports/BENCHMARK_AND_OPTIMIZATION_REPORT.md) - Optimization analysis
+- [Docker Validation](validation-reports/DOCKER_VALIDATION_RESULTS.md) - Container testing
+- [Regression Tests](validation-reports/NO_REGRESSIONS_CONFIRMED.md) - Stability verification
+- [Alpha Validation](validation-reports/V2.7.0-ALPHA.10_FINAL_VALIDATION.md) - Release validation
+
+### 🔌 [Integration Documentation](integration-docs/)
+System integrations, implementations, and compatibility reports.
+
+- [Integration Overview](integration-docs/README.md) - Integration documentation index
+- [Agent Booster](integration-docs/AGENT-BOOSTER-INTEGRATION.md) - Ultra-fast code editing
+- [Claude Flow](integration-docs/CLAUDE-FLOW-INTEGRATION-ANALYSIS.md) - Orchestration integration
+- [WASM Integration](integration-docs/WASM_INTEGRATION_COMPLETE.md) - WebAssembly support
+- [CLI Tools](integration-docs/CLI-INTEGRATION-COMPLETE.md) - Command-line integration
+
+### 🔬 [Quantum Research](quantum-research/)
+Quantum computing research, literature reviews, and experimental plans.
+
+- [Quantum Overview](quantum-research/README.md) - Research documentation index
+- [Literature Review](quantum-research/QUANTUM_RESEARCH_LITERATURE_REVIEW.md) - Comprehensive research
+- [Observer-Agnostic Experiment](../examples/Observer-Agnostic%20Measurement%20and%20No-Retrocausal%20Marginals%20Theorem/) - Quantum measurement testing
+
+### 🗄️ [Validation Archive](validation/)
+Historical validation reports and test archives.
+
+- [Validation Archive](validation/README.md) - Archived test reports
+
+### 📦 [Archived](archived/)
+Historical documentation, completed implementations, and validation reports.
+
+#### Validation Reports (Archived)
+- Version-specific validation (v1.1.10, v1.1.11)
+- MCP proxy validation
+- OpenRouter integration validation
+- Docker deployment validation
+- SDK integration reports
+- Model validation reports
+
+#### Completed Implementations
+- [Research Complete](archived/RESEARCH_COMPLETE.txt) - Historical research
+- [FastMCP Complete](archived/FASTMCP_COMPLETE.md) - FastMCP completion
+- [Flow Nexus Complete](archived/FLOW-NEXUS-COMPLETE.md) - Flow Nexus completion
+- [OpenRouter Proxy Complete](archived/OPENROUTER_PROXY_COMPLETE.md) - OpenRouter completion
+- [Package Complete](archived/PACKAGE-COMPLETE.md) - Package completion
+- [SDK Setup Complete](archived/SDK-SETUP-COMPLETE.md) - SDK setup completion
+- ONNX implementation reports
+- Integration confirmation reports
+
+#### Historical Guides
+- ONNX integration guides (superseded by current guides)
+- Optimization summaries (superseded)
+- Provider instruction optimization
+- Tool instruction enhancements
+
+#### Research & Planning
+- ONNX Phi4 research
+- ONNX Runtime integration planning
+- Phi4 hyperoptimization plans
+
+---
+
+## 🎯 Reading Paths
+
+### Path 1: New Users (30 minutes)
+1. [Main README](../README.md) - Project overview (10 min)
+2. [Claude Config](CLAUDE.md) - Development setup (10 min)
+3. [User Guides](guides/) - Practical tutorials (10 min)
+
+### Path 2: Developers (1.5 hours)
+1. [Architecture Overview](architecture/EXECUTIVE_SUMMARY.md) - System design (20 min)
+2. [Implementation Examples](guides/IMPLEMENTATION_EXAMPLES.md) - Code patterns (40 min)
+3. [Integration Guides](integrations/) - External services (20 min)
+4. [Testing Documentation](testing/) - Quality assurance (10 min)
+
+### Path 3: System Architects (2 hours)
+1. [Research Summary](architecture/RESEARCH_SUMMARY.md) - Technical findings (30 min)
+2. [Multi-Model Router Plan](architecture/MULTI_MODEL_ROUTER_PLAN.md) - Router architecture (45 min)
+3. [Integration Status](architecture/INTEGRATION-STATUS.md) - Current state (20 min)
+4. [Router Documentation](router/) - Configuration and usage (15 min)
+5. [MCP Validation](mcp-validation/) - Protocol implementation (10 min)
+
+---
+
+## 📊 Key Features
+
+### Multi-Agent Orchestration
+- Hierarchical, mesh, and hybrid topologies
+- Parallel and sequential execution patterns
+- Claude Flow integration for coordination
+- 54+ specialized agent types
+
+### SPARC Methodology
+- Specification → Pseudocode → Architecture → Refinement → Completion
+- Test-driven development workflow
+- Automated task orchestration
+- Neural pattern learning
+
+### Model Router
+- Multi-model support (Claude, OpenRouter, ONNX, Gemini)
+- Intelligent model selection
+- Cost optimization
+- Performance monitoring
+
+### Cloud Integration
+- Flow Nexus platform support
+- E2B sandbox execution
+- Real-time streaming and monitoring
+- 70+ MCP orchestration tools
+
+---
+
+## 🔗 External Resources
+
+### Official Documentation
+- [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Agentic Flow GitHub](https://github.com/ruvnet/agentic-flow)
+- [Flow Nexus Platform](https://flow-nexus.ruv.io)
+
+### Community
+- [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
+
+---
+
+## 📞 Getting Help
+
+### Documentation Questions
+1. Check the relevant category above
+2. Review the README for each section
+3. Search for specific topics in the index
+
+### Implementation Support
+1. Review [Implementation Examples](guides/IMPLEMENTATION_EXAMPLES.md)
+2. Check [Integration Guides](integrations/)
+3. Consult [Router Documentation](router/)
+
+### Architecture Questions
+1. Read [Architecture Documentation](architecture/)
+2. Review [Router Documentation](router/)
+3. Check [Integration Status](architecture/INTEGRATION-STATUS.md)
+
+---
+
+## 🎯 Quick Links
+
+- **License**: [MIT License](LICENSE)
+- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
+- **Contributing**: See main [README](../README.md)
+- **Issues**: [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
+
+---
+
+## 📂 Documentation Organization
+
+### Active Documentation
+All current and actively maintained documentation is organized in the category directories above.
+
+### Archived Content
+Historical reports, completed implementations, and superseded guides are in the [archived/](archived/) directory for reference.
+
+---
+
+**Documentation Status**: ✅ Reorganized and up-to-date
+**Last Updated**: October 14, 2025
+
+## 📋 Recent Documentation Updates
+
+**v2.7.0 Reorganization (Oct 14, 2025)**:
+- Created `reasoningbank/` for all ReasoningBank feature documentation
+- Created `validation-reports/` for production testing and validation
+- Created `integration-docs/` for system integration documentation
+- Created `quantum-research/` for quantum computing research
+- Created `version-releases/` for release notes and changelogs
+- Added comprehensive README files to all new categories
+- Consolidated loose files into organized subdirectories
+- Improved navigation and discoverability
+
+**v2.0 Reorganization (Oct 6, 2025)**:
+- Created dedicated `releases/` directory for version-specific documentation
+- Consolidated testing reports into `testing/` directory
+- Separated MCP validation into dedicated `mcp-validation/` section
+- Added comprehensive READMEs to all major sections
+- Archived historical v1.1.x releases for cleaner navigation
+- Improved documentation index with better categorization

package/agentic-flow/docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude Flow Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.