agentic-flow 3.0.0-alpha.2 → 3.1.0

package/.claude/skills/memory-patterns/skill.md

@@ -0,0 +1,110 @@
+---
+name: memory-patterns
+description: Persistent memory patterns for cross-session learning and context retention
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - memory_store
+  - memory_retrieve
+  - pattern_learning
+  - context_management
+---
+
+# Memory Patterns Skill
+
+Implement persistent memory patterns for AI agents using ReasoningBank.
+
+## Quick Commands
+
+```bash
+# Store a pattern
+npx agentic-flow@3.1.0 memory store "api:auth" "OAuth2 with JWT"
+
+# Retrieve a pattern
+npx agentic-flow@3.1.0 memory get "api:auth"
+
+# Search patterns
+npx agentic-flow@3.1.0 memory search "authentication"
+
+# List all patterns
+npx agentic-flow@3.1.0 memory list --namespace project
+```
+
+## Memory Namespaces
+
+| Namespace | Purpose | TTL |
+|-----------|---------|-----|
+| `session` | Current session context | Until end |
+| `project` | Project-specific learnings | Permanent |
+| `user` | User preferences | Permanent |
+| `swarm` | Swarm coordination state | Swarm lifetime |
+| `cache` | Temporary cached data | 1 hour |
+
+## Pattern Types
+
+### Decision Patterns
+```bash
+# Store decision with context
+npx agentic-flow@3.1.0 memory store \
+  "decisions:auth-method" \
+  '{"choice": "JWT", "reason": "stateless, scalable", "date": "2024-01-01"}'
+```
+
+### Code Patterns
+```bash
+# Store reusable code pattern
+npx agentic-flow@3.1.0 memory store \
+  "patterns:error-handling" \
+  "try-catch with custom error classes and logging"
+```
+
+### Learning Patterns
+```bash
+# Store learning from successful task
+npx agentic-flow@3.1.0 memory store \
+  "learnings:react-hooks" \
+  "useCallback for event handlers, useMemo for expensive computations"
+```
+
+## MCP Tools
+
+```javascript
+// Store memory
+mcp__claude-flow__memory_usage({
+  action: "store",
+  key: "project:architecture",
+  value: "microservices with event-driven communication",
+  namespace: "project"
+})
+
+// Retrieve memory
+mcp__claude-flow__memory_usage({
+  action: "retrieve",
+  key: "project:architecture",
+  namespace: "project"
+})
+
+// Search memories
+mcp__claude-flow__memory_search({
+  pattern: "auth*",
+  namespace: "project",
+  limit: 10
+})
+```
+
+## ReasoningBank Integration
+
+ReasoningBank provides:
+- **150x faster** vector search with HNSW
+- **Reflexion memory** for self-improvement
+- **Skill library** for learned capabilities
+- **Causal graphs** for decision tracking
+
+## Best Practices
+
+1. **Use namespaces**: Organize by scope
+2. **Be specific**: Clear, searchable keys
+3. **Include context**: Store decisions with reasoning
+4. **Clean up**: Delete stale patterns
+5. **Version patterns**: Track changes over time

package/.claude/skills/sparc-methodology/skill.md

@@ -0,0 +1,137 @@
+---
+name: sparc-methodology
+description: SPARC development methodology for systematic test-driven development
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - specification
+  - pseudocode
+  - architecture
+  - refinement
+  - completion
+---
+
+# SPARC Methodology Skill
+
+Systematic Test-Driven Development using SPARC (Specification, Pseudocode, Architecture, Refinement, Completion).
+
+## Quick Commands
+
+```bash
+# Run complete TDD workflow
+npx agentic-flow@3.1.0 sparc tdd "implement user authentication"
+
+# Run specific phase
+npx agentic-flow@3.1.0 sparc run specification "auth system"
+npx agentic-flow@3.1.0 sparc run pseudocode "auth system"
+npx agentic-flow@3.1.0 sparc run architect "auth system"
+npx agentic-flow@3.1.0 sparc run refinement "auth system"
+npx agentic-flow@3.1.0 sparc run completion "auth system"
+
+# Batch execution
+npx agentic-flow@3.1.0 sparc batch "spec-pseudocode,architect" "feature X"
+```
+
+## SPARC Phases
+
+### 1. Specification (spec)
+Define requirements and acceptance criteria.
+
+**Agent**: `specification`
+**Output**: Requirements doc, test cases
+**Command**:
+```bash
+npx agentic-flow@3.1.0 sparc run spec "user login feature"
+```
+
+### 2. Pseudocode (pseudo)
+Design algorithms and logic flow.
+
+**Agent**: `pseudocode`
+**Output**: Algorithm design, flow diagrams
+**Command**:
+```bash
+npx agentic-flow@3.1.0 sparc run pseudo "auth flow"
+```
+
+### 3. Architecture (arch)
+System design and component structure.
+
+**Agent**: `architecture`
+**Output**: Component diagram, API design
+**Command**:
+```bash
+npx agentic-flow@3.1.0 sparc run arch "microservices layout"
+```
+
+### 4. Refinement (refine)
+Iterative TDD implementation.
+
+**Agent**: `refinement`
+**Output**: Tests + Implementation
+**Command**:
+```bash
+npx agentic-flow@3.1.0 sparc run refine "auth module"
+```
+
+### 5. Completion (complete)
+Integration and deployment.
+
+**Agent**: `completion`
+**Output**: Integrated system, docs
+**Command**:
+```bash
+npx agentic-flow@3.1.0 sparc run complete "auth system"
+```
+
+## SPARC Modes
+
+Additional specialized modes:
+
+| Mode | Description |
+|------|-------------|
+| `dev` | General development |
+| `api` | API design |
+| `ui` | UI/UX development |
+| `test` | Testing focus |
+| `refactor` | Code improvement |
+| `debug` | Bug investigation |
+| `security` | Security review |
+| `devops` | CI/CD setup |
+
+## TDD Workflow
+
+```bash
+# Full TDD cycle
+npx agentic-flow@3.1.0 sparc tdd "implement OAuth2"
+
+# This runs:
+# 1. Specification: Define requirements
+# 2. Pseudocode: Design algorithm
+# 3. Architecture: Plan structure
+# 4. Refinement: Write tests first, then implement
+# 5. Completion: Integrate and document
+```
+
+## Agent Integration
+
+SPARC uses specialized agents:
+
+```javascript
+// Via Claude Code Task tool
+Task("Specification agent", "Define requirements for OAuth", "specification")
+Task("Architecture agent", "Design OAuth architecture", "architecture")
+Task("Coder agent", "Implement OAuth with TDD", "sparc-coder")
+Task("Tester agent", "Verify OAuth implementation", "tester")
+Task("Reviewer agent", "Review OAuth code quality", "reviewer")
+```
+
+## Best Practices
+
+1. **Start with specification**: Clear requirements first
+2. **Write tests first**: TDD in refinement phase
+3. **Iterate small**: Small increments
+4. **Document as you go**: Keep docs updated
+5. **Review at each phase**: Quality gates
+6. **Use parallel execution**: Multiple agents

package/.claude/skills/swarm-coordination/skill.md

@@ -0,0 +1,94 @@
+---
+name: swarm-coordination
+description: Orchestrate multi-agent swarms for complex parallel task execution
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - swarm_init
+  - agent_spawn
+  - task_orchestration
+  - topology_optimization
+---
+
+# Swarm Coordination Skill
+
+Coordinate multi-agent swarms for parallel task execution with intelligent topology selection.
+
+## Quick Start
+
+```bash
+# Initialize a mesh swarm with 5 agents
+npx agentic-flow@3.1.0 swarm init --topology mesh --agents 5
+
+# Spawn specialized agents
+npx agentic-flow@3.1.0 swarm spawn --type researcher --name "Research Agent"
+npx agentic-flow@3.1.0 swarm spawn --type coder --name "Code Agent"
+
+# Orchestrate a task
+npx agentic-flow@3.1.0 swarm orchestrate "Implement feature X with tests"
+
+# Check swarm status
+npx agentic-flow@3.1.0 swarm status
+```
+
+## Topologies
+
+### Mesh (Default)
+- All agents communicate directly
+- Best for: Collaborative tasks, code review
+- Latency: Low
+- Scalability: Medium
+
+### Hierarchical
+- Tree structure with coordinator
+- Best for: Large projects, delegation
+- Latency: Medium
+- Scalability: High
+
+### Ring
+- Sequential communication
+- Best for: Pipeline processing, CI/CD
+- Latency: Higher
+- Scalability: Medium
+
+### Star
+- Central hub coordinates all
+- Best for: Simple coordination
+- Latency: Low
+- Scalability: Low
+
+## Agent Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| researcher | Deep analysis | Requirements gathering |
+| coder | Implementation | Feature development |
+| tester | Quality assurance | Test creation |
+| reviewer | Code quality | PR review |
+| architect | System design | Architecture decisions |
+| coordinator | Task routing | Complex workflows |
+
+## MCP Tools
+
+```javascript
+// Initialize swarm
+mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 8 })
+
+// Spawn agent
+mcp__claude-flow__agent_spawn({ type: "coder", name: "Feature Dev" })
+
+// Orchestrate task
+mcp__claude-flow__task_orchestrate({
+  task: "Implement OAuth",
+  strategy: "parallel"
+})
+```
+
+## Best Practices
+
+1. **Right-size your swarm**: Start with 3-5 agents
+2. **Choose topology wisely**: Match to task structure
+3. **Use Claude Code Task tool**: For actual agent spawning
+4. **Monitor status**: Check for bottlenecks
+5. **Clean up**: Destroy swarm when done

package/.claude/skills/worker-benchmarks/skill.md

@@ -0,0 +1,135 @@
+---
+name: worker-benchmarks
+description: Run comprehensive worker system benchmarks and performance analysis
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - performance_testing
+  - metrics_collection
+  - optimization_recommendations
+---
+
+# Worker Benchmarks Skill
+
+Run comprehensive performance benchmarks for the agentic-flow worker system.
+
+## Quick Start
+
+```bash
+# Run full benchmark suite
+npx agentic-flow@3.1.0 workers benchmark
+
+# Run specific benchmark
+npx agentic-flow@3.1.0 workers benchmark --type trigger-detection
+npx agentic-flow@3.1.0 workers benchmark --type registry
+npx agentic-flow@3.1.0 workers benchmark --type agent-selection
+npx agentic-flow@3.1.0 workers benchmark --type concurrent
+```
+
+## Benchmark Types
+
+### 1. Trigger Detection (`trigger-detection`)
+Tests keyword detection speed across 12 worker triggers.
+- **Target**: p95 < 5ms
+- **Iterations**: 1000
+- **Metrics**: latency, throughput, histogram
+
+### 2. Worker Registry (`registry`)
+Tests CRUD operations on worker entries.
+- **Target**: p95 < 10ms
+- **Iterations**: 500 creates, gets, updates
+- **Metrics**: per-operation latency breakdown
+
+### 3. Agent Selection (`agent-selection`)
+Tests performance-based agent selection.
+- **Target**: p95 < 1ms
+- **Iterations**: 1000
+- **Metrics**: selection confidence, agent scores
+
+### 4. Model Cache (`cache`)
+Tests model caching performance.
+- **Target**: p95 < 0.5ms
+- **Metrics**: hit rate, cache size, eviction stats
+
+### 5. Concurrent Workers (`concurrent`)
+Tests parallel worker creation and updates.
+- **Target**: < 1000ms for 10 workers
+- **Metrics**: per-worker latency, memory usage
+
+### 6. Memory Key Generation (`memory-keys`)
+Tests memory pattern key generation.
+- **Target**: p95 < 0.1ms
+- **Iterations**: 5000
+- **Metrics**: unique patterns, throughput
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════
+📈 BENCHMARK RESULTS
+═══════════════════════════════════════════════════════════
+
+✅ Trigger Detection
+   Operation: detect
+   Count: 1,000
+   Avg: 0.045ms | p95: 0.120ms (target: 5ms)
+   Throughput: 22,222 ops/s
+   Memory Δ: 0.12MB
+
+✅ Worker Registry
+   Operation: crud
+   Count: 1,500
+   Avg: 1.234ms | p95: 3.456ms (target: 10ms)
+   Throughput: 810 ops/s
+   Memory Δ: 2.34MB
+
+───────────────────────────────────────────────────────────
+📊 SUMMARY
+───────────────────────────────────────────────────────────
+Total Tests: 6
+Passed: 6 | Failed: 0
+Avg Latency: 0.567ms
+Total Duration: 2345ms
+Peak Memory: 8.90MB
+═══════════════════════════════════════════════════════════
+```
+
+## Integration with Settings
+
+Benchmark thresholds are configured in `.claude/settings.json`:
+
+```json
+{
+  "performance": {
+    "benchmarkThresholds": {
+      "triggerDetection": { "p95Ms": 5 },
+      "workerRegistry": { "p95Ms": 10 },
+      "agentSelection": { "p95Ms": 1 },
+      "memoryKeyGeneration": { "p95Ms": 0.1 },
+      "concurrentWorkers": { "totalMs": 1000 }
+    }
+  }
+}
+```
+
+## Programmatic Usage
+
+```typescript
+import { workerBenchmarks, runBenchmarks } from 'agentic-flow/workers/worker-benchmarks';
+
+// Run full suite
+const suite = await runBenchmarks();
+console.log(suite.summary);
+
+// Run individual benchmarks
+const triggerResult = await workerBenchmarks.benchmarkTriggerDetection(1000);
+const registryResult = await workerBenchmarks.benchmarkRegistryOperations(500);
+```
+
+## Performance Optimization Tips
+
+1. **Model Cache**: Enable with `CLAUDE_FLOW_MODEL_CACHE_MB=512`
+2. **Parallel Workers**: Enable with `CLAUDE_FLOW_WORKER_PARALLEL=true`
+3. **Warning Suppression**: Enable with `CLAUDE_FLOW_SUPPRESS_WARNINGS=true`
+4. **SQLite WAL Mode**: Automatic for better concurrent performance

package/.claude/skills/worker-integration/skill.md

@@ -0,0 +1,154 @@
+---
+name: worker-integration
+description: Worker-Agent integration for intelligent task dispatch and performance tracking
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - agent_selection
+  - performance_tracking
+  - memory_coordination
+  - self_learning
+---
+
+# Worker-Agent Integration Skill
+
+Intelligent coordination between background workers and specialized agents.
+
+## Quick Start
+
+```bash
+# View agent recommendations for a trigger
+npx agentic-flow@3.1.0 workers agents ultralearn
+npx agentic-flow@3.1.0 workers agents optimize
+
+# View performance metrics
+npx agentic-flow@3.1.0 workers metrics
+
+# View integration stats
+npx agentic-flow@3.1.0 workers stats --integration
+```
+
+## Agent Mappings
+
+Workers automatically dispatch to optimal agents based on trigger type:
+
+| Trigger | Primary Agents | Fallback | Pipeline Phases |
+|---------|---------------|----------|-----------------|
+| `ultralearn` | researcher, coder | planner | discovery → patterns → vectorization → summary |
+| `optimize` | performance-analyzer, coder | researcher | static-analysis → performance → patterns |
+| `audit` | security-analyst, tester | reviewer | security → secrets → vulnerability-scan |
+| `benchmark` | performance-analyzer | coder, tester | performance → metrics → report |
+| `testgaps` | tester | coder | discovery → coverage → gaps |
+| `document` | documenter, researcher | coder | api-discovery → patterns → indexing |
+| `deepdive` | researcher, security-analyst | coder | call-graph → deps → trace |
+| `refactor` | coder, reviewer | researcher | complexity → smells → patterns |
+
+## Performance-Based Selection
+
+The system learns from execution history to improve agent selection:
+
+```typescript
+// Agent selection considers:
+// 1. Quality score (0-1)
+// 2. Success rate
+// 3. Average latency
+// 4. Execution count
+
+const { agent, confidence, reasoning } = selectBestAgent('optimize');
+// agent: "performance-analyzer"
+// confidence: 0.87
+// reasoning: "Selected based on 45 executions with 94.2% success"
+```
+
+## Memory Key Patterns
+
+Workers store results using consistent patterns:
+
+```
+{trigger}/{topic}/{phase}
+
+Examples:
+- ultralearn/auth-module/analysis
+- optimize/database/performance
+- audit/payment/vulnerabilities
+- benchmark/api/metrics
+```
+
+## Benchmark Thresholds
+
+Agents are monitored against performance thresholds:
+
+```json
+{
+  "researcher": {
+    "p95_latency": "<500ms",
+    "memory_mb": "<256MB"
+  },
+  "coder": {
+    "p95_latency": "<300ms",
+    "quality_score": ">0.85"
+  },
+  "security-analyst": {
+    "scan_coverage": ">95%",
+    "p95_latency": "<1000ms"
+  }
+}
+```
+
+## Feedback Loop
+
+Workers provide feedback for continuous improvement:
+
+```typescript
+import { workerAgentIntegration } from 'agentic-flow/workers/worker-agent-integration';
+
+// Record execution feedback
+workerAgentIntegration.recordFeedback(
+  'optimize',           // trigger
+  'coder',              // agent
+  true,                 // success
+  245,                  // latency ms
+  0.92                  // quality score
+);
+
+// Check compliance
+const { compliant, violations } = workerAgentIntegration.checkBenchmarkCompliance('coder');
+```
+
+## Integration Statistics
+
+```bash
+$ npx agentic-flow@3.1.0 workers stats --integration
+
+Worker-Agent Integration Stats
+══════════════════════════════
+Total Agents:       6
+Tracked Agents:     4
+Total Feedback:     156
+Avg Quality Score:  0.89
+
+Model Cache Stats
+─────────────────
+Hits:     1,234
+Misses:   45
+Hit Rate: 96.5%
+```
+
+## Configuration
+
+Enable integration features in `.claude/settings.json`:
+
+```json
+{
+  "workers": {
+    "enabled": true,
+    "parallel": true,
+    "memoryDepositEnabled": true,
+    "agentMappings": {
+      "ultralearn": ["researcher", "coder"],
+      "optimize": ["performance-analyzer", "coder"]
+    }
+  }
+}
+```