From e0b2be205856c17470ec97f578b5a2d684929148 Mon Sep 17 00:00:00 2001 From: shanshanzhong Date: Mon, 30 Mar 2026 21:05:21 -0700 Subject: [PATCH] x --- .agents/skills/agentdb-advanced/SKILL.md | 550 +++++++ .agents/skills/agentdb-learning/SKILL.md | 545 +++++++ .../skills/agentdb-memory-patterns/SKILL.md | 339 +++++ .agents/skills/agentdb-optimization/SKILL.md | 509 +++++++ .agents/skills/agentdb-vector-search/SKILL.md | 339 +++++ .agents/skills/browser/SKILL.md | 204 +++ .agents/skills/github-code-review/SKILL.md | 1140 +++++++++++++++ .agents/skills/github-multi-repo/SKILL.md | 874 +++++++++++ .../skills/github-project-management/SKILL.md | 1277 +++++++++++++++++ .../skills/github-release-management/SKILL.md | 1081 ++++++++++++++ .../github-workflow-automation/SKILL.md | 1065 ++++++++++++++ .agents/skills/hooks-automation/SKILL.md | 1201 ++++++++++++++++ .agents/skills/pair-programming/SKILL.md | 1202 ++++++++++++++++ .agents/skills/reasoningbank-agentdb/SKILL.md | 446 ++++++ .../reasoningbank-intelligence/SKILL.md | 201 +++ .agents/skills/skill-builder/SKILL.md | 910 ++++++++++++ .../soft-delete-relogin-consistency/SKILL.md | 144 ++ .agents/skills/stream-chain/SKILL.md | 563 ++++++++ .agents/skills/swarm-advanced/SKILL.md | 973 +++++++++++++ .agents/skills/v3-cli-modernization/SKILL.md | 872 +++++++++++ .../skills/v3-core-implementation/SKILL.md | 797 ++++++++++ .agents/skills/v3-ddd-architecture/SKILL.md | 442 ++++++ .agents/skills/v3-integration-deep/SKILL.md | 241 ++++ .agents/skills/v3-mcp-optimization/SKILL.md | 777 ++++++++++ .agents/skills/v3-memory-unification/SKILL.md | 174 +++ .../v3-performance-optimization/SKILL.md | 390 +++++ .agents/skills/v3-security-overhaul/SKILL.md | 82 ++ .agents/skills/v3-swarm-coordination/SKILL.md | 340 +++++ .agents/skills/verification-quality/SKILL.md | 649 +++++++++ internal/logic/common/newUserEligibility.go | 188 +++ .../order/newUserDiscountEligibility.go | 63 + .../logic/public/order/preCreateOrderLogic.go | 50 +- internal/logic/public/order/purchaseLogic.go | 97 +- queue/logic/order/activateOrderLogic.go | 25 +- queue/logic/order/newUserEligibility.go | 58 + 35 files changed, 18692 insertions(+), 116 deletions(-) create mode 100644 .agents/skills/agentdb-advanced/SKILL.md create mode 100644 .agents/skills/agentdb-learning/SKILL.md create mode 100644 .agents/skills/agentdb-memory-patterns/SKILL.md create mode 100644 .agents/skills/agentdb-optimization/SKILL.md create mode 100644 .agents/skills/agentdb-vector-search/SKILL.md create mode 100644 .agents/skills/browser/SKILL.md create mode 100644 .agents/skills/github-code-review/SKILL.md create mode 100644 .agents/skills/github-multi-repo/SKILL.md create mode 100644 .agents/skills/github-project-management/SKILL.md create mode 100644 .agents/skills/github-release-management/SKILL.md create mode 100644 .agents/skills/github-workflow-automation/SKILL.md create mode 100644 .agents/skills/hooks-automation/SKILL.md create mode 100644 .agents/skills/pair-programming/SKILL.md create mode 100644 .agents/skills/reasoningbank-agentdb/SKILL.md create mode 100644 .agents/skills/reasoningbank-intelligence/SKILL.md create mode 100644 .agents/skills/skill-builder/SKILL.md create mode 100644 .agents/skills/soft-delete-relogin-consistency/SKILL.md create mode 100644 .agents/skills/stream-chain/SKILL.md create mode 100644 .agents/skills/swarm-advanced/SKILL.md create mode 100644 .agents/skills/v3-cli-modernization/SKILL.md create mode 100644 .agents/skills/v3-core-implementation/SKILL.md create mode 100644 .agents/skills/v3-ddd-architecture/SKILL.md create mode 100644 .agents/skills/v3-integration-deep/SKILL.md create mode 100644 .agents/skills/v3-mcp-optimization/SKILL.md create mode 100644 .agents/skills/v3-memory-unification/SKILL.md create mode 100644 .agents/skills/v3-performance-optimization/SKILL.md create mode 100644 .agents/skills/v3-security-overhaul/SKILL.md create mode 100644 .agents/skills/v3-swarm-coordination/SKILL.md create mode 100644 .agents/skills/verification-quality/SKILL.md create mode 100644 internal/logic/common/newUserEligibility.go create mode 100644 internal/logic/public/order/newUserDiscountEligibility.go create mode 100644 queue/logic/order/newUserEligibility.go diff --git a/.agents/skills/agentdb-advanced/SKILL.md b/.agents/skills/agentdb-advanced/SKILL.md new file mode 100644 index 0000000..da61dc2 --- /dev/null +++ b/.agents/skills/agentdb-advanced/SKILL.md @@ -0,0 +1,550 @@ +--- +name: "AgentDB Advanced Features" +description: "Master advanced AgentDB features including QUIC synchronization, multi-database management, custom distance metrics, hybrid search, and distributed systems integration. Use when building distributed AI systems, multi-agent coordination, or advanced vector search applications." +--- + +# AgentDB Advanced Features + +## What This Skill Does + +Covers advanced AgentDB capabilities for distributed systems, multi-database coordination, custom distance metrics, hybrid search (vector + metadata), QUIC synchronization, and production deployment patterns. Enables building sophisticated AI systems with sub-millisecond cross-node communication and advanced search capabilities. + +**Performance**: <1ms QUIC sync, hybrid search with filters, custom distance metrics. + +## Prerequisites + +- Node.js 18+ +- AgentDB v1.0.7+ (via agentic-flow) +- Understanding of distributed systems (for QUIC sync) +- Vector search fundamentals + +--- + +## QUIC Synchronization + +### What is QUIC Sync? + +QUIC (Quick UDP Internet Connections) enables sub-millisecond latency synchronization between AgentDB instances across network boundaries with automatic retry, multiplexing, and encryption. + +**Benefits**: +- <1ms latency between nodes +- Multiplexed streams (multiple operations simultaneously) +- Built-in encryption (TLS 1.3) +- Automatic retry and recovery +- Event-based broadcasting + +### Enable QUIC Sync + +```typescript +import { createAgentDBAdapter } from 'agentic-flow/reasoningbank'; + +// Initialize with QUIC synchronization +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/distributed.db', + enableQUICSync: true, + syncPort: 4433, + syncPeers: [ + '192.168.1.10:4433', + '192.168.1.11:4433', + '192.168.1.12:4433', + ], +}); + +// Patterns automatically sync across all peers +await adapter.insertPattern({ + // ... pattern data +}); + +// Available on all peers within ~1ms +``` + +### QUIC Configuration + +```typescript +const adapter = await createAgentDBAdapter({ + enableQUICSync: true, + syncPort: 4433, // QUIC server port + syncPeers: ['host1:4433'], // Peer addresses + syncInterval: 1000, // Sync interval (ms) + syncBatchSize: 100, // Patterns per batch + maxRetries: 3, // Retry failed syncs + compression: true, // Enable compression +}); +``` + +### Multi-Node Deployment + +```bash +# Node 1 (192.168.1.10) +AGENTDB_QUIC_SYNC=true \ +AGENTDB_QUIC_PORT=4433 \ +AGENTDB_QUIC_PEERS=192.168.1.11:4433,192.168.1.12:4433 \ +node server.js + +# Node 2 (192.168.1.11) +AGENTDB_QUIC_SYNC=true \ +AGENTDB_QUIC_PORT=4433 \ +AGENTDB_QUIC_PEERS=192.168.1.10:4433,192.168.1.12:4433 \ +node server.js + +# Node 3 (192.168.1.12) +AGENTDB_QUIC_SYNC=true \ +AGENTDB_QUIC_PORT=4433 \ +AGENTDB_QUIC_PEERS=192.168.1.10:4433,192.168.1.11:4433 \ +node server.js +``` + +--- + +## Distance Metrics + +### Cosine Similarity (Default) + +Best for normalized vectors, semantic similarity: + +```bash +# CLI +npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m cosine + +# API +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + metric: 'cosine', + k: 10, +}); +``` + +**Use Cases**: +- Text embeddings (BERT, GPT, etc.) +- Semantic search +- Document similarity +- Most general-purpose applications + +**Formula**: `cos(θ) = (A · B) / (||A|| × ||B||)` +**Range**: [-1, 1] (1 = identical, -1 = opposite) + +### Euclidean Distance (L2) + +Best for spatial data, geometric similarity: + +```bash +# CLI +npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m euclidean + +# API +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + metric: 'euclidean', + k: 10, +}); +``` + +**Use Cases**: +- Image embeddings +- Spatial data +- Computer vision +- When vector magnitude matters + +**Formula**: `d = √(Σ(ai - bi)²)` +**Range**: [0, ∞] (0 = identical, ∞ = very different) + +### Dot Product + +Best for pre-normalized vectors, fast computation: + +```bash +# CLI +npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m dot + +# API +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + metric: 'dot', + k: 10, +}); +``` + +**Use Cases**: +- Pre-normalized embeddings +- Fast similarity computation +- When vectors are already unit-length + +**Formula**: `dot = Σ(ai × bi)` +**Range**: [-∞, ∞] (higher = more similar) + +### Custom Distance Metrics + +```typescript +// Implement custom distance function +function customDistance(vec1: number[], vec2: number[]): number { + // Weighted Euclidean distance + const weights = [1.0, 2.0, 1.5, ...]; + let sum = 0; + for (let i = 0; i < vec1.length; i++) { + sum += weights[i] * Math.pow(vec1[i] - vec2[i], 2); + } + return Math.sqrt(sum); +} + +// Use in search (requires custom implementation) +``` + +--- + +## Hybrid Search (Vector + Metadata) + +### Basic Hybrid Search + +Combine vector similarity with metadata filtering: + +```typescript +// Store documents with metadata +await adapter.insertPattern({ + id: '', + type: 'document', + domain: 'research-papers', + pattern_data: JSON.stringify({ + embedding: documentEmbedding, + text: documentText, + metadata: { + author: 'Jane Smith', + year: 2025, + category: 'machine-learning', + citations: 150, + } + }), + confidence: 1.0, + usage_count: 0, + success_count: 0, + created_at: Date.now(), + last_used: Date.now(), +}); + +// Hybrid search: vector similarity + metadata filters +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'research-papers', + k: 20, + filters: { + year: { $gte: 2023 }, // Published 2023 or later + category: 'machine-learning', // ML papers only + citations: { $gte: 50 }, // Highly cited + }, +}); +``` + +### Advanced Filtering + +```typescript +// Complex metadata queries +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'products', + k: 50, + filters: { + price: { $gte: 10, $lte: 100 }, // Price range + category: { $in: ['electronics', 'gadgets'] }, // Multiple categories + rating: { $gte: 4.0 }, // High rated + inStock: true, // Available + tags: { $contains: 'wireless' }, // Has tag + }, +}); +``` + +### Weighted Hybrid Search + +Combine vector and metadata scores: + +```typescript +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'content', + k: 20, + hybridWeights: { + vectorSimilarity: 0.7, // 70% weight on semantic similarity + metadataScore: 0.3, // 30% weight on metadata match + }, + filters: { + category: 'technology', + recency: { $gte: Date.now() - 30 * 24 * 3600000 }, // Last 30 days + }, +}); +``` + +--- + +## Multi-Database Management + +### Multiple Databases + +```typescript +// Separate databases for different domains +const knowledgeDB = await createAgentDBAdapter({ + dbPath: '.agentdb/knowledge.db', +}); + +const conversationDB = await createAgentDBAdapter({ + dbPath: '.agentdb/conversations.db', +}); + +const codeDB = await createAgentDBAdapter({ + dbPath: '.agentdb/code.db', +}); + +// Use appropriate database for each task +await knowledgeDB.insertPattern({ /* knowledge */ }); +await conversationDB.insertPattern({ /* conversation */ }); +await codeDB.insertPattern({ /* code */ }); +``` + +### Database Sharding + +```typescript +// Shard by domain for horizontal scaling +const shards = { + 'domain-a': await createAgentDBAdapter({ dbPath: '.agentdb/shard-a.db' }), + 'domain-b': await createAgentDBAdapter({ dbPath: '.agentdb/shard-b.db' }), + 'domain-c': await createAgentDBAdapter({ dbPath: '.agentdb/shard-c.db' }), +}; + +// Route queries to appropriate shard +function getDBForDomain(domain: string) { + const shardKey = domain.split('-')[0]; // Extract shard key + return shards[shardKey] || shards['domain-a']; +} + +// Insert to correct shard +const db = getDBForDomain('domain-a-task'); +await db.insertPattern({ /* ... */ }); +``` + +--- + +## MMR (Maximal Marginal Relevance) + +Retrieve diverse results to avoid redundancy: + +```typescript +// Without MMR: Similar results may be redundant +const standardResults = await adapter.retrieveWithReasoning(queryEmbedding, { + k: 10, + useMMR: false, +}); + +// With MMR: Diverse, non-redundant results +const diverseResults = await adapter.retrieveWithReasoning(queryEmbedding, { + k: 10, + useMMR: true, + mmrLambda: 0.5, // Balance relevance (0) vs diversity (1) +}); +``` + +**MMR Parameters**: +- `mmrLambda = 0`: Maximum relevance (may be redundant) +- `mmrLambda = 0.5`: Balanced (default) +- `mmrLambda = 1`: Maximum diversity (may be less relevant) + +**Use Cases**: +- Search result diversification +- Recommendation systems +- Avoiding echo chambers +- Exploratory search + +--- + +## Context Synthesis + +Generate rich context from multiple memories: + +```typescript +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'problem-solving', + k: 10, + synthesizeContext: true, // Enable context synthesis +}); + +// ContextSynthesizer creates coherent narrative +console.log('Synthesized Context:', result.context); +// "Based on 10 similar problem-solving attempts, the most effective +// approach involves: 1) analyzing root cause, 2) brainstorming solutions, +// 3) evaluating trade-offs, 4) implementing incrementally. Success rate: 85%" + +console.log('Patterns:', result.patterns); +// Extracted common patterns across memories +``` + +--- + +## Production Patterns + +### Connection Pooling + +```typescript +// Singleton pattern for shared adapter +class AgentDBPool { + private static instance: AgentDBAdapter; + + static async getInstance() { + if (!this.instance) { + this.instance = await createAgentDBAdapter({ + dbPath: '.agentdb/production.db', + quantizationType: 'scalar', + cacheSize: 2000, + }); + } + return this.instance; + } +} + +// Use in application +const db = await AgentDBPool.getInstance(); +const results = await db.retrieveWithReasoning(queryEmbedding, { k: 10 }); +``` + +### Error Handling + +```typescript +async function safeRetrieve(queryEmbedding: number[], options: any) { + try { + const result = await adapter.retrieveWithReasoning(queryEmbedding, options); + return result; + } catch (error) { + if (error.code === 'DIMENSION_MISMATCH') { + console.error('Query embedding dimension mismatch'); + // Handle dimension error + } else if (error.code === 'DATABASE_LOCKED') { + // Retry with exponential backoff + await new Promise(resolve => setTimeout(resolve, 100)); + return safeRetrieve(queryEmbedding, options); + } + throw error; + } +} +``` + +### Monitoring and Logging + +```typescript +// Performance monitoring +const startTime = Date.now(); +const result = await adapter.retrieveWithReasoning(queryEmbedding, { k: 10 }); +const latency = Date.now() - startTime; + +if (latency > 100) { + console.warn('Slow query detected:', latency, 'ms'); +} + +// Log statistics +const stats = await adapter.getStats(); +console.log('Database Stats:', { + totalPatterns: stats.totalPatterns, + dbSize: stats.dbSize, + cacheHitRate: stats.cacheHitRate, + avgSearchLatency: stats.avgSearchLatency, +}); +``` + +--- + +## CLI Advanced Operations + +### Database Import/Export + +```bash +# Export with compression +npx agentdb@latest export ./vectors.db ./backup.json.gz --compress + +# Import from backup +npx agentdb@latest import ./backup.json.gz --decompress + +# Merge databases +npx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite +``` + +### Database Optimization + +```bash +# Vacuum database (reclaim space) +sqlite3 .agentdb/vectors.db "VACUUM;" + +# Analyze for query optimization +sqlite3 .agentdb/vectors.db "ANALYZE;" + +# Rebuild indices +npx agentdb@latest reindex ./vectors.db +``` + +--- + +## Environment Variables + +```bash +# AgentDB configuration +AGENTDB_PATH=.agentdb/reasoningbank.db +AGENTDB_ENABLED=true + +# Performance tuning +AGENTDB_QUANTIZATION=binary # binary|scalar|product|none +AGENTDB_CACHE_SIZE=2000 +AGENTDB_HNSW_M=16 +AGENTDB_HNSW_EF=100 + +# Learning plugins +AGENTDB_LEARNING=true + +# Reasoning agents +AGENTDB_REASONING=true + +# QUIC synchronization +AGENTDB_QUIC_SYNC=true +AGENTDB_QUIC_PORT=4433 +AGENTDB_QUIC_PEERS=host1:4433,host2:4433 +``` + +--- + +## Troubleshooting + +### Issue: QUIC sync not working + +```bash +# Check firewall allows UDP port 4433 +sudo ufw allow 4433/udp + +# Verify peers are reachable +ping host1 + +# Check QUIC logs +DEBUG=agentdb:quic node server.js +``` + +### Issue: Hybrid search returns no results + +```typescript +// Relax filters +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + k: 100, // Increase k + filters: { + // Remove or relax filters + }, +}); +``` + +### Issue: Memory consolidation too aggressive + +```typescript +// Disable automatic optimization +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + optimizeMemory: false, // Disable auto-consolidation + k: 10, +}); +``` + +--- + +## Learn More + +- **QUIC Protocol**: docs/quic-synchronization.pdf +- **Hybrid Search**: docs/hybrid-search-guide.md +- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb +- **Website**: https://agentdb.ruv.io + +--- + +**Category**: Advanced / Distributed Systems +**Difficulty**: Advanced +**Estimated Time**: 45-60 minutes diff --git a/.agents/skills/agentdb-learning/SKILL.md b/.agents/skills/agentdb-learning/SKILL.md new file mode 100644 index 0000000..874760c --- /dev/null +++ b/.agents/skills/agentdb-learning/SKILL.md @@ -0,0 +1,545 @@ +--- +name: "AgentDB Learning Plugins" +description: "Create and train AI learning plugins with AgentDB's 9 reinforcement learning algorithms. Includes Decision Transformer, Q-Learning, SARSA, Actor-Critic, and more. Use when building self-learning agents, implementing RL, or optimizing agent behavior through experience." +--- + +# AgentDB Learning Plugins + +## What This Skill Does + +Provides access to 9 reinforcement learning algorithms via AgentDB's plugin system. Create, train, and deploy learning plugins for autonomous agents that improve through experience. Includes offline RL (Decision Transformer), value-based learning (Q-Learning), policy gradients (Actor-Critic), and advanced techniques. + +**Performance**: Train models 10-100x faster with WASM-accelerated neural inference. + +## Prerequisites + +- Node.js 18+ +- AgentDB v1.0.7+ (via agentic-flow) +- Basic understanding of reinforcement learning (recommended) + +--- + +## Quick Start with CLI + +### Create Learning Plugin + +```bash +# Interactive wizard +npx agentdb@latest create-plugin + +# Use specific template +npx agentdb@latest create-plugin -t decision-transformer -n my-agent + +# Preview without creating +npx agentdb@latest create-plugin -t q-learning --dry-run + +# Custom output directory +npx agentdb@latest create-plugin -t actor-critic -o ./plugins +``` + +### List Available Templates + +```bash +# Show all plugin templates +npx agentdb@latest list-templates + +# Available templates: +# - decision-transformer (sequence modeling RL - recommended) +# - q-learning (value-based learning) +# - sarsa (on-policy TD learning) +# - actor-critic (policy gradient with baseline) +# - curiosity-driven (exploration-based) +``` + +### Manage Plugins + +```bash +# List installed plugins +npx agentdb@latest list-plugins + +# Get plugin information +npx agentdb@latest plugin-info my-agent + +# Shows: algorithm, configuration, training status +``` + +--- + +## Quick Start with API + +```typescript +import { createAgentDBAdapter } from 'agentic-flow/reasoningbank'; + +// Initialize with learning enabled +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/learning.db', + enableLearning: true, // Enable learning plugins + enableReasoning: true, + cacheSize: 1000, +}); + +// Store training experience +await adapter.insertPattern({ + id: '', + type: 'experience', + domain: 'game-playing', + pattern_data: JSON.stringify({ + embedding: await computeEmbedding('state-action-reward'), + pattern: { + state: [0.1, 0.2, 0.3], + action: 2, + reward: 1.0, + next_state: [0.15, 0.25, 0.35], + done: false + } + }), + confidence: 0.9, + usage_count: 1, + success_count: 1, + created_at: Date.now(), + last_used: Date.now(), +}); + +// Train learning model +const metrics = await adapter.train({ + epochs: 50, + batchSize: 32, +}); + +console.log('Training Loss:', metrics.loss); +console.log('Duration:', metrics.duration, 'ms'); +``` + +--- + +## Available Learning Algorithms (9 Total) + +### 1. Decision Transformer (Recommended) + +**Type**: Offline Reinforcement Learning +**Best For**: Learning from logged experiences, imitation learning +**Strengths**: No online interaction needed, stable training + +```bash +npx agentdb@latest create-plugin -t decision-transformer -n dt-agent +``` + +**Use Cases**: +- Learn from historical data +- Imitation learning from expert demonstrations +- Safe learning without environment interaction +- Sequence modeling tasks + +**Configuration**: +```json +{ + "algorithm": "decision-transformer", + "model_size": "base", + "context_length": 20, + "embed_dim": 128, + "n_heads": 8, + "n_layers": 6 +} +``` + +### 2. Q-Learning + +**Type**: Value-Based RL (Off-Policy) +**Best For**: Discrete action spaces, sample efficiency +**Strengths**: Proven, simple, works well for small/medium problems + +```bash +npx agentdb@latest create-plugin -t q-learning -n q-agent +``` + +**Use Cases**: +- Grid worlds, board games +- Navigation tasks +- Resource allocation +- Discrete decision-making + +**Configuration**: +```json +{ + "algorithm": "q-learning", + "learning_rate": 0.001, + "gamma": 0.99, + "epsilon": 0.1, + "epsilon_decay": 0.995 +} +``` + +### 3. SARSA + +**Type**: Value-Based RL (On-Policy) +**Best For**: Safe exploration, risk-sensitive tasks +**Strengths**: More conservative than Q-Learning, better for safety + +```bash +npx agentdb@latest create-plugin -t sarsa -n sarsa-agent +``` + +**Use Cases**: +- Safety-critical applications +- Risk-sensitive decision-making +- Online learning with exploration + +**Configuration**: +```json +{ + "algorithm": "sarsa", + "learning_rate": 0.001, + "gamma": 0.99, + "epsilon": 0.1 +} +``` + +### 4. Actor-Critic + +**Type**: Policy Gradient with Value Baseline +**Best For**: Continuous actions, variance reduction +**Strengths**: Stable, works for continuous/discrete actions + +```bash +npx agentdb@latest create-plugin -t actor-critic -n ac-agent +``` + +**Use Cases**: +- Continuous control (robotics, simulations) +- Complex action spaces +- Multi-agent coordination + +**Configuration**: +```json +{ + "algorithm": "actor-critic", + "actor_lr": 0.001, + "critic_lr": 0.002, + "gamma": 0.99, + "entropy_coef": 0.01 +} +``` + +### 5. Active Learning + +**Type**: Query-Based Learning +**Best For**: Label-efficient learning, human-in-the-loop +**Strengths**: Minimizes labeling cost, focuses on uncertain samples + +**Use Cases**: +- Human feedback incorporation +- Label-efficient training +- Uncertainty sampling +- Annotation cost reduction + +### 6. Adversarial Training + +**Type**: Robustness Enhancement +**Best For**: Safety, robustness to perturbations +**Strengths**: Improves model robustness, adversarial defense + +**Use Cases**: +- Security applications +- Robust decision-making +- Adversarial defense +- Safety testing + +### 7. Curriculum Learning + +**Type**: Progressive Difficulty Training +**Best For**: Complex tasks, faster convergence +**Strengths**: Stable learning, faster convergence on hard tasks + +**Use Cases**: +- Complex multi-stage tasks +- Hard exploration problems +- Skill composition +- Transfer learning + +### 8. Federated Learning + +**Type**: Distributed Learning +**Best For**: Privacy, distributed data +**Strengths**: Privacy-preserving, scalable + +**Use Cases**: +- Multi-agent systems +- Privacy-sensitive data +- Distributed training +- Collaborative learning + +### 9. Multi-Task Learning + +**Type**: Transfer Learning +**Best For**: Related tasks, knowledge sharing +**Strengths**: Faster learning on new tasks, better generalization + +**Use Cases**: +- Task families +- Transfer learning +- Domain adaptation +- Meta-learning + +--- + +## Training Workflow + +### 1. Collect Experiences + +```typescript +// Store experiences during agent execution +for (let i = 0; i < numEpisodes; i++) { + const episode = runEpisode(); + + for (const step of episode.steps) { + await adapter.insertPattern({ + id: '', + type: 'experience', + domain: 'task-domain', + pattern_data: JSON.stringify({ + embedding: await computeEmbedding(JSON.stringify(step)), + pattern: { + state: step.state, + action: step.action, + reward: step.reward, + next_state: step.next_state, + done: step.done + } + }), + confidence: step.reward > 0 ? 0.9 : 0.5, + usage_count: 1, + success_count: step.reward > 0 ? 1 : 0, + created_at: Date.now(), + last_used: Date.now(), + }); + } +} +``` + +### 2. Train Model + +```typescript +// Train on collected experiences +const trainingMetrics = await adapter.train({ + epochs: 100, + batchSize: 64, + learningRate: 0.001, + validationSplit: 0.2, +}); + +console.log('Training Metrics:', trainingMetrics); +// { +// loss: 0.023, +// valLoss: 0.028, +// duration: 1523, +// epochs: 100 +// } +``` + +### 3. Evaluate Performance + +```typescript +// Retrieve similar successful experiences +const testQuery = await computeEmbedding(JSON.stringify(testState)); +const result = await adapter.retrieveWithReasoning(testQuery, { + domain: 'task-domain', + k: 10, + synthesizeContext: true, +}); + +// Evaluate action quality +const suggestedAction = result.memories[0].pattern.action; +const confidence = result.memories[0].similarity; + +console.log('Suggested Action:', suggestedAction); +console.log('Confidence:', confidence); +``` + +--- + +## Advanced Training Techniques + +### Experience Replay + +```typescript +// Store experiences in buffer +const replayBuffer = []; + +// Sample random batch for training +const batch = sampleRandomBatch(replayBuffer, batchSize: 32); + +// Train on batch +await adapter.train({ + data: batch, + epochs: 1, + batchSize: 32, +}); +``` + +### Prioritized Experience Replay + +```typescript +// Store experiences with priority (TD error) +await adapter.insertPattern({ + // ... standard fields + confidence: tdError, // Use TD error as confidence/priority + // ... +}); + +// Retrieve high-priority experiences +const highPriority = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'task-domain', + k: 32, + minConfidence: 0.7, // Only high TD-error experiences +}); +``` + +### Multi-Agent Training + +```typescript +// Collect experiences from multiple agents +for (const agent of agents) { + const experience = await agent.step(); + + await adapter.insertPattern({ + // ... store experience with agent ID + domain: `multi-agent/${agent.id}`, + }); +} + +// Train shared model +await adapter.train({ + epochs: 50, + batchSize: 64, +}); +``` + +--- + +## Performance Optimization + +### Batch Training + +```typescript +// Collect batch of experiences +const experiences = collectBatch(size: 1000); + +// Batch insert (500x faster) +for (const exp of experiences) { + await adapter.insertPattern({ /* ... */ }); +} + +// Train on batch +await adapter.train({ + epochs: 10, + batchSize: 128, // Larger batch for efficiency +}); +``` + +### Incremental Learning + +```typescript +// Train incrementally as new data arrives +setInterval(async () => { + const newExperiences = getNewExperiences(); + + if (newExperiences.length > 100) { + await adapter.train({ + epochs: 5, + batchSize: 32, + }); + } +}, 60000); // Every minute +``` + +--- + +## Integration with Reasoning Agents + +Combine learning with reasoning for better performance: + +```typescript +// Train learning model +await adapter.train({ epochs: 50, batchSize: 32 }); + +// Use reasoning agents for inference +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'decision-making', + k: 10, + useMMR: true, // Diverse experiences + synthesizeContext: true, // Rich context + optimizeMemory: true, // Consolidate patterns +}); + +// Make decision based on learned experiences + reasoning +const decision = result.context.suggestedAction; +const confidence = result.memories[0].similarity; +``` + +--- + +## CLI Operations + +```bash +# Create plugin +npx agentdb@latest create-plugin -t decision-transformer -n my-plugin + +# List plugins +npx agentdb@latest list-plugins + +# Get plugin info +npx agentdb@latest plugin-info my-plugin + +# List templates +npx agentdb@latest list-templates +``` + +--- + +## Troubleshooting + +### Issue: Training not converging +```typescript +// Reduce learning rate +await adapter.train({ + epochs: 100, + batchSize: 32, + learningRate: 0.0001, // Lower learning rate +}); +``` + +### Issue: Overfitting +```typescript +// Use validation split +await adapter.train({ + epochs: 50, + batchSize: 64, + validationSplit: 0.2, // 20% validation +}); + +// Enable memory optimization +await adapter.retrieveWithReasoning(queryEmbedding, { + optimizeMemory: true, // Consolidate, reduce overfitting +}); +``` + +### Issue: Slow training +```bash +# Enable quantization for faster inference +# Use binary quantization (32x faster) +``` + +--- + +## Learn More + +- **Algorithm Papers**: See docs/algorithms/ for detailed papers +- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb +- **MCP Integration**: `npx agentdb@latest mcp` +- **Website**: https://agentdb.ruv.io + +--- + +**Category**: Machine Learning / Reinforcement Learning +**Difficulty**: Intermediate to Advanced +**Estimated Time**: 30-60 minutes diff --git a/.agents/skills/agentdb-memory-patterns/SKILL.md b/.agents/skills/agentdb-memory-patterns/SKILL.md new file mode 100644 index 0000000..6074a7a --- /dev/null +++ b/.agents/skills/agentdb-memory-patterns/SKILL.md @@ -0,0 +1,339 @@ +--- +name: "AgentDB Memory Patterns" +description: "Implement persistent memory patterns for AI agents using AgentDB. Includes session memory, long-term storage, pattern learning, and context management. Use when building stateful agents, chat systems, or intelligent assistants." +--- + +# AgentDB Memory Patterns + +## What This Skill Does + +Provides memory management patterns for AI agents using AgentDB's persistent storage and ReasoningBank integration. Enables agents to remember conversations, learn from interactions, and maintain context across sessions. + +**Performance**: 150x-12,500x faster than traditional solutions with 100% backward compatibility. + +## Prerequisites + +- Node.js 18+ +- AgentDB v1.0.7+ (via agentic-flow or standalone) +- Understanding of agent architectures + +## Quick Start with CLI + +### Initialize AgentDB + +```bash +# Initialize vector database +npx agentdb@latest init ./agents.db + +# Or with custom dimensions +npx agentdb@latest init ./agents.db --dimension 768 + +# Use preset configurations +npx agentdb@latest init ./agents.db --preset large + +# In-memory database for testing +npx agentdb@latest init ./memory.db --in-memory +``` + +### Start MCP Server for Codex + +```bash +# Start MCP server (integrates with Codex) +npx agentdb@latest mcp + +# Add to Codex (one-time setup) +Codex mcp add agentdb npx agentdb@latest mcp +``` + +### Create Learning Plugin + +```bash +# Interactive plugin wizard +npx agentdb@latest create-plugin + +# Use template directly +npx agentdb@latest create-plugin -t decision-transformer -n my-agent + +# Available templates: +# - decision-transformer (sequence modeling RL) +# - q-learning (value-based learning) +# - sarsa (on-policy TD learning) +# - actor-critic (policy gradient) +# - curiosity-driven (exploration-based) +``` + +## Quick Start with API + +```typescript +import { createAgentDBAdapter } from 'agentic-flow/reasoningbank'; + +// Initialize with default configuration +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/reasoningbank.db', + enableLearning: true, // Enable learning plugins + enableReasoning: true, // Enable reasoning agents + quantizationType: 'scalar', // binary | scalar | product | none + cacheSize: 1000, // In-memory cache +}); + +// Store interaction memory +const patternId = await adapter.insertPattern({ + id: '', + type: 'pattern', + domain: 'conversation', + pattern_data: JSON.stringify({ + embedding: await computeEmbedding('What is the capital of France?'), + pattern: { + user: 'What is the capital of France?', + assistant: 'The capital of France is Paris.', + timestamp: Date.now() + } + }), + confidence: 0.95, + usage_count: 1, + success_count: 1, + created_at: Date.now(), + last_used: Date.now(), +}); + +// Retrieve context with reasoning +const context = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'conversation', + k: 10, + useMMR: true, // Maximal Marginal Relevance + synthesizeContext: true, // Generate rich context +}); +``` + +## Memory Patterns + +### 1. Session Memory +```typescript +class SessionMemory { + async storeMessage(role: string, content: string) { + return await db.storeMemory({ + sessionId: this.sessionId, + role, + content, + timestamp: Date.now() + }); + } + + async getSessionHistory(limit = 20) { + return await db.query({ + filters: { sessionId: this.sessionId }, + orderBy: 'timestamp', + limit + }); + } +} +``` + +### 2. Long-Term Memory +```typescript +// Store important facts +await db.storeFact({ + category: 'user_preference', + key: 'language', + value: 'English', + confidence: 1.0, + source: 'explicit' +}); + +// Retrieve facts +const prefs = await db.getFacts({ + category: 'user_preference' +}); +``` + +### 3. Pattern Learning +```typescript +// Learn from successful interactions +await db.storePattern({ + trigger: 'user_asks_time', + response: 'provide_formatted_time', + success: true, + context: { timezone: 'UTC' } +}); + +// Apply learned patterns +const pattern = await db.matchPattern(currentContext); +``` + +## Advanced Patterns + +### Hierarchical Memory +```typescript +// Organize memory in hierarchy +await memory.organize({ + immediate: recentMessages, // Last 10 messages + shortTerm: sessionContext, // Current session + longTerm: importantFacts, // Persistent facts + semantic: embeddedKnowledge // Vector search +}); +``` + +### Memory Consolidation +```typescript +// Periodically consolidate memories +await memory.consolidate({ + strategy: 'importance', // Keep important memories + maxSize: 10000, // Size limit + minScore: 0.5 // Relevance threshold +}); +``` + +## CLI Operations + +### Query Database + +```bash +# Query with vector embedding +npx agentdb@latest query ./agents.db "[0.1,0.2,0.3,...]" + +# Top-k results +npx agentdb@latest query ./agents.db "[0.1,0.2,0.3]" -k 10 + +# With similarity threshold +npx agentdb@latest query ./agents.db "0.1 0.2 0.3" -t 0.75 + +# JSON output +npx agentdb@latest query ./agents.db "[...]" -f json +``` + +### Import/Export Data + +```bash +# Export vectors to file +npx agentdb@latest export ./agents.db ./backup.json + +# Import vectors from file +npx agentdb@latest import ./backup.json + +# Get database statistics +npx agentdb@latest stats ./agents.db +``` + +### Performance Benchmarks + +```bash +# Run performance benchmarks +npx agentdb@latest benchmark + +# Results show: +# - Pattern Search: 150x faster (100µs vs 15ms) +# - Batch Insert: 500x faster (2ms vs 1s) +# - Large-scale Query: 12,500x faster (8ms vs 100s) +``` + +## Integration with ReasoningBank + +```typescript +import { createAgentDBAdapter, migrateToAgentDB } from 'agentic-flow/reasoningbank'; + +// Migrate from legacy ReasoningBank +const result = await migrateToAgentDB( + '.swarm/memory.db', // Source (legacy) + '.agentdb/reasoningbank.db' // Destination (AgentDB) +); + +console.log(`✅ Migrated ${result.patternsMigrated} patterns`); + +// Train learning model +const adapter = await createAgentDBAdapter({ + enableLearning: true, +}); + +await adapter.train({ + epochs: 50, + batchSize: 32, +}); + +// Get optimal strategy with reasoning +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'task-planning', + synthesizeContext: true, + optimizeMemory: true, +}); +``` + +## Learning Plugins + +### Available Algorithms (9 Total) + +1. **Decision Transformer** - Sequence modeling RL (recommended) +2. **Q-Learning** - Value-based learning +3. **SARSA** - On-policy TD learning +4. **Actor-Critic** - Policy gradient with baseline +5. **Active Learning** - Query selection +6. **Adversarial Training** - Robustness +7. **Curriculum Learning** - Progressive difficulty +8. **Federated Learning** - Distributed learning +9. **Multi-task Learning** - Transfer learning + +### List and Manage Plugins + +```bash +# List available plugins +npx agentdb@latest list-plugins + +# List plugin templates +npx agentdb@latest list-templates + +# Get plugin info +npx agentdb@latest plugin-info +``` + +## Reasoning Agents (4 Modules) + +1. **PatternMatcher** - Find similar patterns with HNSW indexing +2. **ContextSynthesizer** - Generate rich context from multiple sources +3. **MemoryOptimizer** - Consolidate similar patterns, prune low-quality +4. **ExperienceCurator** - Quality-based experience filtering + +## Best Practices + +1. **Enable quantization**: Use scalar/binary for 4-32x memory reduction +2. **Use caching**: 1000 pattern cache for <1ms retrieval +3. **Batch operations**: 500x faster than individual inserts +4. **Train regularly**: Update learning models with new experiences +5. **Enable reasoning**: Automatic context synthesis and optimization +6. **Monitor metrics**: Use `stats` command to track performance + +## Troubleshooting + +### Issue: Memory growing too large +```bash +# Check database size +npx agentdb@latest stats ./agents.db + +# Enable quantization +# Use 'binary' (32x smaller) or 'scalar' (4x smaller) +``` + +### Issue: Slow search performance +```bash +# Enable HNSW indexing and caching +# Results: <100µs search time +``` + +### Issue: Migration from legacy ReasoningBank +```bash +# Automatic migration with validation +npx agentdb@latest migrate --source .swarm/memory.db +``` + +## Performance Characteristics + +- **Vector Search**: <100µs (HNSW indexing) +- **Pattern Retrieval**: <1ms (with cache) +- **Batch Insert**: 2ms for 100 patterns +- **Memory Efficiency**: 4-32x reduction with quantization +- **Backward Compatibility**: 100% compatible with ReasoningBank API + +## Learn More + +- GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb +- Documentation: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md +- MCP Integration: `npx agentdb@latest mcp` for Codex +- Website: https://agentdb.ruv.io diff --git a/.agents/skills/agentdb-optimization/SKILL.md b/.agents/skills/agentdb-optimization/SKILL.md new file mode 100644 index 0000000..f19df86 --- /dev/null +++ b/.agents/skills/agentdb-optimization/SKILL.md @@ -0,0 +1,509 @@ +--- +name: "AgentDB Performance Optimization" +description: "Optimize AgentDB performance with quantization (4-32x memory reduction), HNSW indexing (150x faster search), caching, and batch operations. Use when optimizing memory usage, improving search speed, or scaling to millions of vectors." +--- + +# AgentDB Performance Optimization + +## What This Skill Does + +Provides comprehensive performance optimization techniques for AgentDB vector databases. Achieve 150x-12,500x performance improvements through quantization, HNSW indexing, caching strategies, and batch operations. Reduce memory usage by 4-32x while maintaining accuracy. + +**Performance**: <100µs vector search, <1ms pattern retrieval, 2ms batch insert for 100 vectors. + +## Prerequisites + +- Node.js 18+ +- AgentDB v1.0.7+ (via agentic-flow) +- Existing AgentDB database or application + +--- + +## Quick Start + +### Run Performance Benchmarks + +```bash +# Comprehensive performance benchmarking +npx agentdb@latest benchmark + +# Results show: +# ✅ Pattern Search: 150x faster (100µs vs 15ms) +# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors) +# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors) +# ✅ Memory Efficiency: 4-32x reduction with quantization +``` + +### Enable Optimizations + +```typescript +import { createAgentDBAdapter } from 'agentic-flow/reasoningbank'; + +// Optimized configuration +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/optimized.db', + quantizationType: 'binary', // 32x memory reduction + cacheSize: 1000, // In-memory cache + enableLearning: true, + enableReasoning: true, +}); +``` + +--- + +## Quantization Strategies + +### 1. Binary Quantization (32x Reduction) + +**Best For**: Large-scale deployments (1M+ vectors), memory-constrained environments +**Trade-off**: ~2-5% accuracy loss, 32x memory reduction, 10x faster + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'binary', + // 768-dim float32 (3072 bytes) → 96 bytes binary + // 1M vectors: 3GB → 96MB +}); +``` + +**Use Cases**: +- Mobile/edge deployment +- Large-scale vector storage (millions of vectors) +- Real-time search with memory constraints + +**Performance**: +- Memory: 32x smaller +- Search Speed: 10x faster (bit operations) +- Accuracy: 95-98% of original + +### 2. Scalar Quantization (4x Reduction) + +**Best For**: Balanced performance/accuracy, moderate datasets +**Trade-off**: ~1-2% accuracy loss, 4x memory reduction, 3x faster + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'scalar', + // 768-dim float32 (3072 bytes) → 768 bytes (uint8) + // 1M vectors: 3GB → 768MB +}); +``` + +**Use Cases**: +- Production applications requiring high accuracy +- Medium-scale deployments (10K-1M vectors) +- General-purpose optimization + +**Performance**: +- Memory: 4x smaller +- Search Speed: 3x faster +- Accuracy: 98-99% of original + +### 3. Product Quantization (8-16x Reduction) + +**Best For**: High-dimensional vectors, balanced compression +**Trade-off**: ~3-7% accuracy loss, 8-16x memory reduction, 5x faster + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'product', + // 768-dim float32 (3072 bytes) → 48-96 bytes + // 1M vectors: 3GB → 192MB +}); +``` + +**Use Cases**: +- High-dimensional embeddings (>512 dims) +- Image/video embeddings +- Large-scale similarity search + +**Performance**: +- Memory: 8-16x smaller +- Search Speed: 5x faster +- Accuracy: 93-97% of original + +### 4. No Quantization (Full Precision) + +**Best For**: Maximum accuracy, small datasets +**Trade-off**: No accuracy loss, full memory usage + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'none', + // Full float32 precision +}); +``` + +--- + +## HNSW Indexing + +**Hierarchical Navigable Small World** - O(log n) search complexity + +### Automatic HNSW + +AgentDB automatically builds HNSW indices: + +```typescript +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/vectors.db', + // HNSW automatically enabled +}); + +// Search with HNSW (100µs vs 15ms linear scan) +const results = await adapter.retrieveWithReasoning(queryEmbedding, { + k: 10, +}); +``` + +### HNSW Parameters + +```typescript +// Advanced HNSW configuration +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/vectors.db', + hnswM: 16, // Connections per layer (default: 16) + hnswEfConstruction: 200, // Build quality (default: 200) + hnswEfSearch: 100, // Search quality (default: 100) +}); +``` + +**Parameter Tuning**: +- **M** (connections): Higher = better recall, more memory + - Small datasets (<10K): M = 8 + - Medium datasets (10K-100K): M = 16 + - Large datasets (>100K): M = 32 +- **efConstruction**: Higher = better index quality, slower build + - Fast build: 100 + - Balanced: 200 (default) + - High quality: 400 +- **efSearch**: Higher = better recall, slower search + - Fast search: 50 + - Balanced: 100 (default) + - High recall: 200 + +--- + +## Caching Strategies + +### In-Memory Pattern Cache + +```typescript +const adapter = await createAgentDBAdapter({ + cacheSize: 1000, // Cache 1000 most-used patterns +}); + +// First retrieval: ~2ms (database) +// Subsequent: <1ms (cache hit) +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + k: 10, +}); +``` + +**Cache Tuning**: +- Small applications: 100-500 patterns +- Medium applications: 500-2000 patterns +- Large applications: 2000-5000 patterns + +### LRU Cache Behavior + +```typescript +// Cache automatically evicts least-recently-used patterns +// Most frequently accessed patterns stay in cache + +// Monitor cache performance +const stats = await adapter.getStats(); +console.log('Cache Hit Rate:', stats.cacheHitRate); +// Aim for >80% hit rate +``` + +--- + +## Batch Operations + +### Batch Insert (500x Faster) + +```typescript +// ❌ SLOW: Individual inserts +for (const doc of documents) { + await adapter.insertPattern({ /* ... */ }); // 1s for 100 docs +} + +// ✅ FAST: Batch insert +const patterns = documents.map(doc => ({ + id: '', + type: 'document', + domain: 'knowledge', + pattern_data: JSON.stringify({ + embedding: doc.embedding, + text: doc.text, + }), + confidence: 1.0, + usage_count: 0, + success_count: 0, + created_at: Date.now(), + last_used: Date.now(), +})); + +// Insert all at once (2ms for 100 docs) +for (const pattern of patterns) { + await adapter.insertPattern(pattern); +} +``` + +### Batch Retrieval + +```typescript +// Retrieve multiple queries efficiently +const queries = [queryEmbedding1, queryEmbedding2, queryEmbedding3]; + +// Parallel retrieval +const results = await Promise.all( + queries.map(q => adapter.retrieveWithReasoning(q, { k: 5 })) +); +``` + +--- + +## Memory Optimization + +### Automatic Consolidation + +```typescript +// Enable automatic pattern consolidation +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'documents', + optimizeMemory: true, // Consolidate similar patterns + k: 10, +}); + +console.log('Optimizations:', result.optimizations); +// { +// consolidated: 15, // Merged 15 similar patterns +// pruned: 3, // Removed 3 low-quality patterns +// improved_quality: 0.12 // 12% quality improvement +// } +``` + +### Manual Optimization + +```typescript +// Manually trigger optimization +await adapter.optimize(); + +// Get statistics +const stats = await adapter.getStats(); +console.log('Before:', stats.totalPatterns); +console.log('After:', stats.totalPatterns); // Reduced by ~10-30% +``` + +### Pruning Strategies + +```typescript +// Prune low-confidence patterns +await adapter.prune({ + minConfidence: 0.5, // Remove confidence < 0.5 + minUsageCount: 2, // Remove usage_count < 2 + maxAge: 30 * 24 * 3600, // Remove >30 days old +}); +``` + +--- + +## Performance Monitoring + +### Database Statistics + +```bash +# Get comprehensive stats +npx agentdb@latest stats .agentdb/vectors.db + +# Output: +# Total Patterns: 125,430 +# Database Size: 47.2 MB (with binary quantization) +# Avg Confidence: 0.87 +# Domains: 15 +# Cache Hit Rate: 84% +# Index Type: HNSW +``` + +### Runtime Metrics + +```typescript +const stats = await adapter.getStats(); + +console.log('Performance Metrics:'); +console.log('Total Patterns:', stats.totalPatterns); +console.log('Database Size:', stats.dbSize); +console.log('Avg Confidence:', stats.avgConfidence); +console.log('Cache Hit Rate:', stats.cacheHitRate); +console.log('Search Latency (avg):', stats.avgSearchLatency); +console.log('Insert Latency (avg):', stats.avgInsertLatency); +``` + +--- + +## Optimization Recipes + +### Recipe 1: Maximum Speed (Sacrifice Accuracy) + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'binary', // 32x memory reduction + cacheSize: 5000, // Large cache + hnswM: 8, // Fewer connections = faster + hnswEfSearch: 50, // Low search quality = faster +}); + +// Expected: <50µs search, 90-95% accuracy +``` + +### Recipe 2: Balanced Performance + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'scalar', // 4x memory reduction + cacheSize: 1000, // Standard cache + hnswM: 16, // Balanced connections + hnswEfSearch: 100, // Balanced quality +}); + +// Expected: <100µs search, 98-99% accuracy +``` + +### Recipe 3: Maximum Accuracy + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'none', // No quantization + cacheSize: 2000, // Large cache + hnswM: 32, // Many connections + hnswEfSearch: 200, // High search quality +}); + +// Expected: <200µs search, 100% accuracy +``` + +### Recipe 4: Memory-Constrained (Mobile/Edge) + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'binary', // 32x memory reduction + cacheSize: 100, // Small cache + hnswM: 8, // Minimal connections +}); + +// Expected: <100µs search, ~10MB for 100K vectors +``` + +--- + +## Scaling Strategies + +### Small Scale (<10K vectors) + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'none', // Full precision + cacheSize: 500, + hnswM: 8, +}); +``` + +### Medium Scale (10K-100K vectors) + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'scalar', // 4x reduction + cacheSize: 1000, + hnswM: 16, +}); +``` + +### Large Scale (100K-1M vectors) + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'binary', // 32x reduction + cacheSize: 2000, + hnswM: 32, +}); +``` + +### Massive Scale (>1M vectors) + +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'product', // 8-16x reduction + cacheSize: 5000, + hnswM: 48, + hnswEfConstruction: 400, +}); +``` + +--- + +## Troubleshooting + +### Issue: High memory usage + +```bash +# Check database size +npx agentdb@latest stats .agentdb/vectors.db + +# Enable quantization +# Use 'binary' for 32x reduction +``` + +### Issue: Slow search performance + +```typescript +// Increase cache size +const adapter = await createAgentDBAdapter({ + cacheSize: 2000, // Increase from 1000 +}); + +// Reduce search quality (faster) +const result = await adapter.retrieveWithReasoning(queryEmbedding, { + k: 5, // Reduce from 10 +}); +``` + +### Issue: Low accuracy + +```typescript +// Disable or use lighter quantization +const adapter = await createAgentDBAdapter({ + quantizationType: 'scalar', // Instead of 'binary' + hnswEfSearch: 200, // Higher search quality +}); +``` + +--- + +## Performance Benchmarks + +**Test System**: AMD Ryzen 9 5950X, 64GB RAM + +| Operation | Vector Count | No Optimization | Optimized | Improvement | +|-----------|-------------|-----------------|-----------|-------------| +| Search | 10K | 15ms | 100µs | 150x | +| Search | 100K | 150ms | 120µs | 1,250x | +| Search | 1M | 100s | 8ms | 12,500x | +| Batch Insert (100) | - | 1s | 2ms | 500x | +| Memory Usage | 1M | 3GB | 96MB | 32x (binary) | + +--- + +## Learn More + +- **Quantization Paper**: docs/quantization-techniques.pdf +- **HNSW Algorithm**: docs/hnsw-index.pdf +- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb +- **Website**: https://agentdb.ruv.io + +--- + +**Category**: Performance / Optimization +**Difficulty**: Intermediate +**Estimated Time**: 20-30 minutes diff --git a/.agents/skills/agentdb-vector-search/SKILL.md b/.agents/skills/agentdb-vector-search/SKILL.md new file mode 100644 index 0000000..31ebc72 --- /dev/null +++ b/.agents/skills/agentdb-vector-search/SKILL.md @@ -0,0 +1,339 @@ +--- +name: "AgentDB Vector Search" +description: "Implement semantic vector search with AgentDB for intelligent document retrieval, similarity matching, and context-aware querying. Use when building RAG systems, semantic search engines, or intelligent knowledge bases." +--- + +# AgentDB Vector Search + +## What This Skill Does + +Implements vector-based semantic search using AgentDB's high-performance vector database with **150x-12,500x faster** operations than traditional solutions. Features HNSW indexing, quantization, and sub-millisecond search (<100µs). + +## Prerequisites + +- Node.js 18+ +- AgentDB v1.0.7+ (via agentic-flow or standalone) +- OpenAI API key (for embeddings) or custom embedding model + +## Quick Start with CLI + +### Initialize Vector Database + +```bash +# Initialize with default dimensions (1536 for OpenAI ada-002) +npx agentdb@latest init ./vectors.db + +# Custom dimensions for different embedding models +npx agentdb@latest init ./vectors.db --dimension 768 # sentence-transformers +npx agentdb@latest init ./vectors.db --dimension 384 # all-MiniLM-L6-v2 + +# Use preset configurations +npx agentdb@latest init ./vectors.db --preset small # <10K vectors +npx agentdb@latest init ./vectors.db --preset medium # 10K-100K vectors +npx agentdb@latest init ./vectors.db --preset large # >100K vectors + +# In-memory database for testing +npx agentdb@latest init ./vectors.db --in-memory +``` + +### Query Vector Database + +```bash +# Basic similarity search +npx agentdb@latest query ./vectors.db "[0.1,0.2,0.3,...]" + +# Top-k results +npx agentdb@latest query ./vectors.db "[0.1,0.2,0.3]" -k 10 + +# With similarity threshold (cosine similarity) +npx agentdb@latest query ./vectors.db "0.1 0.2 0.3" -t 0.75 -m cosine + +# Different distance metrics +npx agentdb@latest query ./vectors.db "[...]" -m euclidean # L2 distance +npx agentdb@latest query ./vectors.db "[...]" -m dot # Dot product + +# JSON output for automation +npx agentdb@latest query ./vectors.db "[...]" -f json -k 5 + +# Verbose output with distances +npx agentdb@latest query ./vectors.db "[...]" -v +``` + +### Import/Export Vectors + +```bash +# Export vectors to JSON +npx agentdb@latest export ./vectors.db ./backup.json + +# Import vectors from JSON +npx agentdb@latest import ./backup.json + +# Get database statistics +npx agentdb@latest stats ./vectors.db +``` + +## Quick Start with API + +```typescript +import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank'; + +// Initialize with vector search optimizations +const adapter = await createAgentDBAdapter({ + dbPath: '.agentdb/vectors.db', + enableLearning: false, // Vector search only + enableReasoning: true, // Enable semantic matching + quantizationType: 'binary', // 32x memory reduction + cacheSize: 1000, // Fast retrieval +}); + +// Store document with embedding +const text = "The quantum computer achieved 100 qubits"; +const embedding = await computeEmbedding(text); + +await adapter.insertPattern({ + id: '', + type: 'document', + domain: 'technology', + pattern_data: JSON.stringify({ + embedding, + text, + metadata: { category: "quantum", date: "2025-01-15" } + }), + confidence: 1.0, + usage_count: 0, + success_count: 0, + created_at: Date.now(), + last_used: Date.now(), +}); + +// Semantic search with MMR (Maximal Marginal Relevance) +const queryEmbedding = await computeEmbedding("quantum computing advances"); +const results = await adapter.retrieveWithReasoning(queryEmbedding, { + domain: 'technology', + k: 10, + useMMR: true, // Diverse results + synthesizeContext: true, // Rich context +}); +``` + +## Core Features + +### 1. Vector Storage +```typescript +// Store with automatic embedding +await db.storeWithEmbedding({ + content: "Your document text", + metadata: { source: "docs", page: 42 } +}); +``` + +### 2. Similarity Search +```typescript +// Find similar documents +const similar = await db.findSimilar("quantum computing", { + limit: 5, + minScore: 0.75 +}); +``` + +### 3. Hybrid Search (Vector + Metadata) +```typescript +// Combine vector similarity with metadata filtering +const results = await db.hybridSearch({ + query: "machine learning models", + filters: { + category: "research", + date: { $gte: "2024-01-01" } + }, + limit: 20 +}); +``` + +## Advanced Usage + +### RAG (Retrieval Augmented Generation) +```typescript +// Build RAG pipeline +async function ragQuery(question: string) { + // 1. Get relevant context + const context = await db.searchSimilar( + await embed(question), + { limit: 5, threshold: 0.7 } + ); + + // 2. Generate answer with context + const prompt = `Context: ${context.map(c => c.text).join('\n')} +Question: ${question}`; + + return await llm.generate(prompt); +} +``` + +### Batch Operations +```typescript +// Efficient batch storage +await db.batchStore(documents.map(doc => ({ + text: doc.content, + embedding: doc.vector, + metadata: doc.meta +}))); +``` + +## MCP Server Integration + +```bash +# Start AgentDB MCP server for Codex +npx agentdb@latest mcp + +# Add to Codex (one-time setup) +Codex mcp add agentdb npx agentdb@latest mcp + +# Now use MCP tools in Codex: +# - agentdb_query: Semantic vector search +# - agentdb_store: Store documents with embeddings +# - agentdb_stats: Database statistics +``` + +## Performance Benchmarks + +```bash +# Run comprehensive benchmarks +npx agentdb@latest benchmark + +# Results: +# ✅ Pattern Search: 150x faster (100µs vs 15ms) +# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors) +# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors) +# ✅ Memory Efficiency: 4-32x reduction with quantization +``` + +## Quantization Options + +AgentDB provides multiple quantization strategies for memory efficiency: + +### Binary Quantization (32x reduction) +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'binary', // 768-dim → 96 bytes +}); +``` + +### Scalar Quantization (4x reduction) +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'scalar', // 768-dim → 768 bytes +}); +``` + +### Product Quantization (8-16x reduction) +```typescript +const adapter = await createAgentDBAdapter({ + quantizationType: 'product', // 768-dim → 48-96 bytes +}); +``` + +## Distance Metrics + +```bash +# Cosine similarity (default, best for most use cases) +npx agentdb@latest query ./db.sqlite "[...]" -m cosine + +# Euclidean distance (L2 norm) +npx agentdb@latest query ./db.sqlite "[...]" -m euclidean + +# Dot product (for normalized vectors) +npx agentdb@latest query ./db.sqlite "[...]" -m dot +``` + +## Advanced Features + +### HNSW Indexing +- **O(log n) search complexity** +- **Sub-millisecond retrieval** (<100µs) +- **Automatic index building** + +### Caching +- **1000 pattern in-memory cache** +- **<1ms pattern retrieval** +- **Automatic cache invalidation** + +### MMR (Maximal Marginal Relevance) +- **Diverse result sets** +- **Avoid redundancy** +- **Balance relevance and diversity** + +## Performance Tips + +1. **Enable HNSW indexing**: Automatic with AgentDB, 10-100x faster +2. **Use quantization**: Binary (32x), Scalar (4x), Product (8-16x) memory reduction +3. **Batch operations**: 500x faster for bulk inserts +4. **Match dimensions**: 1536 (OpenAI), 768 (sentence-transformers), 384 (MiniLM) +5. **Similarity threshold**: Start at 0.7 for quality, adjust based on use case +6. **Enable caching**: 1000 pattern cache for frequent queries + +## Troubleshooting + +### Issue: Slow search performance +```bash +# Check if HNSW indexing is enabled (automatic) +npx agentdb@latest stats ./vectors.db + +# Expected: <100µs search time +``` + +### Issue: High memory usage +```bash +# Enable binary quantization (32x reduction) +# Use in adapter: quantizationType: 'binary' +``` + +### Issue: Poor relevance +```bash +# Adjust similarity threshold +npx agentdb@latest query ./db.sqlite "[...]" -t 0.8 # Higher threshold + +# Or use MMR for diverse results +# Use in adapter: useMMR: true +``` + +### Issue: Wrong dimensions +```bash +# Check embedding model dimensions: +# - OpenAI ada-002: 1536 +# - sentence-transformers: 768 +# - all-MiniLM-L6-v2: 384 + +npx agentdb@latest init ./db.sqlite --dimension 768 +``` + +## Database Statistics + +```bash +# Get comprehensive stats +npx agentdb@latest stats ./vectors.db + +# Shows: +# - Total patterns/vectors +# - Database size +# - Average confidence +# - Domains distribution +# - Index status +``` + +## Performance Characteristics + +- **Vector Search**: <100µs (HNSW indexing) +- **Pattern Retrieval**: <1ms (with cache) +- **Batch Insert**: 2ms for 100 vectors +- **Memory Efficiency**: 4-32x reduction with quantization +- **Scalability**: Handles 1M+ vectors efficiently +- **Latency**: Sub-millisecond for most operations + +## Learn More + +- GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb +- Documentation: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md +- MCP Integration: `npx agentdb@latest mcp` for Codex +- Website: https://agentdb.ruv.io +- CLI Help: `npx agentdb@latest --help` +- Command Help: `npx agentdb@latest help ` diff --git a/.agents/skills/browser/SKILL.md b/.agents/skills/browser/SKILL.md new file mode 100644 index 0000000..085b3c7 --- /dev/null +++ b/.agents/skills/browser/SKILL.md @@ -0,0 +1,204 @@ +--- +name: browser +description: Web browser automation with AI-optimized snapshots for Codex-flow agents +version: 1.0.0 +triggers: + - /browser + - browse + - web automation + - scrape + - navigate + - screenshot +tools: + - browser/open + - browser/snapshot + - browser/click + - browser/fill + - browser/screenshot + - browser/close +--- + +# Browser Automation Skill + +Web browser automation using agent-browser with AI-optimized snapshots. Reduces context by 93% using element refs (@e1, @e2) instead of full DOM. + +## Core Workflow + +```bash +# 1. Navigate to page +agent-browser open + +# 2. Get accessibility tree with element refs +agent-browser snapshot -i # -i = interactive elements only + +# 3. Interact using refs from snapshot +agent-browser click @e2 +agent-browser fill @e3 "text" + +# 4. Re-snapshot after page changes +agent-browser snapshot -i +``` + +## Quick Reference + +### Navigation +| Command | Description | +|---------|-------------| +| `open ` | Navigate to URL | +| `back` | Go back | +| `forward` | Go forward | +| `reload` | Reload page | +| `close` | Close browser | + +### Snapshots (AI-Optimized) +| Command | Description | +|---------|-------------| +| `snapshot` | Full accessibility tree | +| `snapshot -i` | Interactive elements only (buttons, links, inputs) | +| `snapshot -c` | Compact (remove empty elements) | +| `snapshot -d 3` | Limit depth to 3 levels | +| `screenshot [path]` | Capture screenshot (base64 if no path) | + +### Interaction +| Command | Description | +|---------|-------------| +| `click ` | Click element | +| `fill ` | Clear and fill input | +| `type ` | Type with key events | +| `press ` | Press key (Enter, Tab, etc.) | +| `hover ` | Hover element | +| `select ` | Select dropdown option | +| `check/uncheck ` | Toggle checkbox | +| `scroll [px]` | Scroll page | + +### Get Info +| Command | Description | +|---------|-------------| +| `get text ` | Get text content | +| `get html ` | Get innerHTML | +| `get value ` | Get input value | +| `get attr ` | Get attribute | +| `get title` | Get page title | +| `get url` | Get current URL | + +### Wait +| Command | Description | +|---------|-------------| +| `wait ` | Wait for element | +| `wait ` | Wait milliseconds | +| `wait --text "text"` | Wait for text | +| `wait --url "pattern"` | Wait for URL | +| `wait --load networkidle` | Wait for load state | + +### Sessions +| Command | Description | +|---------|-------------| +| `--session ` | Use isolated session | +| `session list` | List active sessions | + +## Selectors + +### Element Refs (Recommended) +```bash +# Get refs from snapshot +agent-browser snapshot -i +# Output: button "Submit" [ref=e2] + +# Use ref to interact +agent-browser click @e2 +``` + +### CSS Selectors +```bash +agent-browser click "#submit" +agent-browser fill ".email-input" "test@test.com" +``` + +### Semantic Locators +```bash +agent-browser find role button click --name "Submit" +agent-browser find label "Email" fill "test@test.com" +agent-browser find testid "login-btn" click +``` + +## Examples + +### Login Flow +```bash +agent-browser open https://example.com/login +agent-browser snapshot -i +agent-browser fill @e2 "user@example.com" +agent-browser fill @e3 "password123" +agent-browser click @e4 +agent-browser wait --url "**/dashboard" +``` + +### Form Submission +```bash +agent-browser open https://example.com/contact +agent-browser snapshot -i +agent-browser fill @e1 "John Doe" +agent-browser fill @e2 "john@example.com" +agent-browser fill @e3 "Hello, this is my message" +agent-browser click @e4 +agent-browser wait --text "Thank you" +``` + +### Data Extraction +```bash +agent-browser open https://example.com/products +agent-browser snapshot -i +# Iterate through product refs +agent-browser get text @e1 # Product name +agent-browser get text @e2 # Price +agent-browser get attr @e3 href # Link +``` + +### Multi-Session (Swarm) +```bash +# Session 1: Navigator +agent-browser --session nav open https://example.com +agent-browser --session nav state save auth.json + +# Session 2: Scraper (uses same auth) +agent-browser --session scrape state load auth.json +agent-browser --session scrape open https://example.com/data +agent-browser --session scrape snapshot -i +``` + +## Integration with Codex Flow + +### MCP Tools +All browser operations are available as MCP tools with `browser/` prefix: +- `browser/open` +- `browser/snapshot` +- `browser/click` +- `browser/fill` +- `browser/screenshot` +- etc. + +### Memory Integration +```bash +# Store successful patterns +npx @Codex-flow/cli memory store --namespace browser-patterns --key "login-flow" --value "snapshot->fill->click->wait" + +# Retrieve before similar task +npx @Codex-flow/cli memory search --query "login automation" +``` + +### Hooks +```bash +# Pre-browse hook (get context) +npx @Codex-flow/cli hooks pre-edit --file "browser-task.ts" + +# Post-browse hook (record success) +npx @Codex-flow/cli hooks post-task --task-id "browse-1" --success true +``` + +## Tips + +1. **Always use snapshots** - They're optimized for AI with refs +2. **Prefer `-i` flag** - Gets only interactive elements, smaller output +3. **Use refs, not selectors** - More reliable, deterministic +4. **Re-snapshot after navigation** - Page state changes +5. **Use sessions for parallel work** - Each session is isolated diff --git a/.agents/skills/github-code-review/SKILL.md b/.agents/skills/github-code-review/SKILL.md new file mode 100644 index 0000000..b12d74e --- /dev/null +++ b/.agents/skills/github-code-review/SKILL.md @@ -0,0 +1,1140 @@ +--- +name: github-code-review +version: 1.0.0 +description: Comprehensive GitHub code review with AI-powered swarm coordination +category: github +tags: [code-review, github, swarm, pr-management, automation] +author: Codex Flow +requires: + - github-cli + - ruv-swarm + - Codex-flow +capabilities: + - Multi-agent code review + - Automated PR management + - Security and performance analysis + - Swarm-based review orchestration + - Intelligent comment generation + - Quality gate enforcement +--- + +# GitHub Code Review Skill + +> **AI-Powered Code Review**: Deploy specialized review agents to perform comprehensive, intelligent code reviews that go beyond traditional static analysis. + +## 🎯 Quick Start + +### Simple Review +```bash +# Initialize review swarm for PR +gh pr view 123 --json files,diff | npx ruv-swarm github review-init --pr 123 + +# Post review status +gh pr comment 123 --body "🔍 Multi-agent code review initiated" +``` + +### Complete Review Workflow +```bash +# Get PR context with gh CLI +PR_DATA=$(gh pr view 123 --json files,additions,deletions,title,body) +PR_DIFF=$(gh pr diff 123) + +# Initialize comprehensive review +npx ruv-swarm github review-init \ + --pr 123 \ + --pr-data "$PR_DATA" \ + --diff "$PR_DIFF" \ + --agents "security,performance,style,architecture,accessibility" \ + --depth comprehensive +``` + +--- + +## 📚 Table of Contents + +
+Core Features + +- [Multi-Agent Review System](#multi-agent-review-system) +- [Specialized Review Agents](#specialized-review-agents) +- [PR-Based Swarm Management](#pr-based-swarm-management) +- [Automated Workflows](#automated-workflows) +- [Quality Gates & Checks](#quality-gates--checks) + +
+ +
+Review Agents + +- [Security Review Agent](#security-review-agent) +- [Performance Review Agent](#performance-review-agent) +- [Architecture Review Agent](#architecture-review-agent) +- [Style & Convention Agent](#style--convention-agent) +- [Accessibility Agent](#accessibility-agent) + +
+ +
+Advanced Features + +- [Context-Aware Reviews](#context-aware-reviews) +- [Learning from History](#learning-from-history) +- [Cross-PR Analysis](#cross-pr-analysis) +- [Custom Review Agents](#custom-review-agents) + +
+ +
+Integration & Automation + +- [CI/CD Integration](#cicd-integration) +- [Webhook Handlers](#webhook-handlers) +- [PR Comment Commands](#pr-comment-commands) +- [Automated Fixes](#automated-fixes) + +
+ +--- + +## 🚀 Core Features + +### Multi-Agent Review System + +Deploy specialized AI agents for comprehensive code review: + +```bash +# Initialize review swarm with GitHub CLI integration +PR_DATA=$(gh pr view 123 --json files,additions,deletions,title,body) +PR_DIFF=$(gh pr diff 123) + +# Start multi-agent review +npx ruv-swarm github review-init \ + --pr 123 \ + --pr-data "$PR_DATA" \ + --diff "$PR_DIFF" \ + --agents "security,performance,style,architecture,accessibility" \ + --depth comprehensive + +# Post initial review status +gh pr comment 123 --body "🔍 Multi-agent code review initiated" +``` + +**Benefits:** +- ✅ Parallel review by specialized agents +- ✅ Comprehensive coverage across multiple domains +- ✅ Faster review cycles with coordinated analysis +- ✅ Consistent quality standards enforcement + +--- + +## 🤖 Specialized Review Agents + +### Security Review Agent + +**Focus:** Identify security vulnerabilities and suggest fixes + +```bash +# Get changed files from PR +CHANGED_FILES=$(gh pr view 123 --json files --jq '.files[].path') + +# Run security-focused review +SECURITY_RESULTS=$(npx ruv-swarm github review-security \ + --pr 123 \ + --files "$CHANGED_FILES" \ + --check "owasp,cve,secrets,permissions" \ + --suggest-fixes) + +# Post findings based on severity +if echo "$SECURITY_RESULTS" | grep -q "critical"; then + # Request changes for critical issues + gh pr review 123 --request-changes --body "$SECURITY_RESULTS" + gh pr edit 123 --add-label "security-review-required" +else + # Post as comment for non-critical issues + gh pr comment 123 --body "$SECURITY_RESULTS" +fi +``` + +
+Security Checks Performed + +```javascript +{ + "checks": [ + "SQL injection vulnerabilities", + "XSS attack vectors", + "Authentication bypasses", + "Authorization flaws", + "Cryptographic weaknesses", + "Dependency vulnerabilities", + "Secret exposure", + "CORS misconfigurations" + ], + "actions": [ + "Block PR on critical issues", + "Suggest secure alternatives", + "Add security test cases", + "Update security documentation" + ] +} +``` + +
+ +
+Comment Template: Security Issue + +```markdown +🔒 **Security Issue: [Type]** + +**Severity**: 🔴 Critical / 🟡 High / 🟢 Low + +**Description**: +[Clear explanation of the security issue] + +**Impact**: +[Potential consequences if not addressed] + +**Suggested Fix**: +```language +[Code example of the fix] +``` + +**References**: +- [OWASP Guide](link) +- [Security Best Practices](link) +``` + +
+ +--- + +### Performance Review Agent + +**Focus:** Analyze performance impact and optimization opportunities + +```bash +# Run performance analysis +npx ruv-swarm github review-performance \ + --pr 123 \ + --profile "cpu,memory,io" \ + --benchmark-against main \ + --suggest-optimizations +``` + +
+Performance Metrics Analyzed + +```javascript +{ + "metrics": [ + "Algorithm complexity (Big O analysis)", + "Database query efficiency", + "Memory allocation patterns", + "Cache utilization", + "Network request optimization", + "Bundle size impact", + "Render performance" + ], + "benchmarks": [ + "Compare with baseline", + "Load test simulations", + "Memory leak detection", + "Bottleneck identification" + ] +} +``` + +
+ +--- + +### Architecture Review Agent + +**Focus:** Evaluate design patterns and architectural decisions + +```bash +# Architecture review +npx ruv-swarm github review-architecture \ + --pr 123 \ + --check "patterns,coupling,cohesion,solid" \ + --visualize-impact \ + --suggest-refactoring +``` + +
+Architecture Analysis + +```javascript +{ + "patterns": [ + "Design pattern adherence", + "SOLID principles", + "DRY violations", + "Separation of concerns", + "Dependency injection", + "Layer violations", + "Circular dependencies" + ], + "metrics": [ + "Coupling metrics", + "Cohesion scores", + "Complexity measures", + "Maintainability index" + ] +} +``` + +
+ +--- + +### Style & Convention Agent + +**Focus:** Enforce coding standards and best practices + +```bash +# Style enforcement with auto-fix +npx ruv-swarm github review-style \ + --pr 123 \ + --check "formatting,naming,docs,tests" \ + --auto-fix "formatting,imports,whitespace" +``` + +
+Style Checks + +```javascript +{ + "checks": [ + "Code formatting", + "Naming conventions", + "Documentation standards", + "Comment quality", + "Test coverage", + "Error handling patterns", + "Logging standards" + ], + "auto-fix": [ + "Formatting issues", + "Import organization", + "Trailing whitespace", + "Simple naming issues" + ] +} +``` + +
+ +--- + +## 🔄 PR-Based Swarm Management + +### Create Swarm from PR + +```bash +# Create swarm from PR description using gh CLI +gh pr view 123 --json body,title,labels,files | npx ruv-swarm swarm create-from-pr + +# Auto-spawn agents based on PR labels +gh pr view 123 --json labels | npx ruv-swarm swarm auto-spawn + +# Create swarm with full PR context +gh pr view 123 --json body,labels,author,assignees | \ + npx ruv-swarm swarm init --from-pr-data +``` + +### Label-Based Agent Assignment + +Map PR labels to specialized agents: + +```json +{ + "label-mapping": { + "bug": ["debugger", "tester"], + "feature": ["architect", "coder", "tester"], + "refactor": ["analyst", "coder"], + "docs": ["researcher", "writer"], + "performance": ["analyst", "optimizer"], + "security": ["security", "authentication", "audit"] + } +} +``` + +### Topology Selection by PR Size + +```bash +# Automatic topology selection based on PR complexity +# Small PR (< 100 lines): ring topology +# Medium PR (100-500 lines): mesh topology +# Large PR (> 500 lines): hierarchical topology +npx ruv-swarm github pr-topology --pr 123 +``` + +--- + +## 🎬 PR Comment Commands + +Execute swarm commands directly from PR comments: + +```markdown + +/swarm init mesh 6 +/swarm spawn coder "Implement authentication" +/swarm spawn tester "Write unit tests" +/swarm status +/swarm review --agents security,performance +``` + +
+Webhook Handler for Comment Commands + +```javascript +// webhook-handler.js +const { createServer } = require('http'); +const { execSync } = require('child_process'); + +createServer((req, res) => { + if (req.url === '/github-webhook') { + const event = JSON.parse(body); + + if (event.action === 'opened' && event.pull_request) { + execSync(`npx ruv-swarm github pr-init ${event.pull_request.number}`); + } + + if (event.comment && event.comment.body.startsWith('/swarm')) { + const command = event.comment.body; + execSync(`npx ruv-swarm github handle-comment --pr ${event.issue.number} --command "${command}"`); + } + + res.writeHead(200); + res.end('OK'); + } +}).listen(3000); +``` + +
+ +--- + +## ⚙️ Review Configuration + +### Configuration File + +```yaml +# .github/review-swarm.yml +version: 1 +review: + auto-trigger: true + required-agents: + - security + - performance + - style + optional-agents: + - architecture + - accessibility + - i18n + + thresholds: + security: block # Block merge on security issues + performance: warn # Warn on performance issues + style: suggest # Suggest style improvements + + rules: + security: + - no-eval + - no-hardcoded-secrets + - proper-auth-checks + - validate-input + performance: + - no-n-plus-one + - efficient-queries + - proper-caching + - optimize-loops + architecture: + - max-coupling: 5 + - min-cohesion: 0.7 + - follow-patterns + - avoid-circular-deps +``` + +### Custom Review Triggers + +```javascript +{ + "triggers": { + "high-risk-files": { + "paths": ["**/auth/**", "**/payment/**", "**/admin/**"], + "agents": ["security", "architecture"], + "depth": "comprehensive", + "require-approval": true + }, + "performance-critical": { + "paths": ["**/api/**", "**/database/**", "**/cache/**"], + "agents": ["performance", "database"], + "benchmarks": true, + "regression-threshold": "5%" + }, + "ui-changes": { + "paths": ["**/components/**", "**/styles/**", "**/pages/**"], + "agents": ["accessibility", "style", "i18n"], + "visual-tests": true, + "responsive-check": true + } + } +} +``` + +--- + +## 🤖 Automated Workflows + +### Auto-Review on PR Creation + +```yaml +# .github/workflows/auto-review.yml +name: Automated Code Review +on: + pull_request: + types: [opened, synchronize] + issue_comment: + types: [created] + +jobs: + swarm-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Setup GitHub CLI + run: echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token + + - name: Run Review Swarm + run: | + # Get PR context with gh CLI + PR_NUM=${{ github.event.pull_request.number }} + PR_DATA=$(gh pr view $PR_NUM --json files,title,body,labels) + PR_DIFF=$(gh pr diff $PR_NUM) + + # Run swarm review + REVIEW_OUTPUT=$(npx ruv-swarm github review-all \ + --pr $PR_NUM \ + --pr-data "$PR_DATA" \ + --diff "$PR_DIFF" \ + --agents "security,performance,style,architecture") + + # Post review results + echo "$REVIEW_OUTPUT" | gh pr review $PR_NUM --comment -F - + + # Update PR status + if echo "$REVIEW_OUTPUT" | grep -q "approved"; then + gh pr review $PR_NUM --approve + elif echo "$REVIEW_OUTPUT" | grep -q "changes-requested"; then + gh pr review $PR_NUM --request-changes -b "See review comments above" + fi + + - name: Update Labels + run: | + # Add labels based on review results + if echo "$REVIEW_OUTPUT" | grep -q "security"; then + gh pr edit $PR_NUM --add-label "security-review" + fi + if echo "$REVIEW_OUTPUT" | grep -q "performance"; then + gh pr edit $PR_NUM --add-label "performance-review" + fi +``` + +--- + +## 💬 Intelligent Comment Generation + +### Generate Contextual Review Comments + +```bash +# Get PR diff with context +PR_DIFF=$(gh pr diff 123 --color never) +PR_FILES=$(gh pr view 123 --json files) + +# Generate review comments +COMMENTS=$(npx ruv-swarm github review-comment \ + --pr 123 \ + --diff "$PR_DIFF" \ + --files "$PR_FILES" \ + --style "constructive" \ + --include-examples \ + --suggest-fixes) + +# Post comments using gh CLI +echo "$COMMENTS" | jq -c '.[]' | while read -r comment; do + FILE=$(echo "$comment" | jq -r '.path') + LINE=$(echo "$comment" | jq -r '.line') + BODY=$(echo "$comment" | jq -r '.body') + COMMIT_ID=$(gh pr view 123 --json headRefOid -q .headRefOid) + + # Create inline review comments + gh api \ + --method POST \ + /repos/:owner/:repo/pulls/123/comments \ + -f path="$FILE" \ + -f line="$LINE" \ + -f body="$BODY" \ + -f commit_id="$COMMIT_ID" +done +``` + +### Batch Comment Management + +```bash +# Manage review comments efficiently +npx ruv-swarm github review-comments \ + --pr 123 \ + --group-by "agent,severity" \ + --summarize \ + --resolve-outdated +``` + +--- + +## 🚪 Quality Gates & Checks + +### Status Checks + +```yaml +# Required status checks in branch protection +protection_rules: + required_status_checks: + strict: true + contexts: + - "review-swarm/security" + - "review-swarm/performance" + - "review-swarm/architecture" + - "review-swarm/tests" +``` + +### Define Quality Gates + +```bash +# Set quality gate thresholds +npx ruv-swarm github quality-gates \ + --define '{ + "security": {"threshold": "no-critical"}, + "performance": {"regression": "<5%"}, + "coverage": {"minimum": "80%"}, + "architecture": {"complexity": "<10"}, + "duplication": {"maximum": "5%"} + }' +``` + +### Track Review Metrics + +```bash +# Monitor review effectiveness +npx ruv-swarm github review-metrics \ + --period 30d \ + --metrics "issues-found,false-positives,fix-rate,time-to-review" \ + --export-dashboard \ + --format json +``` + +--- + +## 🎓 Advanced Features + +### Context-Aware Reviews + +Analyze PRs with full project context: + +```bash +# Review with comprehensive context +npx ruv-swarm github review-context \ + --pr 123 \ + --load-related-prs \ + --analyze-impact \ + --check-breaking-changes \ + --dependency-analysis +``` + +### Learning from History + +Train review agents on your codebase patterns: + +```bash +# Learn from past reviews +npx ruv-swarm github review-learn \ + --analyze-past-reviews \ + --identify-patterns \ + --improve-suggestions \ + --reduce-false-positives + +# Train on your codebase +npx ruv-swarm github review-train \ + --learn-patterns \ + --adapt-to-style \ + --improve-accuracy +``` + +### Cross-PR Analysis + +Coordinate reviews across related pull requests: + +```bash +# Analyze related PRs together +npx ruv-swarm github review-batch \ + --prs "123,124,125" \ + --check-consistency \ + --verify-integration \ + --combined-impact +``` + +### Multi-PR Swarm Coordination + +```bash +# Coordinate swarms across related PRs +npx ruv-swarm github multi-pr \ + --prs "123,124,125" \ + --strategy "parallel" \ + --share-memory +``` + +--- + +## 🛠️ Custom Review Agents + +### Create Custom Agent + +```javascript +// custom-review-agent.js +class CustomReviewAgent { + constructor(config) { + this.config = config; + this.rules = config.rules || []; + } + + async review(pr) { + const issues = []; + + // Custom logic: Check for TODO comments in production code + if (await this.checkTodoComments(pr)) { + issues.push({ + severity: 'warning', + file: pr.file, + line: pr.line, + message: 'TODO comment found in production code', + suggestion: 'Resolve TODO or create issue to track it' + }); + } + + // Custom logic: Verify API versioning + if (await this.checkApiVersioning(pr)) { + issues.push({ + severity: 'error', + file: pr.file, + line: pr.line, + message: 'API endpoint missing versioning', + suggestion: 'Add /v1/, /v2/ prefix to API routes' + }); + } + + return issues; + } + + async checkTodoComments(pr) { + // Implementation + const todoRegex = /\/\/\s*TODO|\/\*\s*TODO/gi; + return todoRegex.test(pr.diff); + } + + async checkApiVersioning(pr) { + // Implementation + const apiRegex = /app\.(get|post|put|delete)\(['"]\/api\/(?!v\d+)/; + return apiRegex.test(pr.diff); + } +} + +module.exports = CustomReviewAgent; +``` + +### Register Custom Agent + +```bash +# Register custom review agent +npx ruv-swarm github register-agent \ + --name "custom-reviewer" \ + --file "./custom-review-agent.js" \ + --category "standards" +``` + +--- + +## 🔧 CI/CD Integration + +### Integration with Build Pipeline + +```yaml +# .github/workflows/build-and-review.yml +name: Build and Review +on: [pull_request] + +jobs: + build-and-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - run: npm install + - run: npm test + - run: npm run build + + swarm-review: + needs: build-and-test + runs-on: ubuntu-latest + steps: + - name: Run Swarm Review + run: | + npx ruv-swarm github review-all \ + --pr ${{ github.event.pull_request.number }} \ + --include-build-results +``` + +### Automated PR Fixes + +```bash +# Auto-fix common issues +npx ruv-swarm github pr-fix 123 \ + --issues "lint,test-failures,formatting" \ + --commit-fixes \ + --push-changes +``` + +### Progress Updates to PR + +```bash +# Post swarm progress to PR using gh CLI +PROGRESS=$(npx ruv-swarm github pr-progress 123 --format markdown) + +gh pr comment 123 --body "$PROGRESS" + +# Update PR labels based on progress +if [[ $(echo "$PROGRESS" | grep -o '[0-9]\+%' | sed 's/%//') -gt 90 ]]; then + gh pr edit 123 --add-label "ready-for-review" +fi +``` + +--- + +## 📋 Complete Workflow Examples + +### Example 1: Security-Critical PR + +```bash +# Review authentication system changes +npx ruv-swarm github review-init \ + --pr 456 \ + --agents "security,authentication,audit" \ + --depth "maximum" \ + --require-security-approval \ + --penetration-test +``` + +### Example 2: Performance-Sensitive PR + +```bash +# Review database optimization +npx ruv-swarm github review-init \ + --pr 789 \ + --agents "performance,database,caching" \ + --benchmark \ + --profile \ + --load-test +``` + +### Example 3: UI Component PR + +```bash +# Review new component library +npx ruv-swarm github review-init \ + --pr 321 \ + --agents "accessibility,style,i18n,docs" \ + --visual-regression \ + --component-tests \ + --responsive-check +``` + +### Example 4: Feature Development PR + +```bash +# Review new feature implementation +gh pr view 456 --json body,labels,files | \ + npx ruv-swarm github pr-init 456 \ + --topology hierarchical \ + --agents "architect,coder,tester,security" \ + --auto-assign-tasks +``` + +### Example 5: Bug Fix PR + +```bash +# Review bug fix with debugging focus +npx ruv-swarm github pr-init 789 \ + --topology mesh \ + --agents "debugger,analyst,tester" \ + --priority high \ + --regression-test +``` + +--- + +## 📊 Monitoring & Analytics + +### Review Dashboard + +```bash +# Launch real-time review dashboard +npx ruv-swarm github review-dashboard \ + --real-time \ + --show "agent-activity,issue-trends,fix-rates,coverage" +``` + +### Generate Review Reports + +```bash +# Create comprehensive review report +npx ruv-swarm github review-report \ + --format "markdown" \ + --include "summary,details,trends,recommendations" \ + --email-stakeholders \ + --export-pdf +``` + +### PR Swarm Analytics + +```bash +# Generate PR-specific analytics +npx ruv-swarm github pr-report 123 \ + --metrics "completion-time,agent-efficiency,token-usage,issue-density" \ + --format markdown \ + --compare-baseline +``` + +### Export to GitHub Insights + +```bash +# Export metrics to GitHub Insights +npx ruv-swarm github export-metrics \ + --pr 123 \ + --to-insights \ + --dashboard-url +``` + +--- + +## 🔐 Security Considerations + +### Best Practices + +1. **Token Permissions**: Ensure GitHub tokens have minimal required scopes +2. **Command Validation**: Validate all PR comments before execution +3. **Rate Limiting**: Implement rate limits for PR operations +4. **Audit Trail**: Log all swarm operations for compliance +5. **Secret Management**: Never expose API keys in PR comments or logs + +### Security Checklist + +- [ ] GitHub token scoped to repository only +- [ ] Webhook signatures verified +- [ ] Command injection protection enabled +- [ ] Rate limiting configured +- [ ] Audit logging enabled +- [ ] Secrets scanning active +- [ ] Branch protection rules enforced + +--- + +## 📚 Best Practices + +### 1. Review Configuration +- ✅ Define clear review criteria upfront +- ✅ Set appropriate severity thresholds +- ✅ Configure agent specializations for your stack +- ✅ Establish override procedures for emergencies + +### 2. Comment Quality +- ✅ Provide actionable, specific feedback +- ✅ Include code examples with suggestions +- ✅ Reference documentation and best practices +- ✅ Maintain respectful, constructive tone + +### 3. Performance Optimization +- ✅ Cache analysis results to avoid redundant work +- ✅ Use incremental reviews for large PRs +- ✅ Enable parallel agent execution +- ✅ Batch comment operations efficiently + +### 4. PR Templates + +```markdown + +## Swarm Configuration +- Topology: [mesh/hierarchical/ring/star] +- Max Agents: [number] +- Auto-spawn: [yes/no] +- Priority: [high/medium/low] + +## Tasks for Swarm +- [ ] Task 1 description +- [ ] Task 2 description +- [ ] Task 3 description + +## Review Focus Areas +- [ ] Security review +- [ ] Performance analysis +- [ ] Architecture validation +- [ ] Accessibility check +``` + +### 5. Auto-Merge When Ready + +```bash +# Auto-merge when swarm completes and passes checks +SWARM_STATUS=$(npx ruv-swarm github pr-status 123) + +if [[ "$SWARM_STATUS" == "complete" ]]; then + # Check review requirements + REVIEWS=$(gh pr view 123 --json reviews --jq '.reviews | length') + + if [[ $REVIEWS -ge 2 ]]; then + # Enable auto-merge + gh pr merge 123 --auto --squash + fi +fi +``` + +--- + +## 🔗 Integration with Codex + +### Workflow Pattern + +1. **Codex** reads PR diff and context +2. **Swarm** coordinates review approach based on PR type +3. **Agents** work in parallel on different review aspects +4. **Progress** updates posted to PR automatically +5. **Final review** performed before marking ready + +### Example: Complete PR Management + +```javascript +[Single Message - Parallel Execution]: + // Initialize coordination + mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 5 } + mcp__claude-flow__agent_spawn { type: "reviewer", name: "Senior Reviewer" } + mcp__claude-flow__agent_spawn { type: "tester", name: "QA Engineer" } + mcp__claude-flow__agent_spawn { type: "coordinator", name: "Merge Coordinator" } + + // Create and manage PR using gh CLI + Bash("gh pr create --title 'Feature: Add authentication' --base main") + Bash("gh pr view 54 --json files,diff") + Bash("gh pr review 54 --approve --body 'LGTM after automated review'") + + // Execute tests and validation + Bash("npm test") + Bash("npm run lint") + Bash("npm run build") + + // Track progress + TodoWrite { todos: [ + { content: "Complete code review", status: "completed", activeForm: "Completing code review" }, + { content: "Run test suite", status: "completed", activeForm: "Running test suite" }, + { content: "Validate security", status: "completed", activeForm: "Validating security" }, + { content: "Merge when ready", status: "pending", activeForm: "Merging when ready" } + ]} +``` + +--- + +## 🆘 Troubleshooting + +### Common Issues + +
+Issue: Review agents not spawning + +**Solution:** +```bash +# Check swarm status +npx ruv-swarm swarm-status + +# Verify GitHub CLI authentication +gh auth status + +# Re-initialize swarm +npx ruv-swarm github review-init --pr 123 --force +``` + +
+ +
+Issue: Comments not posting to PR + +**Solution:** +```bash +# Verify GitHub token permissions +gh auth status + +# Check API rate limits +gh api rate_limit + +# Use batch comment posting +npx ruv-swarm github review-comments --pr 123 --batch +``` + +
+ +
+Issue: Review taking too long + +**Solution:** +```bash +# Use incremental review for large PRs +npx ruv-swarm github review-init --pr 123 --incremental + +# Reduce agent count +npx ruv-swarm github review-init --pr 123 --agents "security,style" --max-agents 3 + +# Enable parallel processing +npx ruv-swarm github review-init --pr 123 --parallel --cache-results +``` + +
+ +--- + +## 📖 Additional Resources + +### Related Skills +- `github-pr-manager` - Comprehensive PR lifecycle management +- `github-workflow-automation` - Automate GitHub workflows +- `swarm-coordination` - Advanced swarm orchestration + +### Documentation +- [GitHub CLI Documentation](https://cli.github.com/manual/) +- [RUV Swarm Guide](https://github.com/ruvnet/ruv-swarm) +- [Codex Flow Integration](https://github.com/ruvnet/Codex-flow) + +### Support +- GitHub Issues: Report bugs and request features +- Community: Join discussions and share experiences +- Examples: Browse example configurations and workflows + +--- + +## 📄 License + +This skill is part of the Codex Flow project and is licensed under the MIT License. + +--- + +**Last Updated:** 2025-10-19 +**Version:** 1.0.0 +**Maintainer:** Codex Flow Team diff --git a/.agents/skills/github-multi-repo/SKILL.md b/.agents/skills/github-multi-repo/SKILL.md new file mode 100644 index 0000000..7df526a --- /dev/null +++ b/.agents/skills/github-multi-repo/SKILL.md @@ -0,0 +1,874 @@ +--- +name: github-multi-repo +version: 1.0.0 +description: Multi-repository coordination, synchronization, and architecture management with AI swarm orchestration +category: github-integration +tags: [multi-repo, synchronization, architecture, coordination, github] +author: Codex Flow Team +requires: + - ruv-swarm@^1.0.11 + - gh-cli@^2.0.0 +capabilities: + - cross-repository coordination + - package synchronization + - architecture optimization + - template management + - distributed workflows +--- + +# GitHub Multi-Repository Coordination Skill + +## Overview + +Advanced multi-repository coordination system that combines swarm intelligence, package synchronization, and repository architecture optimization. This skill enables organization-wide automation, cross-project collaboration, and scalable repository management. + +## Core Capabilities + +### 🔄 Multi-Repository Swarm Coordination +Cross-repository AI swarm orchestration for distributed development workflows. + +### 📦 Package Synchronization +Intelligent dependency resolution and version alignment across multiple packages. + +### 🏗️ Repository Architecture +Structure optimization and template management for scalable projects. + +### 🔗 Integration Management +Cross-package integration testing and deployment coordination. + +## Quick Start + +### Initialize Multi-Repo Coordination +```bash +# Basic swarm initialization +npx Codex-flow skill run github-multi-repo init \ + --repos "org/frontend,org/backend,org/shared" \ + --topology hierarchical + +# Advanced initialization with synchronization +npx Codex-flow skill run github-multi-repo init \ + --repos "org/frontend,org/backend,org/shared" \ + --topology mesh \ + --shared-memory \ + --sync-strategy eventual +``` + +### Synchronize Packages +```bash +# Synchronize package versions and dependencies +npx Codex-flow skill run github-multi-repo sync \ + --packages "Codex-flow,ruv-swarm" \ + --align-versions \ + --update-docs +``` + +### Optimize Architecture +```bash +# Analyze and optimize repository structure +npx Codex-flow skill run github-multi-repo optimize \ + --analyze-structure \ + --suggest-improvements \ + --create-templates +``` + +## Features + +### 1. Cross-Repository Swarm Orchestration + +#### Repository Discovery +```javascript +// Auto-discover related repositories with gh CLI +const REPOS = Bash(`gh repo list my-organization --limit 100 \ + --json name,description,languages,topics \ + --jq '.[] | select(.languages | keys | contains(["TypeScript"]))'`) + +// Analyze repository dependencies +const DEPS = Bash(`gh repo list my-organization --json name | \ + jq -r '.[].name' | while read -r repo; do + gh api repos/my-organization/$repo/contents/package.json \ + --jq '.content' 2>/dev/null | base64 -d | jq '{name, dependencies}' + done | jq -s '.'`) + +// Initialize swarm with discovered repositories +mcp__claude-flow__swarm_init({ + topology: "hierarchical", + maxAgents: 8, + metadata: { repos: REPOS, dependencies: DEPS } +}) +``` + +#### Synchronized Operations +```javascript +// Execute synchronized changes across repositories +[Parallel Multi-Repo Operations]: + // Spawn coordination agents + Task("Repository Coordinator", "Coordinate changes across all repositories", "coordinator") + Task("Dependency Analyzer", "Analyze cross-repo dependencies", "analyst") + Task("Integration Tester", "Validate cross-repo changes", "tester") + + // Get matching repositories + Bash(`gh repo list org --limit 100 --json name \ + --jq '.[] | select(.name | test("-service$")) | .name' > /tmp/repos.txt`) + + // Execute task across repositories + Bash(`cat /tmp/repos.txt | while read -r repo; do + gh repo clone org/$repo /tmp/$repo -- --depth=1 + cd /tmp/$repo + + # Apply changes + npm update + npm test + + # Create PR if successful + if [ $? -eq 0 ]; then + git checkout -b update-dependencies-$(date +%Y%m%d) + git add -A + git commit -m "chore: Update dependencies" + git push origin HEAD + gh pr create --title "Update dependencies" --body "Automated update" --label "dependencies" + fi + done`) + + // Track all operations + TodoWrite { todos: [ + { id: "discover", content: "Discover all service repositories", status: "completed" }, + { id: "update", content: "Update dependencies", status: "completed" }, + { id: "test", content: "Run integration tests", status: "in_progress" }, + { id: "pr", content: "Create pull requests", status: "pending" } + ]} +``` + +### 2. Package Synchronization + +#### Version Alignment +```javascript +// Synchronize package dependencies and versions +[Complete Package Sync]: + // Initialize sync swarm + mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 5 }) + + // Spawn sync agents + Task("Sync Coordinator", "Coordinate version alignment", "coordinator") + Task("Dependency Analyzer", "Analyze dependencies", "analyst") + Task("Integration Tester", "Validate synchronization", "tester") + + // Read package states + Read("/workspaces/ruv-FANN/Codex-flow/Codex-flow/package.json") + Read("/workspaces/ruv-FANN/ruv-swarm/npm/package.json") + + // Align versions using gh CLI + Bash(`gh api repos/:owner/:repo/git/refs \ + -f ref='refs/heads/sync/package-alignment' \ + -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')`) + + // Update package.json files + Bash(`gh api repos/:owner/:repo/contents/package.json \ + --method PUT \ + -f message="feat: Align Node.js version requirements" \ + -f branch="sync/package-alignment" \ + -f content="$(cat aligned-package.json | base64)"`) + + // Store sync state + mcp__claude-flow__memory_usage({ + action: "store", + key: "sync/packages/status", + value: { + timestamp: Date.now(), + packages_synced: ["Codex-flow", "ruv-swarm"], + status: "synchronized" + } + }) +``` + +#### Documentation Synchronization +```javascript +// Synchronize AGENTS.md files across packages +[Documentation Sync]: + // Get source documentation + Bash(`gh api repos/:owner/:repo/contents/ruv-swarm/docs/AGENTS.md \ + --jq '.content' | base64 -d > /tmp/Codex-source.md`) + + // Update target documentation + Bash(`gh api repos/:owner/:repo/contents/Codex-flow/AGENTS.md \ + --method PUT \ + -f message="docs: Synchronize AGENTS.md" \ + -f branch="sync/documentation" \ + -f content="$(cat /tmp/Codex-source.md | base64)"`) + + // Track sync status + mcp__claude-flow__memory_usage({ + action: "store", + key: "sync/documentation/status", + value: { status: "synchronized", files: ["AGENTS.md"] } + }) +``` + +#### Cross-Package Integration +```javascript +// Coordinate feature implementation across packages +[Cross-Package Feature]: + // Push changes to all packages + mcp__github__push_files({ + branch: "feature/github-integration", + files: [ + { + path: "Codex-flow/.Codex/commands/github/github-modes.md", + content: "[GitHub modes documentation]" + }, + { + path: "ruv-swarm/src/github-coordinator/hooks.js", + content: "[GitHub coordination hooks]" + } + ], + message: "feat: Add GitHub workflow integration" + }) + + // Create coordinated PR + Bash(`gh pr create \ + --title "Feature: GitHub Workflow Integration" \ + --body "## 🚀 GitHub Integration + +### Features +- ✅ Multi-repo coordination +- ✅ Package synchronization +- ✅ Architecture optimization + +### Testing +- [x] Package dependency verification +- [x] Integration tests +- [x] Cross-package compatibility"`) +``` + +### 3. Repository Architecture + +#### Structure Analysis +```javascript +// Analyze and optimize repository structure +[Architecture Analysis]: + // Initialize architecture swarm + mcp__claude-flow__swarm_init({ topology: "hierarchical", maxAgents: 6 }) + + // Spawn architecture agents + Task("Senior Architect", "Analyze repository structure", "architect") + Task("Structure Analyst", "Identify optimization opportunities", "analyst") + Task("Performance Optimizer", "Optimize structure for scalability", "optimizer") + Task("Best Practices Researcher", "Research architecture patterns", "researcher") + + // Analyze current structures + LS("/workspaces/ruv-FANN/Codex-flow/Codex-flow") + LS("/workspaces/ruv-FANN/ruv-swarm/npm") + + // Search for best practices + Bash(`gh search repos "language:javascript template architecture" \ + --limit 10 \ + --json fullName,description,stargazersCount \ + --sort stars \ + --order desc`) + + // Store analysis results + mcp__claude-flow__memory_usage({ + action: "store", + key: "architecture/analysis/results", + value: { + repositories_analyzed: ["Codex-flow", "ruv-swarm"], + optimization_areas: ["structure", "workflows", "templates"], + recommendations: ["standardize_structure", "improve_workflows"] + } + }) +``` + +#### Template Creation +```javascript +// Create standardized repository template +[Template Creation]: + // Create template repository + mcp__github__create_repository({ + name: "Codex-project-template", + description: "Standardized template for Codex projects", + private: false, + autoInit: true + }) + + // Push template structure + mcp__github__push_files({ + repo: "Codex-project-template", + files: [ + { + path: ".Codex/commands/github/github-modes.md", + content: "[GitHub modes template]" + }, + { + path: ".Codex/config.json", + content: JSON.stringify({ + version: "1.0", + mcp_servers: { + "ruv-swarm": { + command: "npx", + args: ["ruv-swarm", "mcp", "start"] + } + } + }) + }, + { + path: "AGENTS.md", + content: "[Standardized AGENTS.md]" + }, + { + path: "package.json", + content: JSON.stringify({ + name: "Codex-project-template", + engines: { node: ">=20.0.0" }, + dependencies: { "ruv-swarm": "^1.0.11" } + }) + } + ], + message: "feat: Create standardized template" + }) +``` + +#### Cross-Repository Standardization +```javascript +// Synchronize structure across repositories +[Structure Standardization]: + const repositories = ["Codex-flow", "ruv-swarm", "Codex-extensions"] + + // Update common files across all repositories + repositories.forEach(repo => { + mcp__github__create_or_update_file({ + repo: "ruv-FANN", + path: `${repo}/.github/workflows/integration.yml`, + content: `name: Integration Tests +on: [push, pull_request] +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: { node-version: '20' } + - run: npm install && npm test`, + message: "ci: Standardize integration workflow", + branch: "structure/standardization" + }) + }) +``` + +### 4. Orchestration Workflows + +#### Dependency Management +```javascript +// Update dependencies across all repositories +[Organization-Wide Dependency Update]: + // Create tracking issue + TRACKING_ISSUE=$(Bash(`gh issue create \ + --title "Dependency Update: typescript@5.0.0" \ + --body "Tracking TypeScript update across all repositories" \ + --label "dependencies,tracking" \ + --json number -q .number`)) + + // Find all TypeScript repositories + TS_REPOS=$(Bash(`gh repo list org --limit 100 --json name | \ + jq -r '.[].name' | while read -r repo; do + if gh api repos/org/$repo/contents/package.json 2>/dev/null | \ + jq -r '.content' | base64 -d | grep -q '"typescript"'; then + echo "$repo" + fi + done`)) + + // Update each repository + Bash(`echo "$TS_REPOS" | while read -r repo; do + gh repo clone org/$repo /tmp/$repo -- --depth=1 + cd /tmp/$repo + + npm install --save-dev typescript@5.0.0 + + if npm test; then + git checkout -b update-typescript-5 + git add package.json package-lock.json + git commit -m "chore: Update TypeScript to 5.0.0 + +Part of #$TRACKING_ISSUE" + + git push origin HEAD + gh pr create \ + --title "Update TypeScript to 5.0.0" \ + --body "Updates TypeScript\n\nTracking: #$TRACKING_ISSUE" \ + --label "dependencies" + else + gh issue comment $TRACKING_ISSUE \ + --body "❌ Failed to update $repo - tests failing" + fi + done`) +``` + +#### Refactoring Operations +```javascript +// Coordinate large-scale refactoring +[Cross-Repo Refactoring]: + // Initialize refactoring swarm + mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 8 }) + + // Spawn specialized agents + Task("Refactoring Coordinator", "Coordinate refactoring across repos", "coordinator") + Task("Impact Analyzer", "Analyze refactoring impact", "analyst") + Task("Code Transformer", "Apply refactoring changes", "coder") + Task("Migration Guide Creator", "Create migration documentation", "documenter") + Task("Integration Tester", "Validate refactored code", "tester") + + // Execute refactoring + mcp__claude-flow__task_orchestrate({ + task: "Rename OldAPI to NewAPI across all repositories", + strategy: "sequential", + priority: "high" + }) +``` + +#### Security Updates +```javascript +// Coordinate security patches +[Security Patch Deployment]: + // Scan all repositories + Bash(`gh repo list org --limit 100 --json name | jq -r '.[].name' | \ + while read -r repo; do + gh repo clone org/$repo /tmp/$repo -- --depth=1 + cd /tmp/$repo + npm audit --json > /tmp/audit-$repo.json + done`) + + // Apply patches + Bash(`for repo in /tmp/audit-*.json; do + if [ $(jq '.vulnerabilities | length' $repo) -gt 0 ]; then + cd /tmp/$(basename $repo .json | sed 's/audit-//') + npm audit fix + + if npm test; then + git checkout -b security/patch-$(date +%Y%m%d) + git add -A + git commit -m "security: Apply security patches" + git push origin HEAD + gh pr create --title "Security patches" --label "security" + fi + fi + done`) +``` + +## Configuration + +### Multi-Repo Config File +```yaml +# .swarm/multi-repo.yml +version: 1 +organization: my-org + +repositories: + - name: frontend + url: github.com/my-org/frontend + role: ui + agents: [coder, designer, tester] + + - name: backend + url: github.com/my-org/backend + role: api + agents: [architect, coder, tester] + + - name: shared + url: github.com/my-org/shared + role: library + agents: [analyst, coder] + +coordination: + topology: hierarchical + communication: webhook + memory: redis://shared-memory + +dependencies: + - from: frontend + to: [backend, shared] + - from: backend + to: [shared] +``` + +### Repository Roles +```javascript +{ + "roles": { + "ui": { + "responsibilities": ["user-interface", "ux", "accessibility"], + "default-agents": ["designer", "coder", "tester"] + }, + "api": { + "responsibilities": ["endpoints", "business-logic", "data"], + "default-agents": ["architect", "coder", "security"] + }, + "library": { + "responsibilities": ["shared-code", "utilities", "types"], + "default-agents": ["analyst", "coder", "documenter"] + } + } +} +``` + +## Communication Strategies + +### 1. Webhook-Based Coordination +```javascript +const { MultiRepoSwarm } = require('ruv-swarm'); + +const swarm = new MultiRepoSwarm({ + webhook: { + url: 'https://swarm-coordinator.example.com', + secret: process.env.WEBHOOK_SECRET + } +}); + +swarm.on('repo:update', async (event) => { + await swarm.propagate(event, { + to: event.dependencies, + strategy: 'eventual-consistency' + }); +}); +``` + +### 2. Event Streaming +```yaml +# Kafka configuration for real-time coordination +kafka: + brokers: ['kafka1:9092', 'kafka2:9092'] + topics: + swarm-events: + partitions: 10 + replication: 3 + swarm-memory: + partitions: 5 + replication: 3 +``` + +## Synchronization Patterns + +### 1. Eventually Consistent +```javascript +{ + "sync": { + "strategy": "eventual", + "max-lag": "5m", + "retry": { + "attempts": 3, + "backoff": "exponential" + } + } +} +``` + +### 2. Strong Consistency +```javascript +{ + "sync": { + "strategy": "strong", + "consensus": "raft", + "quorum": 0.51, + "timeout": "30s" + } +} +``` + +### 3. Hybrid Approach +```javascript +{ + "sync": { + "default": "eventual", + "overrides": { + "security-updates": "strong", + "dependency-updates": "strong", + "documentation": "eventual" + } + } +} +``` + +## Use Cases + +### 1. Microservices Coordination +```bash +npx Codex-flow skill run github-multi-repo microservices \ + --services "auth,users,orders,payments" \ + --ensure-compatibility \ + --sync-contracts \ + --integration-tests +``` + +### 2. Library Updates +```bash +npx Codex-flow skill run github-multi-repo lib-update \ + --library "org/shared-lib" \ + --version "2.0.0" \ + --find-consumers \ + --update-imports \ + --run-tests +``` + +### 3. Organization-Wide Changes +```bash +npx Codex-flow skill run github-multi-repo org-policy \ + --policy "add-security-headers" \ + --repos "org/*" \ + --validate-compliance \ + --create-reports +``` + +## Architecture Patterns + +### Monorepo Structure +``` +ruv-FANN/ +├── packages/ +│ ├── Codex-flow/ +│ │ ├── src/ +│ │ ├── .Codex/ +│ │ └── package.json +│ ├── ruv-swarm/ +│ │ ├── src/ +│ │ ├── wasm/ +│ │ └── package.json +│ └── shared/ +│ ├── types/ +│ ├── utils/ +│ └── config/ +├── tools/ +│ ├── build/ +│ ├── test/ +│ └── deploy/ +├── docs/ +│ ├── architecture/ +│ ├── integration/ +│ └── examples/ +└── .github/ + ├── workflows/ + ├── templates/ + └── actions/ +``` + +### Command Structure +``` +.Codex/ +├── commands/ +│ ├── github/ +│ │ ├── github-modes.md +│ │ ├── pr-manager.md +│ │ ├── issue-tracker.md +│ │ └── sync-coordinator.md +│ ├── sparc/ +│ │ ├── sparc-modes.md +│ │ ├── coder.md +│ │ └── tester.md +│ └── swarm/ +│ ├── coordination.md +│ └── orchestration.md +├── templates/ +│ ├── issue.md +│ ├── pr.md +│ └── project.md +└── config.json +``` + +## Monitoring & Visualization + +### Multi-Repo Dashboard +```bash +npx Codex-flow skill run github-multi-repo dashboard \ + --port 3000 \ + --metrics "agent-activity,task-progress,memory-usage" \ + --real-time +``` + +### Dependency Graph +```bash +npx Codex-flow skill run github-multi-repo dep-graph \ + --format mermaid \ + --include-agents \ + --show-data-flow +``` + +### Health Monitoring +```bash +npx Codex-flow skill run github-multi-repo health-check \ + --repos "org/*" \ + --check "connectivity,memory,agents" \ + --alert-on-issues +``` + +## Best Practices + +### 1. Repository Organization +- Clear repository roles and boundaries +- Consistent naming conventions +- Documented dependencies +- Shared configuration standards + +### 2. Communication +- Use appropriate sync strategies +- Implement circuit breakers +- Monitor latency and failures +- Clear error propagation + +### 3. Security +- Secure cross-repo authentication +- Encrypted communication channels +- Audit trail for all operations +- Principle of least privilege + +### 4. Version Management +- Semantic versioning alignment +- Dependency compatibility validation +- Automated version bump coordination + +### 5. Testing Integration +- Cross-package test validation +- Integration test automation +- Performance regression detection + +## Performance Optimization + +### Caching Strategy +```bash +npx Codex-flow skill run github-multi-repo cache-strategy \ + --analyze-patterns \ + --suggest-cache-layers \ + --implement-invalidation +``` + +### Parallel Execution +```bash +npx Codex-flow skill run github-multi-repo parallel-optimize \ + --analyze-dependencies \ + --identify-parallelizable \ + --execute-optimal +``` + +### Resource Pooling +```bash +npx Codex-flow skill run github-multi-repo resource-pool \ + --share-agents \ + --distribute-load \ + --monitor-usage +``` + +## Troubleshooting + +### Connectivity Issues +```bash +npx Codex-flow skill run github-multi-repo diagnose-connectivity \ + --test-all-repos \ + --check-permissions \ + --verify-webhooks +``` + +### Memory Synchronization +```bash +npx Codex-flow skill run github-multi-repo debug-memory \ + --check-consistency \ + --identify-conflicts \ + --repair-state +``` + +### Performance Bottlenecks +```bash +npx Codex-flow skill run github-multi-repo perf-analysis \ + --profile-operations \ + --identify-bottlenecks \ + --suggest-optimizations +``` + +## Advanced Features + +### 1. Distributed Task Queue +```bash +npx Codex-flow skill run github-multi-repo queue \ + --backend redis \ + --workers 10 \ + --priority-routing \ + --dead-letter-queue +``` + +### 2. Cross-Repo Testing +```bash +npx Codex-flow skill run github-multi-repo test \ + --setup-test-env \ + --link-services \ + --run-e2e \ + --tear-down +``` + +### 3. Monorepo Migration +```bash +npx Codex-flow skill run github-multi-repo to-monorepo \ + --analyze-repos \ + --suggest-structure \ + --preserve-history \ + --create-migration-prs +``` + +## Examples + +### Full-Stack Application Update +```bash +npx Codex-flow skill run github-multi-repo fullstack-update \ + --frontend "org/web-app" \ + --backend "org/api-server" \ + --database "org/db-migrations" \ + --coordinate-deployment +``` + +### Cross-Team Collaboration +```bash +npx Codex-flow skill run github-multi-repo cross-team \ + --teams "frontend,backend,devops" \ + --task "implement-feature-x" \ + --assign-by-expertise \ + --track-progress +``` + +## Metrics and Reporting + +### Sync Quality Metrics +- Package version alignment percentage +- Documentation consistency score +- Integration test success rate +- Synchronization completion time + +### Architecture Health Metrics +- Repository structure consistency score +- Documentation coverage percentage +- Cross-repository integration success rate +- Template adoption and usage statistics + +### Automated Reporting +- Weekly sync status reports +- Dependency drift detection +- Documentation divergence alerts +- Integration health monitoring + +## Integration Points + +### Related Skills +- `github-workflow` - GitHub workflow automation +- `github-pr` - Pull request management +- `sparc-architect` - Architecture design +- `sparc-optimizer` - Performance optimization + +### Related Commands +- `/github sync-coordinator` - Cross-repo synchronization +- `/github release-manager` - Coordinated releases +- `/github repo-architect` - Repository optimization +- `/sparc architect` - Detailed architecture design + +## Support and Resources + +- Documentation: https://github.com/ruvnet/Codex-flow +- Issues: https://github.com/ruvnet/Codex-flow/issues +- Examples: `.Codex/examples/github-multi-repo/` + +--- + +**Version:** 1.0.0 +**Last Updated:** 2025-10-19 +**Maintainer:** Codex Flow Team diff --git a/.agents/skills/github-project-management/SKILL.md b/.agents/skills/github-project-management/SKILL.md new file mode 100644 index 0000000..1ea768d --- /dev/null +++ b/.agents/skills/github-project-management/SKILL.md @@ -0,0 +1,1277 @@ +--- +name: github-project-management +title: GitHub Project Management +version: 2.0.0 +category: github +description: Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning +author: Codex +tags: + - github + - project-management + - issue-tracking + - project-boards + - sprint-planning + - agile + - swarm-coordination +difficulty: intermediate +prerequisites: + - GitHub CLI (gh) installed and authenticated + - ruv-swarm or Codex-flow MCP server configured + - Repository access permissions +tools_required: + - mcp__github__* + - mcp__claude-flow__* + - Bash + - Read + - Write + - TodoWrite +related_skills: + - github-pr-workflow + - github-release-management + - sparc-orchestrator +estimated_time: 30-45 minutes +--- + +# GitHub Project Management + +## Overview + +A comprehensive skill for managing GitHub projects using AI swarm coordination. This skill combines intelligent issue management, automated project board synchronization, and swarm-based coordination for efficient project delivery. + +## Quick Start + +### Basic Issue Creation with Swarm Coordination + +```bash +# Create a coordinated issue +gh issue create \ + --title "Feature: Advanced Authentication" \ + --body "Implement OAuth2 with social login..." \ + --label "enhancement,swarm-ready" + +# Initialize swarm for issue +npx Codex-flow@alpha hooks pre-task --description "Feature implementation" +``` + +### Project Board Quick Setup + +```bash +# Get project ID +PROJECT_ID=$(gh project list --owner @me --format json | \ + jq -r '.projects[0].id') + +# Initialize board sync +npx ruv-swarm github board-init \ + --project-id "$PROJECT_ID" \ + --sync-mode "bidirectional" +``` + +--- + +## Core Capabilities + +### 1. Issue Management & Triage + +
+Automated Issue Creation + +#### Single Issue with Swarm Coordination + +```javascript +// Initialize issue management swarm +mcp__claude-flow__swarm_init { topology: "star", maxAgents: 3 } +mcp__claude-flow__agent_spawn { type: "coordinator", name: "Issue Coordinator" } +mcp__claude-flow__agent_spawn { type: "researcher", name: "Requirements Analyst" } +mcp__claude-flow__agent_spawn { type: "coder", name: "Implementation Planner" } + +// Create comprehensive issue +mcp__github__create_issue { + owner: "org", + repo: "repository", + title: "Integration Review: Complete system integration", + body: `## 🔄 Integration Review + + ### Overview + Comprehensive review and integration between components. + + ### Objectives + - [ ] Verify dependencies and imports + - [ ] Ensure API integration + - [ ] Check hook system integration + - [ ] Validate data systems alignment + + ### Swarm Coordination + This issue will be managed by coordinated swarm agents for optimal progress tracking.`, + labels: ["integration", "review", "enhancement"], + assignees: ["username"] +} + +// Set up automated tracking +mcp__claude-flow__task_orchestrate { + task: "Monitor and coordinate issue progress with automated updates", + strategy: "adaptive", + priority: "medium" +} +``` + +#### Batch Issue Creation + +```bash +# Create multiple related issues using gh CLI +gh issue create \ + --title "Feature: Advanced GitHub Integration" \ + --body "Implement comprehensive GitHub workflow automation..." \ + --label "feature,github,high-priority" + +gh issue create \ + --title "Bug: Merge conflicts in integration branch" \ + --body "Resolve merge conflicts..." \ + --label "bug,integration,urgent" + +gh issue create \ + --title "Documentation: Update integration guides" \ + --body "Update all documentation..." \ + --label "documentation,integration" +``` + +
+ +
+Issue-to-Swarm Conversion + +#### Transform Issues into Swarm Tasks + +```bash +# Get issue details +ISSUE_DATA=$(gh issue view 456 --json title,body,labels,assignees,comments) + +# Create swarm from issue +npx ruv-swarm github issue-to-swarm 456 \ + --issue-data "$ISSUE_DATA" \ + --auto-decompose \ + --assign-agents + +# Batch process multiple issues +ISSUES=$(gh issue list --label "swarm-ready" --json number,title,body,labels) +npx ruv-swarm github issues-batch \ + --issues "$ISSUES" \ + --parallel + +# Update issues with swarm status +echo "$ISSUES" | jq -r '.[].number' | while read -r num; do + gh issue edit $num --add-label "swarm-processing" +done +``` + +#### Issue Comment Commands + +Execute swarm operations via issue comments: + +```markdown + +/swarm analyze +/swarm decompose 5 +/swarm assign @agent-coder +/swarm estimate +/swarm start +``` + +
+ +
+Automated Issue Triage + +#### Auto-Label Based on Content + +```javascript +// .github/swarm-labels.json +{ + "rules": [ + { + "keywords": ["bug", "error", "broken"], + "labels": ["bug", "swarm-debugger"], + "agents": ["debugger", "tester"] + }, + { + "keywords": ["feature", "implement", "add"], + "labels": ["enhancement", "swarm-feature"], + "agents": ["architect", "coder", "tester"] + }, + { + "keywords": ["slow", "performance", "optimize"], + "labels": ["performance", "swarm-optimizer"], + "agents": ["analyst", "optimizer"] + } + ] +} +``` + +#### Automated Triage System + +```bash +# Analyze and triage unlabeled issues +npx ruv-swarm github triage \ + --unlabeled \ + --analyze-content \ + --suggest-labels \ + --assign-priority + +# Find and link duplicate issues +npx ruv-swarm github find-duplicates \ + --threshold 0.8 \ + --link-related \ + --close-duplicates +``` + +
+ +
+Task Decomposition & Progress Tracking + +#### Break Down Issues into Subtasks + +```bash +# Get issue body +ISSUE_BODY=$(gh issue view 456 --json body --jq '.body') + +# Decompose into subtasks +SUBTASKS=$(npx ruv-swarm github issue-decompose 456 \ + --body "$ISSUE_BODY" \ + --max-subtasks 10 \ + --assign-priorities) + +# Update issue with checklist +CHECKLIST=$(echo "$SUBTASKS" | jq -r '.tasks[] | "- [ ] " + .description') +UPDATED_BODY="$ISSUE_BODY + +## Subtasks +$CHECKLIST" + +gh issue edit 456 --body "$UPDATED_BODY" + +# Create linked issues for major subtasks +echo "$SUBTASKS" | jq -r '.tasks[] | select(.priority == "high")' | while read -r task; do + TITLE=$(echo "$task" | jq -r '.title') + BODY=$(echo "$task" | jq -r '.description') + + gh issue create \ + --title "$TITLE" \ + --body "$BODY + +Parent issue: #456" \ + --label "subtask" +done +``` + +#### Automated Progress Updates + +```bash +# Get current issue state +CURRENT=$(gh issue view 456 --json body,labels) + +# Get swarm progress +PROGRESS=$(npx ruv-swarm github issue-progress 456) + +# Update checklist in issue body +UPDATED_BODY=$(echo "$CURRENT" | jq -r '.body' | \ + npx ruv-swarm github update-checklist --progress "$PROGRESS") + +# Edit issue with updated body +gh issue edit 456 --body "$UPDATED_BODY" + +# Post progress summary as comment +SUMMARY=$(echo "$PROGRESS" | jq -r ' +"## 📊 Progress Update + +**Completion**: \(.completion)% +**ETA**: \(.eta) + +### Completed Tasks +\(.completed | map("- ✅ " + .) | join("\n")) + +### In Progress +\(.in_progress | map("- 🔄 " + .) | join("\n")) + +### Remaining +\(.remaining | map("- ⏳ " + .) | join("\n")) + +--- +🤖 Automated update by swarm agent"') + +gh issue comment 456 --body "$SUMMARY" + +# Update labels based on progress +if [[ $(echo "$PROGRESS" | jq -r '.completion') -eq 100 ]]; then + gh issue edit 456 --add-label "ready-for-review" --remove-label "in-progress" +fi +``` + +
+ +
+Stale Issue Management + +#### Auto-Close Stale Issues with Swarm Analysis + +```bash +# Find stale issues +STALE_DATE=$(date -d '30 days ago' --iso-8601) +STALE_ISSUES=$(gh issue list --state open --json number,title,updatedAt,labels \ + --jq ".[] | select(.updatedAt < \"$STALE_DATE\")") + +# Analyze each stale issue +echo "$STALE_ISSUES" | jq -r '.number' | while read -r num; do + # Get full issue context + ISSUE=$(gh issue view $num --json title,body,comments,labels) + + # Analyze with swarm + ACTION=$(npx ruv-swarm github analyze-stale \ + --issue "$ISSUE" \ + --suggest-action) + + case "$ACTION" in + "close") + gh issue comment $num --body "This issue has been inactive for 30 days and will be closed in 7 days if there's no further activity." + gh issue edit $num --add-label "stale" + ;; + "keep") + gh issue edit $num --remove-label "stale" 2>/dev/null || true + ;; + "needs-info") + gh issue comment $num --body "This issue needs more information. Please provide additional context or it may be closed as stale." + gh issue edit $num --add-label "needs-info" + ;; + esac +done + +# Close issues that have been stale for 37+ days +gh issue list --label stale --state open --json number,updatedAt \ + --jq ".[] | select(.updatedAt < \"$(date -d '37 days ago' --iso-8601)\") | .number" | \ + while read -r num; do + gh issue close $num --comment "Closing due to inactivity. Feel free to reopen if this is still relevant." + done +``` + +
+ +### 2. Project Board Automation + +
+Board Initialization & Configuration + +#### Connect Swarm to GitHub Project + +```bash +# Get project details +PROJECT_ID=$(gh project list --owner @me --format json | \ + jq -r '.projects[] | select(.title == "Development Board") | .id') + +# Initialize swarm with project +npx ruv-swarm github board-init \ + --project-id "$PROJECT_ID" \ + --sync-mode "bidirectional" \ + --create-views "swarm-status,agent-workload,priority" + +# Create project fields for swarm tracking +gh project field-create $PROJECT_ID --owner @me \ + --name "Swarm Status" \ + --data-type "SINGLE_SELECT" \ + --single-select-options "pending,in_progress,completed" +``` + +#### Board Mapping Configuration + +```yaml +# .github/board-sync.yml +version: 1 +project: + name: "AI Development Board" + number: 1 + +mapping: + # Map swarm task status to board columns + status: + pending: "Backlog" + assigned: "Ready" + in_progress: "In Progress" + review: "Review" + completed: "Done" + blocked: "Blocked" + + # Map agent types to labels + agents: + coder: "🔧 Development" + tester: "🧪 Testing" + analyst: "📊 Analysis" + designer: "🎨 Design" + architect: "🏗️ Architecture" + + # Map priority to project fields + priority: + critical: "🔴 Critical" + high: "🟡 High" + medium: "🟢 Medium" + low: "⚪ Low" + + # Custom fields + fields: + - name: "Agent Count" + type: number + source: task.agents.length + - name: "Complexity" + type: select + source: task.complexity + - name: "ETA" + type: date + source: task.estimatedCompletion +``` + +
+ +
+Task Synchronization + +#### Real-time Board Sync + +```bash +# Sync swarm tasks with project cards +npx ruv-swarm github board-sync \ + --map-status '{ + "todo": "To Do", + "in_progress": "In Progress", + "review": "Review", + "done": "Done" + }' \ + --auto-move-cards \ + --update-metadata + +# Enable real-time board updates +npx ruv-swarm github board-realtime \ + --webhook-endpoint "https://api.example.com/github-sync" \ + --update-frequency "immediate" \ + --batch-updates false +``` + +#### Convert Issues to Project Cards + +```bash +# List issues with label +ISSUES=$(gh issue list --label "enhancement" --json number,title,body) + +# Add issues to project +echo "$ISSUES" | jq -r '.[].number' | while read -r issue; do + gh project item-add $PROJECT_ID --owner @me --url "https://github.com/$GITHUB_REPOSITORY/issues/$issue" +done + +# Process with swarm +npx ruv-swarm github board-import-issues \ + --issues "$ISSUES" \ + --add-to-column "Backlog" \ + --parse-checklist \ + --assign-agents +``` + +
+ +
+Smart Card Management + +#### Auto-Assignment + +```bash +# Automatically assign cards to agents +npx ruv-swarm github board-auto-assign \ + --strategy "load-balanced" \ + --consider "expertise,workload,availability" \ + --update-cards +``` + +#### Intelligent Card State Transitions + +```bash +# Smart card movement based on rules +npx ruv-swarm github board-smart-move \ + --rules '{ + "auto-progress": "when:all-subtasks-done", + "auto-review": "when:tests-pass", + "auto-done": "when:pr-merged" + }' +``` + +#### Bulk Operations + +```bash +# Bulk card operations +npx ruv-swarm github board-bulk \ + --filter "status:blocked" \ + --action "add-label:needs-attention" \ + --notify-assignees +``` + +
+ +
+Custom Views & Dashboards + +#### View Configuration + +```javascript +// Custom board views +{ + "views": [ + { + "name": "Swarm Overview", + "type": "board", + "groupBy": "status", + "filters": ["is:open"], + "sort": "priority:desc" + }, + { + "name": "Agent Workload", + "type": "table", + "groupBy": "assignedAgent", + "columns": ["title", "status", "priority", "eta"], + "sort": "eta:asc" + }, + { + "name": "Sprint Progress", + "type": "roadmap", + "dateField": "eta", + "groupBy": "milestone" + } + ] +} +``` + +#### Dashboard Configuration + +```javascript +// Dashboard with performance widgets +{ + "dashboard": { + "widgets": [ + { + "type": "chart", + "title": "Task Completion Rate", + "data": "completed-per-day", + "visualization": "line" + }, + { + "type": "gauge", + "title": "Sprint Progress", + "data": "sprint-completion", + "target": 100 + }, + { + "type": "heatmap", + "title": "Agent Activity", + "data": "agent-tasks-per-day" + } + ] + } +} +``` + +
+ +### 3. Sprint Planning & Tracking + +
+Sprint Management + +#### Initialize Sprint with Swarm Coordination + +```bash +# Manage sprints with swarms +npx ruv-swarm github sprint-manage \ + --sprint "Sprint 23" \ + --auto-populate \ + --capacity-planning \ + --track-velocity + +# Track milestone progress +npx ruv-swarm github milestone-track \ + --milestone "v2.0 Release" \ + --update-board \ + --show-dependencies \ + --predict-completion +``` + +#### Agile Development Board Setup + +```bash +# Setup agile board +npx ruv-swarm github agile-board \ + --methodology "scrum" \ + --sprint-length "2w" \ + --ceremonies "planning,review,retro" \ + --metrics "velocity,burndown" +``` + +#### Kanban Flow Board Setup + +```bash +# Setup kanban board +npx ruv-swarm github kanban-board \ + --wip-limits '{ + "In Progress": 5, + "Review": 3 + }' \ + --cycle-time-tracking \ + --continuous-flow +``` + +
+ +
+Progress Tracking & Analytics + +#### Board Analytics + +```bash +# Fetch project data +PROJECT_DATA=$(gh project item-list $PROJECT_ID --owner @me --format json) + +# Get issue metrics +ISSUE_METRICS=$(echo "$PROJECT_DATA" | jq -r '.items[] | select(.content.type == "Issue")' | \ + while read -r item; do + ISSUE_NUM=$(echo "$item" | jq -r '.content.number') + gh issue view $ISSUE_NUM --json createdAt,closedAt,labels,assignees + done) + +# Generate analytics with swarm +npx ruv-swarm github board-analytics \ + --project-data "$PROJECT_DATA" \ + --issue-metrics "$ISSUE_METRICS" \ + --metrics "throughput,cycle-time,wip" \ + --group-by "agent,priority,type" \ + --time-range "30d" \ + --export "dashboard" +``` + +#### Performance Reports + +```bash +# Track and visualize progress +npx ruv-swarm github board-progress \ + --show "burndown,velocity,cycle-time" \ + --time-period "sprint" \ + --export-metrics + +# Generate reports +npx ruv-swarm github board-report \ + --type "sprint-summary" \ + --format "markdown" \ + --include "velocity,burndown,blockers" \ + --distribute "slack,email" +``` + +#### KPI Tracking + +```bash +# Track board performance +npx ruv-swarm github board-kpis \ + --metrics '[ + "average-cycle-time", + "throughput-per-sprint", + "blocked-time-percentage", + "first-time-pass-rate" + ]' \ + --dashboard-url + +# Track team performance +npx ruv-swarm github team-metrics \ + --board "Development" \ + --per-member \ + --include "velocity,quality,collaboration" \ + --anonymous-option +``` + +
+ +
+Release Planning + +#### Release Coordination + +```bash +# Plan releases using board data +npx ruv-swarm github release-plan-board \ + --analyze-velocity \ + --estimate-completion \ + --identify-risks \ + --optimize-scope +``` + +
+ +### 4. Advanced Coordination + +
+Multi-Board Synchronization + +#### Cross-Board Sync + +```bash +# Sync across multiple boards +npx ruv-swarm github multi-board-sync \ + --boards "Development,QA,Release" \ + --sync-rules '{ + "Development->QA": "when:ready-for-test", + "QA->Release": "when:tests-pass" + }' + +# Cross-organization sync +npx ruv-swarm github cross-org-sync \ + --source "org1/Project-A" \ + --target "org2/Project-B" \ + --field-mapping "custom" \ + --conflict-resolution "source-wins" +``` + +
+ +
+Issue Dependencies & Epic Management + +#### Dependency Resolution + +```bash +# Handle issue dependencies +npx ruv-swarm github issue-deps 456 \ + --resolve-order \ + --parallel-safe \ + --update-blocking +``` + +#### Epic Coordination + +```bash +# Coordinate epic-level swarms +npx ruv-swarm github epic-swarm \ + --epic 123 \ + --child-issues "456,457,458" \ + --orchestrate +``` + +
+ +
+Cross-Repository Coordination + +#### Multi-Repo Issue Management + +```bash +# Handle issues across repositories +npx ruv-swarm github cross-repo \ + --issue "org/repo#456" \ + --related "org/other-repo#123" \ + --coordinate +``` + +
+ +
+Team Collaboration + +#### Work Distribution + +```bash +# Distribute work among team +npx ruv-swarm github board-distribute \ + --strategy "skills-based" \ + --balance-workload \ + --respect-preferences \ + --notify-assignments +``` + +#### Standup Automation + +```bash +# Generate standup reports +npx ruv-swarm github standup-report \ + --team "frontend" \ + --include "yesterday,today,blockers" \ + --format "slack" \ + --schedule "daily-9am" +``` + +#### Review Coordination + +```bash +# Coordinate reviews via board +npx ruv-swarm github review-coordinate \ + --board "Code Review" \ + --assign-reviewers \ + --track-feedback \ + --ensure-coverage +``` + +
+ +--- + +## Issue Templates + +### Integration Issue Template + +```markdown +## 🔄 Integration Task + +### Overview +[Brief description of integration requirements] + +### Objectives +- [ ] Component A integration +- [ ] Component B validation +- [ ] Testing and verification +- [ ] Documentation updates + +### Integration Areas +#### Dependencies +- [ ] Package.json updates +- [ ] Version compatibility +- [ ] Import statements + +#### Functionality +- [ ] Core feature integration +- [ ] API compatibility +- [ ] Performance validation + +#### Testing +- [ ] Unit tests +- [ ] Integration tests +- [ ] End-to-end validation + +### Swarm Coordination +- **Coordinator**: Overall progress tracking +- **Analyst**: Technical validation +- **Tester**: Quality assurance +- **Documenter**: Documentation updates + +### Progress Tracking +Updates will be posted automatically by swarm agents during implementation. + +--- +🤖 Generated with Codex +``` + +### Bug Report Template + +```markdown +## 🐛 Bug Report + +### Problem Description +[Clear description of the issue] + +### Expected Behavior +[What should happen] + +### Actual Behavior +[What actually happens] + +### Reproduction Steps +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Environment +- Package: [package name and version] +- Node.js: [version] +- OS: [operating system] + +### Investigation Plan +- [ ] Root cause analysis +- [ ] Fix implementation +- [ ] Testing and validation +- [ ] Regression testing + +### Swarm Assignment +- **Debugger**: Issue investigation +- **Coder**: Fix implementation +- **Tester**: Validation and testing + +--- +🤖 Generated with Codex +``` + +### Feature Request Template + +```markdown +## ✨ Feature Request + +### Feature Description +[Clear description of the proposed feature] + +### Use Cases +1. [Use case 1] +2. [Use case 2] +3. [Use case 3] + +### Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 +- [ ] Criterion 3 + +### Implementation Approach +#### Design +- [ ] Architecture design +- [ ] API design +- [ ] UI/UX mockups + +#### Development +- [ ] Core implementation +- [ ] Integration with existing features +- [ ] Performance optimization + +#### Testing +- [ ] Unit tests +- [ ] Integration tests +- [ ] User acceptance testing + +### Swarm Coordination +- **Architect**: Design and planning +- **Coder**: Implementation +- **Tester**: Quality assurance +- **Documenter**: Documentation + +--- +🤖 Generated with Codex +``` + +### Swarm Task Template + +```markdown + +name: Swarm Task +description: Create a task for AI swarm processing +body: + - type: dropdown + id: topology + attributes: + label: Swarm Topology + options: + - mesh + - hierarchical + - ring + - star + - type: input + id: agents + attributes: + label: Required Agents + placeholder: "coder, tester, analyst" + - type: textarea + id: tasks + attributes: + label: Task Breakdown + placeholder: | + 1. Task one description + 2. Task two description +``` + +--- + +## Workflow Integration + +### GitHub Actions for Issue Management + +```yaml +# .github/workflows/issue-swarm.yml +name: Issue Swarm Handler +on: + issues: + types: [opened, labeled, commented] + +jobs: + swarm-process: + runs-on: ubuntu-latest + steps: + - name: Process Issue + uses: ruvnet/swarm-action@v1 + with: + command: | + if [[ "${{ github.event.label.name }}" == "swarm-ready" ]]; then + npx ruv-swarm github issue-init ${{ github.event.issue.number }} + fi +``` + +### Board Integration Workflow + +```bash +# Sync with project board +npx ruv-swarm github issue-board-sync \ + --project "Development" \ + --column-mapping '{ + "To Do": "pending", + "In Progress": "active", + "Done": "completed" + }' +``` + +--- + +## Specialized Issue Strategies + +### Bug Investigation Swarm + +```bash +# Specialized bug handling +npx ruv-swarm github bug-swarm 456 \ + --reproduce \ + --isolate \ + --fix \ + --test +``` + +### Feature Implementation Swarm + +```bash +# Feature implementation swarm +npx ruv-swarm github feature-swarm 456 \ + --design \ + --implement \ + --document \ + --demo +``` + +### Technical Debt Refactoring + +```bash +# Refactoring swarm +npx ruv-swarm github debt-swarm 456 \ + --analyze-impact \ + --plan-migration \ + --execute \ + --validate +``` + +--- + +## Best Practices + +### 1. Swarm-Coordinated Issue Management +- Always initialize swarm for complex issues +- Assign specialized agents based on issue type +- Use memory for progress coordination +- Regular automated progress updates + +### 2. Board Organization +- Clear column definitions with consistent naming +- Systematic labeling strategy across repositories +- Regular board grooming and maintenance +- Well-defined automation rules + +### 3. Data Integrity +- Bidirectional sync validation +- Conflict resolution strategies +- Comprehensive audit trails +- Regular backups of project data + +### 4. Team Adoption +- Comprehensive training materials +- Clear, documented workflows +- Regular team reviews and retrospectives +- Active feedback loops for improvement + +### 5. Smart Labeling and Organization +- Consistent labeling strategy across repositories +- Priority-based issue sorting and assignment +- Milestone integration for project coordination +- Agent-type to label mapping + +### 6. Automated Progress Tracking +- Regular automated updates with swarm coordination +- Progress metrics and completion tracking +- Cross-issue dependency management +- Real-time status synchronization + +--- + +## Troubleshooting + +### Sync Issues + +```bash +# Diagnose sync problems +npx ruv-swarm github board-diagnose \ + --check "permissions,webhooks,rate-limits" \ + --test-sync \ + --show-conflicts +``` + +### Performance Optimization + +```bash +# Optimize board performance +npx ruv-swarm github board-optimize \ + --analyze-size \ + --archive-completed \ + --index-fields \ + --cache-views +``` + +### Data Recovery + +```bash +# Recover board data +npx ruv-swarm github board-recover \ + --backup-id "2024-01-15" \ + --restore-cards \ + --preserve-current \ + --merge-conflicts +``` + +--- + +## Metrics & Analytics + +### Performance Metrics + +Automatic tracking of: +- Issue creation and resolution times +- Agent productivity metrics +- Project milestone progress +- Cross-repository coordination efficiency +- Sprint velocity and burndown +- Cycle time and throughput +- Work-in-progress limits + +### Reporting Features + +- Weekly progress summaries +- Agent performance analytics +- Project health metrics +- Integration success rates +- Team collaboration metrics +- Quality and defect tracking + +### Issue Resolution Time + +```bash +# Analyze swarm performance +npx ruv-swarm github issue-metrics \ + --issue 456 \ + --metrics "time-to-close,agent-efficiency,subtask-completion" +``` + +### Swarm Effectiveness + +```bash +# Generate effectiveness report +npx ruv-swarm github effectiveness \ + --issues "closed:>2024-01-01" \ + --compare "with-swarm,without-swarm" +``` + +--- + +## Security & Permissions + +1. **Command Authorization**: Validate user permissions before executing commands +2. **Rate Limiting**: Prevent spam and abuse of issue commands +3. **Audit Logging**: Track all swarm operations on issues and boards +4. **Data Privacy**: Respect private repository settings +5. **Access Control**: Proper GitHub permissions for board operations +6. **Webhook Security**: Secure webhook endpoints for real-time updates + +--- + +## Integration with Other Skills + +### Seamless Integration With: +- `github-pr-workflow` - Link issues to pull requests automatically +- `github-release-management` - Coordinate release issues and milestones +- `sparc-orchestrator` - Complex project coordination workflows +- `sparc-tester` - Automated testing workflows for issues + +--- + +## Complete Workflow Example + +### Full-Stack Feature Development + +```bash +# 1. Create feature issue with swarm coordination +gh issue create \ + --title "Feature: Real-time Collaboration" \ + --body "$(cat < +npx ruv-swarm github issue-decompose +npx ruv-swarm github triage --unlabeled + +# Project Boards +npx ruv-swarm github board-init --project-id +npx ruv-swarm github board-sync +npx ruv-swarm github board-analytics + +# Sprint Management +npx ruv-swarm github sprint-manage --sprint "Sprint X" +npx ruv-swarm github milestone-track --milestone "vX.X" + +# Analytics +npx ruv-swarm github issue-metrics --issue +npx ruv-swarm github board-kpis +``` + +--- + +## Additional Resources + +- [GitHub CLI Documentation](https://cli.github.com/manual/) +- [GitHub Projects Documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects) +- [Swarm Coordination Guide](https://github.com/ruvnet/ruv-swarm) +- [Codex Flow Documentation](https://github.com/ruvnet/Codex-flow) + +--- + +**Last Updated**: 2025-10-19 +**Version**: 2.0.0 +**Maintainer**: Codex diff --git a/.agents/skills/github-release-management/SKILL.md b/.agents/skills/github-release-management/SKILL.md new file mode 100644 index 0000000..5cc4c81 --- /dev/null +++ b/.agents/skills/github-release-management/SKILL.md @@ -0,0 +1,1081 @@ +--- +name: github-release-management +version: 2.0.0 +description: Comprehensive GitHub release orchestration with AI swarm coordination for automated versioning, testing, deployment, and rollback management +category: github +tags: [release, deployment, versioning, automation, ci-cd, swarm, orchestration] +author: Codex Flow Team +requires: + - gh (GitHub CLI) + - Codex-flow + - ruv-swarm (optional for enhanced coordination) + - mcp-github (optional for MCP integration) +dependencies: + - git + - npm or yarn + - node >= 20.0.0 +related_skills: + - github-pr-management + - github-issue-tracking + - github-workflow-automation + - multi-repo-coordination +--- + +# GitHub Release Management Skill + +Intelligent release automation and orchestration using AI swarms for comprehensive software releases - from changelog generation to multi-platform deployment with rollback capabilities. + +## Quick Start + +### Simple Release Flow +```bash +# Plan and create a release +gh release create v2.0.0 \ + --draft \ + --generate-notes \ + --title "Release v2.0.0" + +# Orchestrate with swarm +npx Codex-flow github release-create \ + --version "2.0.0" \ + --build-artifacts \ + --deploy-targets "npm,docker,github" +``` + +### Full Automated Release +```bash +# Initialize release swarm +npx Codex-flow swarm init --topology hierarchical + +# Execute complete release pipeline +npx Codex-flow sparc pipeline "Release v2.0.0 with full validation" +``` + +--- + +## Core Capabilities + +### 1. Release Planning & Version Management +- Semantic version analysis and suggestion +- Breaking change detection from commits +- Release timeline generation +- Multi-package version coordination + +### 2. Automated Testing & Validation +- Multi-stage test orchestration +- Cross-platform compatibility testing +- Performance regression detection +- Security vulnerability scanning + +### 3. Build & Deployment Orchestration +- Multi-platform build coordination +- Parallel artifact generation +- Progressive deployment strategies +- Automated rollback mechanisms + +### 4. Documentation & Communication +- Automated changelog generation +- Release notes with categorization +- Migration guide creation +- Stakeholder notification + +--- + +## Progressive Disclosure: Level 1 - Basic Usage + +### Essential Release Commands + +#### Create Release Draft +```bash +# Get last release tag +LAST_TAG=$(gh release list --limit 1 --json tagName -q '.[0].tagName') + +# Generate changelog from commits +CHANGELOG=$(gh api repos/:owner/:repo/compare/${LAST_TAG}...HEAD \ + --jq '.commits[].commit.message') + +# Create draft release +gh release create v2.0.0 \ + --draft \ + --title "Release v2.0.0" \ + --notes "$CHANGELOG" \ + --target main +``` + +#### Basic Version Bump +```bash +# Update package.json version +npm version patch # or minor, major + +# Push version tag +git push --follow-tags +``` + +#### Simple Deployment +```bash +# Build and publish npm package +npm run build +npm publish + +# Create GitHub release +gh release create $(npm pkg get version) \ + --generate-notes +``` + +### Quick Integration Example +```javascript +// Simple release preparation in Codex +[Single Message]: + // Update version files + Edit("package.json", { old: '"version": "1.0.0"', new: '"version": "2.0.0"' }) + + // Generate changelog + Bash("gh api repos/:owner/:repo/compare/v1.0.0...HEAD --jq '.commits[].commit.message' > CHANGELOG.md") + + // Create release branch + Bash("git checkout -b release/v2.0.0") + Bash("git add -A && git commit -m 'release: Prepare v2.0.0'") + + // Create PR + Bash("gh pr create --title 'Release v2.0.0' --body 'Automated release preparation'") +``` + +--- + +## Progressive Disclosure: Level 2 - Swarm Coordination + +### AI Swarm Release Orchestration + +#### Initialize Release Swarm +```javascript +// Set up coordinated release team +[Single Message - Swarm Initialization]: + mcp__claude-flow__swarm_init { + topology: "hierarchical", + maxAgents: 6, + strategy: "balanced" + } + + // Spawn specialized agents + mcp__claude-flow__agent_spawn { type: "coordinator", name: "Release Director" } + mcp__claude-flow__agent_spawn { type: "coder", name: "Version Manager" } + mcp__claude-flow__agent_spawn { type: "tester", name: "QA Engineer" } + mcp__claude-flow__agent_spawn { type: "reviewer", name: "Release Reviewer" } + mcp__claude-flow__agent_spawn { type: "analyst", name: "Deployment Analyst" } + mcp__claude-flow__agent_spawn { type: "researcher", name: "Compatibility Checker" } +``` + +#### Coordinated Release Workflow +```javascript +[Single Message - Full Release Coordination]: + // Create release branch + Bash("gh api repos/:owner/:repo/git/refs --method POST -f ref='refs/heads/release/v2.0.0' -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')") + + // Orchestrate release preparation + mcp__claude-flow__task_orchestrate { + task: "Prepare release v2.0.0 with comprehensive testing and validation", + strategy: "sequential", + priority: "critical", + maxAgents: 6 + } + + // Update all release files + Write("package.json", "[updated version]") + Write("CHANGELOG.md", "[release changelog]") + Write("RELEASE_NOTES.md", "[detailed notes]") + + // Run comprehensive validation + Bash("npm install && npm test && npm run lint && npm run build") + + // Create release PR + Bash(`gh pr create \ + --title "Release v2.0.0: Feature Set and Improvements" \ + --head "release/v2.0.0" \ + --base "main" \ + --body "$(cat RELEASE_NOTES.md)"`) + + // Track progress + TodoWrite { todos: [ + { content: "Prepare release branch", status: "completed", priority: "critical" }, + { content: "Run validation suite", status: "completed", priority: "high" }, + { content: "Create release PR", status: "completed", priority: "high" }, + { content: "Code review approval", status: "pending", priority: "high" }, + { content: "Merge and deploy", status: "pending", priority: "critical" } + ]} + + // Store release state + mcp__claude-flow__memory_usage { + action: "store", + key: "release/v2.0.0/status", + value: JSON.stringify({ + version: "2.0.0", + stage: "validation_complete", + timestamp: Date.now(), + ready_for_review: true + }) + } +``` + +### Release Agent Specializations + +#### Changelog Agent +```bash +# Get merged PRs between versions +PRS=$(gh pr list --state merged --base main --json number,title,labels,author,mergedAt \ + --jq ".[] | select(.mergedAt > \"$(gh release view v1.0.0 --json publishedAt -q .publishedAt)\")") + +# Get commit history +COMMITS=$(gh api repos/:owner/:repo/compare/v1.0.0...HEAD \ + --jq '.commits[].commit.message') + +# Generate categorized changelog +npx Codex-flow github changelog \ + --prs "$PRS" \ + --commits "$COMMITS" \ + --from v1.0.0 \ + --to HEAD \ + --categorize \ + --add-migration-guide +``` + +**Capabilities:** +- Semantic commit analysis +- Breaking change detection +- Contributor attribution +- Migration guide generation +- Multi-language support + +#### Version Agent +```bash +# Intelligent version suggestion +npx Codex-flow github version-suggest \ + --current v1.2.3 \ + --analyze-commits \ + --check-compatibility \ + --suggest-pre-release +``` + +**Logic:** +- Analyzes commit messages and PR labels +- Detects breaking changes via keywords +- Suggests appropriate version bump +- Handles pre-release versioning +- Validates version constraints + +#### Build Agent +```bash +# Multi-platform build coordination +npx Codex-flow github release-build \ + --platforms "linux,macos,windows" \ + --architectures "x64,arm64" \ + --parallel \ + --optimize-size +``` + +**Features:** +- Cross-platform compilation +- Parallel build execution +- Artifact optimization and compression +- Dependency bundling +- Build caching and reuse + +#### Test Agent +```bash +# Comprehensive pre-release testing +npx Codex-flow github release-test \ + --suites "unit,integration,e2e,performance" \ + --environments "node:16,node:18,node:20" \ + --fail-fast false \ + --generate-report +``` + +#### Deploy Agent +```bash +# Multi-target deployment orchestration +npx Codex-flow github release-deploy \ + --targets "npm,docker,github,s3" \ + --staged-rollout \ + --monitor-metrics \ + --auto-rollback +``` + +--- + +## Progressive Disclosure: Level 3 - Advanced Workflows + +### Multi-Package Release Coordination + +#### Monorepo Release Strategy +```javascript +[Single Message - Multi-Package Release]: + // Initialize mesh topology for cross-package coordination + mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 8 } + + // Spawn package-specific agents + Task("Package A Manager", "Coordinate Codex-flow package release v1.0.72", "coder") + Task("Package B Manager", "Coordinate ruv-swarm package release v1.0.12", "coder") + Task("Integration Tester", "Validate cross-package compatibility", "tester") + Task("Version Coordinator", "Align dependencies and versions", "coordinator") + + // Update all packages simultaneously + Write("packages/Codex-flow/package.json", "[v1.0.72 content]") + Write("packages/ruv-swarm/package.json", "[v1.0.12 content]") + Write("CHANGELOG.md", "[consolidated changelog]") + + // Run cross-package validation + Bash("cd packages/Codex-flow && npm install && npm test") + Bash("cd packages/ruv-swarm && npm install && npm test") + Bash("npm run test:integration") + + // Create unified release PR + Bash(`gh pr create \ + --title "Release: Codex-flow v1.0.72, ruv-swarm v1.0.12" \ + --body "Multi-package coordinated release with cross-compatibility validation"`) +``` + +### Progressive Deployment Strategy + +#### Staged Rollout Configuration +```yaml +# .github/release-deployment.yml +deployment: + strategy: progressive + stages: + - name: canary + percentage: 5 + duration: 1h + metrics: + - error-rate < 0.1% + - latency-p99 < 200ms + auto-advance: true + + - name: partial + percentage: 25 + duration: 4h + validation: automated-tests + approval: qa-team + + - name: rollout + percentage: 50 + duration: 8h + monitor: true + + - name: full + percentage: 100 + approval: release-manager + rollback-enabled: true +``` + +#### Execute Staged Deployment +```bash +# Deploy with progressive rollout +npx Codex-flow github release-deploy \ + --version v2.0.0 \ + --strategy progressive \ + --config .github/release-deployment.yml \ + --monitor-metrics \ + --auto-rollback-on-error +``` + +### Multi-Repository Coordination + +#### Coordinated Multi-Repo Release +```bash +# Synchronize releases across repositories +npx Codex-flow github multi-release \ + --repos "frontend:v2.0.0,backend:v2.1.0,cli:v1.5.0" \ + --ensure-compatibility \ + --atomic-release \ + --synchronized \ + --rollback-all-on-failure +``` + +#### Cross-Repo Dependency Management +```javascript +[Single Message - Cross-Repo Release]: + // Initialize star topology for centralized coordination + mcp__claude-flow__swarm_init { topology: "star", maxAgents: 6 } + + // Spawn repo-specific coordinators + Task("Frontend Release", "Release frontend v2.0.0 with API compatibility", "coordinator") + Task("Backend Release", "Release backend v2.1.0 with breaking changes", "coordinator") + Task("CLI Release", "Release CLI v1.5.0 with new commands", "coordinator") + Task("Compatibility Checker", "Validate cross-repo compatibility", "researcher") + + // Coordinate version updates across repos + Bash("gh api repos/org/frontend/dispatches --method POST -f event_type='release' -F client_payload[version]=v2.0.0") + Bash("gh api repos/org/backend/dispatches --method POST -f event_type='release' -F client_payload[version]=v2.1.0") + Bash("gh api repos/org/cli/dispatches --method POST -f event_type='release' -F client_payload[version]=v1.5.0") + + // Monitor all releases + mcp__claude-flow__swarm_monitor { interval: 5, duration: 300 } +``` + +### Hotfix Emergency Procedures + +#### Emergency Hotfix Workflow +```bash +# Fast-track critical bug fix +npx Codex-flow github emergency-release \ + --issue 789 \ + --severity critical \ + --target-version v1.2.4 \ + --cherry-pick-commits \ + --bypass-checks security-only \ + --fast-track \ + --notify-all +``` + +#### Automated Hotfix Process +```javascript +[Single Message - Emergency Hotfix]: + // Create hotfix branch from last stable release + Bash("git checkout -b hotfix/v1.2.4 v1.2.3") + + // Cherry-pick critical fixes + Bash("git cherry-pick abc123def") + + // Fast validation + Bash("npm run test:critical && npm run build") + + // Create emergency release + Bash(`gh release create v1.2.4 \ + --title "HOTFIX v1.2.4: Critical Security Patch" \ + --notes "Emergency release addressing CVE-2024-XXXX" \ + --prerelease=false`) + + // Immediate deployment + Bash("npm publish --tag hotfix") + + // Notify stakeholders + Bash(`gh issue create \ + --title "🚨 HOTFIX v1.2.4 Deployed" \ + --body "Critical security patch deployed. Please update immediately." \ + --label "critical,security,hotfix"`) +``` + +--- + +## Progressive Disclosure: Level 4 - Enterprise Features + +### Release Configuration Management + +#### Comprehensive Release Config +```yaml +# .github/release-swarm.yml +version: 2.0.0 + +release: + versioning: + strategy: semantic + breaking-keywords: ["BREAKING", "BREAKING CHANGE", "!"] + feature-keywords: ["feat", "feature"] + fix-keywords: ["fix", "bugfix"] + + changelog: + sections: + - title: "🚀 Features" + labels: ["feature", "enhancement"] + emoji: true + - title: "🐛 Bug Fixes" + labels: ["bug", "fix"] + - title: "💥 Breaking Changes" + labels: ["breaking"] + highlight: true + - title: "📚 Documentation" + labels: ["docs", "documentation"] + - title: "⚡ Performance" + labels: ["performance", "optimization"] + - title: "🔒 Security" + labels: ["security"] + priority: critical + + artifacts: + - name: npm-package + build: npm run build + test: npm run test:all + publish: npm publish + registry: https://registry.npmjs.org + + - name: docker-image + build: docker build -t app:$VERSION . + test: docker run app:$VERSION npm test + publish: docker push app:$VERSION + platforms: [linux/amd64, linux/arm64] + + - name: binaries + build: ./scripts/build-binaries.sh + platforms: [linux, macos, windows] + architectures: [x64, arm64] + upload: github-release + sign: true + + validation: + pre-release: + - lint: npm run lint + - typecheck: npm run typecheck + - unit-tests: npm run test:unit + - integration-tests: npm run test:integration + - security-scan: npm audit + - license-check: npm run license-check + + post-release: + - smoke-tests: npm run test:smoke + - deployment-validation: ./scripts/validate-deployment.sh + - performance-baseline: npm run benchmark + + deployment: + environments: + - name: staging + auto-deploy: true + validation: npm run test:e2e + approval: false + + - name: production + auto-deploy: false + approval-required: true + approvers: ["release-manager", "tech-lead"] + rollback-enabled: true + health-checks: + - endpoint: /health + expected: 200 + timeout: 30s + + monitoring: + metrics: + - error-rate: <1% + - latency-p95: <500ms + - availability: >99.9% + - memory-usage: <80% + + alerts: + - type: slack + channel: releases + on: [deploy, rollback, error] + - type: email + recipients: ["team@company.com"] + on: [critical-error, rollback] + - type: pagerduty + service: production-releases + on: [critical-error] + + rollback: + auto-rollback: + triggers: + - error-rate > 5% + - latency-p99 > 2000ms + - availability < 99% + grace-period: 5m + + manual-rollback: + preserve-data: true + notify-users: true + create-incident: true +``` + +### Advanced Testing Strategies + +#### Comprehensive Validation Suite +```bash +# Pre-release validation with all checks +npx Codex-flow github release-validate \ + --checks " + version-conflicts, + dependency-compatibility, + api-breaking-changes, + security-vulnerabilities, + performance-regression, + documentation-completeness, + license-compliance, + backwards-compatibility + " \ + --block-on-failure \ + --generate-report \ + --upload-results +``` + +#### Backward Compatibility Testing +```bash +# Test against previous versions +npx Codex-flow github compat-test \ + --previous-versions "v1.0,v1.1,v1.2" \ + --api-contracts \ + --data-migrations \ + --integration-tests \ + --generate-report +``` + +#### Performance Regression Detection +```bash +# Benchmark against baseline +npx Codex-flow github performance-test \ + --baseline v1.9.0 \ + --candidate v2.0.0 \ + --metrics "throughput,latency,memory,cpu" \ + --threshold 5% \ + --fail-on-regression +``` + +### Release Monitoring & Analytics + +#### Real-Time Release Monitoring +```bash +# Monitor release health post-deployment +npx Codex-flow github release-monitor \ + --version v2.0.0 \ + --metrics "error-rate,latency,throughput,adoption" \ + --alert-thresholds \ + --duration 24h \ + --export-dashboard +``` + +#### Release Analytics & Insights +```bash +# Analyze release performance and adoption +npx Codex-flow github release-analytics \ + --version v2.0.0 \ + --compare-with v1.9.0 \ + --metrics "adoption,performance,stability,feedback" \ + --generate-insights \ + --export-report +``` + +#### Automated Rollback Configuration +```bash +# Configure intelligent auto-rollback +npx Codex-flow github rollback-config \ + --triggers '{ + "error-rate": ">5%", + "latency-p99": ">1000ms", + "availability": "<99.9%", + "failed-health-checks": ">3" + }' \ + --grace-period 5m \ + --notify-on-rollback \ + --preserve-metrics +``` + +### Security & Compliance + +#### Security Scanning +```bash +# Comprehensive security validation +npx Codex-flow github release-security \ + --scan-dependencies \ + --check-secrets \ + --audit-permissions \ + --sign-artifacts \ + --sbom-generation \ + --vulnerability-report +``` + +#### Compliance Validation +```bash +# Ensure regulatory compliance +npx Codex-flow github release-compliance \ + --standards "SOC2,GDPR,HIPAA" \ + --license-audit \ + --data-governance \ + --audit-trail \ + --generate-attestation +``` + +--- + +## GitHub Actions Integration + +### Complete Release Workflow +```yaml +# .github/workflows/release.yml +name: Intelligent Release Workflow +on: + push: + tags: ['v*'] + +jobs: + release-orchestration: + runs-on: ubuntu-latest + permissions: + contents: write + packages: write + issues: write + + steps: + - name: Checkout Repository + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '20' + cache: 'npm' + + - name: Authenticate GitHub CLI + run: echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token + + - name: Initialize Release Swarm + run: | + # Extract version from tag + RELEASE_TAG=${{ github.ref_name }} + PREV_TAG=$(gh release list --limit 2 --json tagName -q '.[1].tagName') + + # Get merged PRs for changelog + PRS=$(gh pr list --state merged --base main --json number,title,labels,author,mergedAt \ + --jq ".[] | select(.mergedAt > \"$(gh release view $PREV_TAG --json publishedAt -q .publishedAt)\")") + + # Get commit history + COMMITS=$(gh api repos/${{ github.repository }}/compare/${PREV_TAG}...HEAD \ + --jq '.commits[].commit.message') + + # Initialize swarm coordination + npx Codex-flow@alpha swarm init --topology hierarchical + + # Store release context + echo "$PRS" > /tmp/release-prs.json + echo "$COMMITS" > /tmp/release-commits.txt + + - name: Generate Release Changelog + run: | + # Generate intelligent changelog + CHANGELOG=$(npx Codex-flow@alpha github changelog \ + --prs "$(cat /tmp/release-prs.json)" \ + --commits "$(cat /tmp/release-commits.txt)" \ + --from $PREV_TAG \ + --to $RELEASE_TAG \ + --categorize \ + --add-migration-guide \ + --format markdown) + + echo "$CHANGELOG" > RELEASE_CHANGELOG.md + + - name: Build Release Artifacts + run: | + # Install dependencies + npm ci + + # Run comprehensive validation + npm run lint + npm run typecheck + npm run test:all + npm run build + + # Build platform-specific binaries + npx Codex-flow@alpha github release-build \ + --platforms "linux,macos,windows" \ + --architectures "x64,arm64" \ + --parallel + + - name: Security Scan + run: | + # Run security validation + npm audit --audit-level=moderate + + npx Codex-flow@alpha github release-security \ + --scan-dependencies \ + --check-secrets \ + --sign-artifacts + + - name: Create GitHub Release + run: | + # Update release with generated changelog + gh release edit ${{ github.ref_name }} \ + --notes "$(cat RELEASE_CHANGELOG.md)" \ + --draft=false + + # Upload all artifacts + for file in dist/*; do + gh release upload ${{ github.ref_name }} "$file" + done + + - name: Deploy to Package Registries + run: | + # Publish to npm + echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc + npm publish + + # Build and push Docker images + docker build -t ${{ github.repository }}:${{ github.ref_name }} . + docker push ${{ github.repository }}:${{ github.ref_name }} + + - name: Post-Release Validation + run: | + # Run smoke tests + npm run test:smoke + + # Validate deployment + npx Codex-flow@alpha github release-validate \ + --version ${{ github.ref_name }} \ + --smoke-tests \ + --health-checks + + - name: Create Release Announcement + run: | + # Create announcement issue + gh issue create \ + --title "🎉 Released ${{ github.ref_name }}" \ + --body "$(cat RELEASE_CHANGELOG.md)" \ + --label "announcement,release" + + # Notify via discussion + gh api repos/${{ github.repository }}/discussions \ + --method POST \ + -f title="Release ${{ github.ref_name }} Now Available" \ + -f body="$(cat RELEASE_CHANGELOG.md)" \ + -f category_id="$(gh api repos/${{ github.repository }}/discussions/categories --jq '.[] | select(.slug=="announcements") | .id')" + + - name: Monitor Release + run: | + # Start release monitoring + npx Codex-flow@alpha github release-monitor \ + --version ${{ github.ref_name }} \ + --duration 1h \ + --alert-on-errors & +``` + +### Hotfix Workflow +```yaml +# .github/workflows/hotfix.yml +name: Emergency Hotfix Workflow +on: + issues: + types: [labeled] + +jobs: + emergency-hotfix: + if: contains(github.event.issue.labels.*.name, 'critical-hotfix') + runs-on: ubuntu-latest + + steps: + - name: Create Hotfix Branch + run: | + LAST_STABLE=$(gh release list --limit 1 --json tagName -q '.[0].tagName') + HOTFIX_VERSION=$(echo $LAST_STABLE | awk -F. '{print $1"."$2"."$3+1}') + + git checkout -b hotfix/$HOTFIX_VERSION $LAST_STABLE + + - name: Fast-Track Testing + run: | + npm ci + npm run test:critical + npm run build + + - name: Emergency Release + run: | + npx Codex-flow@alpha github emergency-release \ + --issue ${{ github.event.issue.number }} \ + --severity critical \ + --fast-track \ + --notify-all +``` + +--- + +## Best Practices & Patterns + +### Release Planning Guidelines + +#### 1. Regular Release Cadence +- **Weekly**: Patch releases with bug fixes +- **Bi-weekly**: Minor releases with features +- **Quarterly**: Major releases with breaking changes +- **On-demand**: Hotfixes for critical issues + +#### 2. Feature Freeze Strategy +- Code freeze 3 days before release +- Only critical bug fixes allowed +- Beta testing period for major releases +- Stakeholder communication plan + +#### 3. Version Management Rules +- Strict semantic versioning compliance +- Breaking changes only in major versions +- Deprecation warnings one minor version ahead +- Cross-package version synchronization + +### Automation Recommendations + +#### 1. Comprehensive CI/CD Pipeline +- Automated testing at every stage +- Security scanning before release +- Performance benchmarking +- Documentation generation + +#### 2. Progressive Deployment +- Canary releases for early detection +- Staged rollouts with monitoring +- Automated health checks +- Quick rollback mechanisms + +#### 3. Monitoring & Observability +- Real-time error tracking +- Performance metrics collection +- User adoption analytics +- Feedback collection automation + +### Documentation Standards + +#### 1. Changelog Requirements +- Categorized changes by type +- Breaking changes highlighted +- Migration guides for major versions +- Contributor attribution + +#### 2. Release Notes Content +- High-level feature summaries +- Detailed technical changes +- Upgrade instructions +- Known issues and limitations + +#### 3. API Documentation +- Automated API doc generation +- Example code updates +- Deprecation notices +- Version compatibility matrix + +--- + +## Troubleshooting & Common Issues + +### Issue: Failed Release Build +```bash +# Debug build failures +npx Codex-flow@alpha diagnostic-run \ + --component build \ + --verbose + +# Retry with isolated environment +docker run --rm -v $(pwd):/app node:20 \ + bash -c "cd /app && npm ci && npm run build" +``` + +### Issue: Test Failures in CI +```bash +# Run tests with detailed output +npm run test -- --verbose --coverage + +# Check for environment-specific issues +npm run test:ci + +# Compare local vs CI environment +npx Codex-flow@alpha github compat-test \ + --environments "local,ci" \ + --compare +``` + +### Issue: Deployment Rollback Needed +```bash +# Immediate rollback to previous version +npx Codex-flow@alpha github rollback \ + --to-version v1.9.9 \ + --reason "Critical bug in v2.0.0" \ + --preserve-data \ + --notify-users + +# Investigate rollback cause +npx Codex-flow@alpha github release-analytics \ + --version v2.0.0 \ + --identify-issues +``` + +### Issue: Version Conflicts +```bash +# Check and resolve version conflicts +npx Codex-flow@alpha github release-validate \ + --checks version-conflicts \ + --auto-resolve + +# Align multi-package versions +npx Codex-flow@alpha github version-sync \ + --packages "package-a,package-b" \ + --strategy semantic +``` + +--- + +## Performance Metrics & Benchmarks + +### Expected Performance +- **Release Planning**: < 2 minutes +- **Build Process**: 3-8 minutes (varies by project) +- **Test Execution**: 5-15 minutes +- **Deployment**: 2-5 minutes per target +- **Complete Pipeline**: 15-30 minutes + +### Optimization Tips +1. **Parallel Execution**: Use swarm coordination for concurrent tasks +2. **Caching**: Enable build and dependency caching +3. **Incremental Builds**: Only rebuild changed components +4. **Test Optimization**: Run critical tests first, full suite in parallel + +### Success Metrics +- **Release Frequency**: Target weekly minor releases +- **Lead Time**: < 2 hours from commit to production +- **Failure Rate**: < 2% of releases require rollback +- **MTTR**: < 30 minutes for critical hotfixes + +--- + +## Related Resources + +### Documentation +- [GitHub CLI Documentation](https://cli.github.com/manual/) +- [Semantic Versioning Spec](https://semver.org/) +- [Codex Flow SPARC Guide](../../docs/sparc-methodology.md) +- [Swarm Coordination Patterns](../../docs/swarm-patterns.md) + +### Related Skills +- **github-pr-management**: PR review and merge automation +- **github-workflow-automation**: CI/CD workflow orchestration +- **multi-repo-coordination**: Cross-repository synchronization +- **deployment-orchestration**: Advanced deployment strategies + +### Support & Community +- Issues: https://github.com/ruvnet/Codex-flow/issues +- Discussions: https://github.com/ruvnet/Codex-flow/discussions +- Documentation: https://Codex-flow.dev/docs + +--- + +## Appendix: Release Checklist Template + +### Pre-Release Checklist +- [ ] Version numbers updated across all packages +- [ ] Changelog generated and reviewed +- [ ] Breaking changes documented with migration guide +- [ ] All tests passing (unit, integration, e2e) +- [ ] Security scan completed with no critical issues +- [ ] Performance benchmarks within acceptable range +- [ ] Documentation updated (API docs, README, examples) +- [ ] Release notes drafted and reviewed +- [ ] Stakeholders notified of upcoming release +- [ ] Deployment plan reviewed and approved + +### Release Checklist +- [ ] Release branch created and validated +- [ ] CI/CD pipeline completed successfully +- [ ] Artifacts built and verified +- [ ] GitHub release created with proper notes +- [ ] Packages published to registries +- [ ] Docker images pushed to container registry +- [ ] Deployment to staging successful +- [ ] Smoke tests passing in staging +- [ ] Production deployment completed +- [ ] Health checks passing + +### Post-Release Checklist +- [ ] Release announcement published +- [ ] Monitoring dashboards reviewed +- [ ] Error rates within normal range +- [ ] Performance metrics stable +- [ ] User feedback collected +- [ ] Documentation links verified +- [ ] Release retrospective scheduled +- [ ] Next release planning initiated + +--- + +**Version**: 2.0.0 +**Last Updated**: 2025-10-19 +**Maintained By**: Codex Flow Team diff --git a/.agents/skills/github-workflow-automation/SKILL.md b/.agents/skills/github-workflow-automation/SKILL.md new file mode 100644 index 0000000..f8e33c0 --- /dev/null +++ b/.agents/skills/github-workflow-automation/SKILL.md @@ -0,0 +1,1065 @@ +--- +name: github-workflow-automation +version: 1.0.0 +category: github +description: Advanced GitHub Actions workflow automation with AI swarm coordination, intelligent CI/CD pipelines, and comprehensive repository management +tags: + - github + - github-actions + - ci-cd + - workflow-automation + - swarm-coordination + - deployment + - security +authors: + - Codex-flow +requires: + - gh (GitHub CLI) + - git + - Codex-flow@alpha + - node (v16+) +priority: high +progressive_disclosure: true +--- + +# GitHub Workflow Automation Skill + +## Overview + +This skill provides comprehensive GitHub Actions automation with AI swarm coordination. It integrates intelligent CI/CD pipelines, workflow orchestration, and repository management to create self-organizing, adaptive GitHub workflows. + +## Quick Start + +
+💡 Basic Usage - Click to expand + +### Initialize GitHub Workflow Automation +```bash +# Start with a simple workflow +npx ruv-swarm actions generate-workflow \ + --analyze-codebase \ + --detect-languages \ + --create-optimal-pipeline +``` + +### Common Commands +```bash +# Optimize existing workflow +npx ruv-swarm actions optimize \ + --workflow ".github/workflows/ci.yml" \ + --suggest-parallelization + +# Analyze failed runs +gh run view --json jobs,conclusion | \ + npx ruv-swarm actions analyze-failure \ + --suggest-fixes +``` + +
+ +## Core Capabilities + +### 🤖 Swarm-Powered GitHub Modes + +
+Available GitHub Integration Modes + +#### 1. gh-coordinator +**GitHub workflow orchestration and coordination** +- **Coordination Mode**: Hierarchical +- **Max Parallel Operations**: 10 +- **Batch Optimized**: Yes +- **Best For**: Complex GitHub workflows, multi-repo coordination + +```bash +# Usage example +npx Codex-flow@alpha github gh-coordinator \ + "Coordinate multi-repo release across 5 repositories" +``` + +#### 2. pr-manager +**Pull request management and review coordination** +- **Review Mode**: Automated +- **Multi-reviewer**: Yes +- **Conflict Resolution**: Intelligent + +```bash +# Create PR with automated review +gh pr create --title "Feature: New capability" \ + --body "Automated PR with swarm review" | \ + npx ruv-swarm actions pr-validate \ + --spawn-agents "linter,tester,security,docs" +``` + +#### 3. issue-tracker +**Issue management and project coordination** +- **Issue Workflow**: Automated +- **Label Management**: Smart +- **Progress Tracking**: Real-time + +```bash +# Create coordinated issue workflow +npx Codex-flow@alpha github issue-tracker \ + "Manage sprint issues with automated tracking" +``` + +#### 4. release-manager +**Release coordination and deployment** +- **Release Pipeline**: Automated +- **Versioning**: Semantic +- **Deployment**: Multi-stage + +```bash +# Automated release management +npx Codex-flow@alpha github release-manager \ + "Create v2.0.0 release with changelog and deployment" +``` + +#### 5. repo-architect +**Repository structure and organization** +- **Structure Optimization**: Yes +- **Multi-repo Support**: Yes +- **Template Management**: Advanced + +```bash +# Optimize repository structure +npx Codex-flow@alpha github repo-architect \ + "Restructure monorepo with optimal organization" +``` + +#### 6. code-reviewer +**Automated code review and quality assurance** +- **Review Quality**: Deep +- **Security Analysis**: Yes +- **Performance Check**: Automated + +```bash +# Automated code review +gh pr view 123 --json files | \ + npx ruv-swarm actions pr-validate \ + --deep-review \ + --security-scan +``` + +#### 7. ci-orchestrator +**CI/CD pipeline coordination** +- **Pipeline Management**: Advanced +- **Test Coordination**: Parallel +- **Deployment**: Automated + +```bash +# Orchestrate CI/CD pipeline +npx Codex-flow@alpha github ci-orchestrator \ + "Setup parallel test execution with smart caching" +``` + +#### 8. security-guardian +**Security and compliance management** +- **Security Scan**: Automated +- **Compliance Check**: Continuous +- **Vulnerability Management**: Proactive + +```bash +# Security audit +npx ruv-swarm actions security \ + --deep-scan \ + --compliance-check \ + --create-issues +``` + +
+ +### 🔧 Workflow Templates + +
+Production-Ready GitHub Actions Templates + +#### 1. Intelligent CI with Swarms +```yaml +# .github/workflows/swarm-ci.yml +name: Intelligent CI with Swarms +on: [push, pull_request] + +jobs: + swarm-analysis: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Initialize Swarm + uses: ruvnet/swarm-action@v1 + with: + topology: mesh + max-agents: 6 + + - name: Analyze Changes + run: | + npx ruv-swarm actions analyze \ + --commit ${{ github.sha }} \ + --suggest-tests \ + --optimize-pipeline +``` + +#### 2. Multi-Language Detection +```yaml +# .github/workflows/polyglot-swarm.yml +name: Polyglot Project Handler +on: push + +jobs: + detect-and-build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Detect Languages + id: detect + run: | + npx ruv-swarm actions detect-stack \ + --output json > stack.json + + - name: Dynamic Build Matrix + run: | + npx ruv-swarm actions create-matrix \ + --from stack.json \ + --parallel-builds +``` + +#### 3. Adaptive Security Scanning +```yaml +# .github/workflows/security-swarm.yml +name: Intelligent Security Scan +on: + schedule: + - cron: '0 0 * * *' + workflow_dispatch: + +jobs: + security-swarm: + runs-on: ubuntu-latest + steps: + - name: Security Analysis Swarm + run: | + SECURITY_ISSUES=$(npx ruv-swarm actions security \ + --deep-scan \ + --format json) + + echo "$SECURITY_ISSUES" | jq -r '.issues[]? | @base64' | while read -r issue; do + _jq() { + echo ${issue} | base64 --decode | jq -r ${1} + } + gh issue create \ + --title "$(_jq '.title')" \ + --body "$(_jq '.body')" \ + --label "security,critical" + done +``` + +#### 4. Self-Healing Pipeline +```yaml +# .github/workflows/self-healing.yml +name: Self-Healing Pipeline +on: workflow_run + +jobs: + heal-pipeline: + if: ${{ github.event.workflow_run.conclusion == 'failure' }} + runs-on: ubuntu-latest + steps: + - name: Diagnose and Fix + run: | + npx ruv-swarm actions self-heal \ + --run-id ${{ github.event.workflow_run.id }} \ + --auto-fix-common \ + --create-pr-complex +``` + +#### 5. Progressive Deployment +```yaml +# .github/workflows/smart-deployment.yml +name: Smart Deployment +on: + push: + branches: [main] + +jobs: + progressive-deploy: + runs-on: ubuntu-latest + steps: + - name: Analyze Risk + id: risk + run: | + npx ruv-swarm actions deploy-risk \ + --changes ${{ github.sha }} \ + --history 30d + + - name: Choose Strategy + run: | + npx ruv-swarm actions deploy-strategy \ + --risk ${{ steps.risk.outputs.level }} \ + --auto-execute +``` + +#### 6. Performance Regression Detection +```yaml +# .github/workflows/performance-guard.yml +name: Performance Guard +on: pull_request + +jobs: + perf-swarm: + runs-on: ubuntu-latest + steps: + - name: Performance Analysis + run: | + npx ruv-swarm actions perf-test \ + --baseline main \ + --threshold 10% \ + --auto-profile-regression +``` + +#### 7. PR Validation Swarm +```yaml +# .github/workflows/pr-validation.yml +name: PR Validation Swarm +on: pull_request + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Multi-Agent Validation + run: | + PR_DATA=$(gh pr view ${{ github.event.pull_request.number }} --json files,labels) + + RESULTS=$(npx ruv-swarm actions pr-validate \ + --spawn-agents "linter,tester,security,docs" \ + --parallel \ + --pr-data "$PR_DATA") + + gh pr comment ${{ github.event.pull_request.number }} \ + --body "$RESULTS" +``` + +#### 8. Intelligent Release +```yaml +# .github/workflows/intelligent-release.yml +name: Intelligent Release +on: + push: + tags: ['v*'] + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Release Swarm + run: | + npx ruv-swarm actions release \ + --analyze-changes \ + --generate-notes \ + --create-artifacts \ + --publish-smart +``` + +
+ +### 📊 Monitoring & Analytics + +
+Workflow Analysis & Optimization + +#### Workflow Analytics +```bash +# Analyze workflow performance +npx ruv-swarm actions analytics \ + --workflow "ci.yml" \ + --period 30d \ + --identify-bottlenecks \ + --suggest-improvements +``` + +#### Cost Optimization +```bash +# Optimize GitHub Actions costs +npx ruv-swarm actions cost-optimize \ + --analyze-usage \ + --suggest-caching \ + --recommend-self-hosted +``` + +#### Failure Pattern Analysis +```bash +# Identify failure patterns +npx ruv-swarm actions failure-patterns \ + --period 90d \ + --classify-failures \ + --suggest-preventions +``` + +#### Resource Management +```bash +# Optimize resource usage +npx ruv-swarm actions resources \ + --analyze-usage \ + --suggest-runners \ + --cost-optimize +``` + +
+ +## Advanced Features + +### 🧪 Dynamic Test Strategies + +
+Intelligent Test Selection & Execution + +#### Smart Test Selection +```yaml +# Automatically select relevant tests +- name: Swarm Test Selection + run: | + npx ruv-swarm actions smart-test \ + --changed-files ${{ steps.files.outputs.all }} \ + --impact-analysis \ + --parallel-safe +``` + +#### Dynamic Test Matrix +```yaml +# Generate test matrix from code analysis +jobs: + generate-matrix: + outputs: + matrix: ${{ steps.set-matrix.outputs.matrix }} + steps: + - id: set-matrix + run: | + MATRIX=$(npx ruv-swarm actions test-matrix \ + --detect-frameworks \ + --optimize-coverage) + echo "matrix=${MATRIX}" >> $GITHUB_OUTPUT + + test: + needs: generate-matrix + strategy: + matrix: ${{fromJson(needs.generate-matrix.outputs.matrix)}} +``` + +#### Intelligent Parallelization +```bash +# Determine optimal parallelization +npx ruv-swarm actions parallel-strategy \ + --analyze-dependencies \ + --time-estimates \ + --cost-aware +``` + +
+ +### 🔮 Predictive Analysis + +
+AI-Powered Workflow Predictions + +#### Predictive Failures +```bash +# Predict potential failures +npx ruv-swarm actions predict \ + --analyze-history \ + --identify-risks \ + --suggest-preventive +``` + +#### Workflow Recommendations +```bash +# Get workflow recommendations +npx ruv-swarm actions recommend \ + --analyze-repo \ + --suggest-workflows \ + --industry-best-practices +``` + +#### Automated Optimization +```bash +# Continuously optimize workflows +npx ruv-swarm actions auto-optimize \ + --monitor-performance \ + --apply-improvements \ + --track-savings +``` + +
+ +### 🎯 Custom Actions Development + +
+Build Your Own Swarm Actions + +#### Custom Swarm Action Template +```javascript +// action.yml +name: 'Swarm Custom Action' +description: 'Custom swarm-powered action' +inputs: + task: + description: 'Task for swarm' + required: true +runs: + using: 'node16' + main: 'dist/index.js' + +// index.js +const { SwarmAction } = require('ruv-swarm'); + +async function run() { + const swarm = new SwarmAction({ + topology: 'mesh', + agents: ['analyzer', 'optimizer'] + }); + + await swarm.execute(core.getInput('task')); +} + +run().catch(error => core.setFailed(error.message)); +``` + +
+ +## Integration with Codex-Flow + +### 🔄 Swarm Coordination Patterns + +
+MCP-Based GitHub Workflow Coordination + +#### Initialize GitHub Swarm +```javascript +// Step 1: Initialize swarm coordination +mcp__claude-flow__swarm_init { + topology: "hierarchical", + maxAgents: 8 +} + +// Step 2: Spawn specialized agents +mcp__claude-flow__agent_spawn { type: "coordinator", name: "GitHub Coordinator" } +mcp__claude-flow__agent_spawn { type: "reviewer", name: "Code Reviewer" } +mcp__claude-flow__agent_spawn { type: "tester", name: "QA Agent" } +mcp__claude-flow__agent_spawn { type: "analyst", name: "Security Analyst" } + +// Step 3: Orchestrate GitHub workflow +mcp__claude-flow__task_orchestrate { + task: "Complete PR review and merge workflow", + strategy: "parallel", + priority: "high" +} +``` + +#### GitHub Hooks Integration +```bash +# Pre-task: Setup GitHub context +npx Codex-flow@alpha hooks pre-task \ + --description "PR review workflow" \ + --context "pr-123" + +# During task: Track progress +npx Codex-flow@alpha hooks notify \ + --message "Completed security scan" \ + --type "github-action" + +# Post-task: Export results +npx Codex-flow@alpha hooks post-task \ + --task-id "pr-review-123" \ + --export-github-summary +``` + +
+ +### 📦 Batch Operations + +
+Concurrent GitHub Operations + +#### Parallel GitHub CLI Commands +```javascript +// Single message with all GitHub operations +[Concurrent Execution]: + Bash("gh issue create --title 'Feature A' --body 'Description A' --label 'enhancement'") + Bash("gh issue create --title 'Feature B' --body 'Description B' --label 'enhancement'") + Bash("gh pr create --title 'PR 1' --head 'feature-a' --base 'main'") + Bash("gh pr create --title 'PR 2' --head 'feature-b' --base 'main'") + Bash("gh pr checks 123 --watch") + TodoWrite { todos: [ + {content: "Review security scan results", status: "pending"}, + {content: "Merge approved PRs", status: "pending"}, + {content: "Update changelog", status: "pending"} + ]} +``` + +
+ +## Best Practices + +### 🏗️ Workflow Organization + +
+Structure Your GitHub Workflows + +#### 1. Use Reusable Workflows +```yaml +# .github/workflows/reusable-swarm.yml +name: Reusable Swarm Workflow +on: + workflow_call: + inputs: + topology: + required: true + type: string + +jobs: + swarm-task: + runs-on: ubuntu-latest + steps: + - name: Initialize Swarm + run: | + npx ruv-swarm init --topology ${{ inputs.topology }} +``` + +#### 2. Implement Proper Caching +```yaml +- name: Cache Swarm Dependencies + uses: actions/cache@v3 + with: + path: ~/.npm + key: ${{ runner.os }}-swarm-${{ hashFiles('**/package-lock.json') }} +``` + +#### 3. Set Appropriate Timeouts +```yaml +jobs: + swarm-task: + timeout-minutes: 30 + steps: + - name: Swarm Operation + timeout-minutes: 10 +``` + +#### 4. Use Workflow Dependencies +```yaml +jobs: + setup: + runs-on: ubuntu-latest + + test: + needs: setup + runs-on: ubuntu-latest + + deploy: + needs: [setup, test] + runs-on: ubuntu-latest +``` + +
+ +### 🔒 Security Best Practices + +
+Secure Your GitHub Workflows + +#### 1. Store Configurations Securely +```yaml +- name: Setup Swarm + env: + SWARM_CONFIG: ${{ secrets.SWARM_CONFIG }} + API_KEY: ${{ secrets.API_KEY }} + run: | + npx ruv-swarm init --config "$SWARM_CONFIG" +``` + +#### 2. Use OIDC Authentication +```yaml +permissions: + id-token: write + contents: read + +- name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v2 + with: + role-to-assume: arn:aws:iam::123456789012:role/GitHubAction + aws-region: us-east-1 +``` + +#### 3. Implement Least-Privilege +```yaml +permissions: + contents: read + pull-requests: write + issues: write +``` + +#### 4. Audit Swarm Operations +```yaml +- name: Audit Swarm Actions + run: | + npx ruv-swarm actions audit \ + --export-logs \ + --compliance-report +``` + +
+ +### ⚡ Performance Optimization + +
+Maximize Workflow Performance + +#### 1. Cache Swarm Dependencies +```yaml +- uses: actions/cache@v3 + with: + path: | + ~/.npm + node_modules + key: ${{ runner.os }}-swarm-${{ hashFiles('**/package-lock.json') }} +``` + +#### 2. Use Appropriate Runner Sizes +```yaml +jobs: + heavy-task: + runs-on: ubuntu-latest-4-cores + steps: + - name: Intensive Swarm Operation +``` + +#### 3. Implement Early Termination +```yaml +- name: Quick Fail Check + run: | + if ! npx ruv-swarm actions pre-check; then + echo "Pre-check failed, terminating early" + exit 1 + fi +``` + +#### 4. Optimize Parallel Execution +```yaml +strategy: + matrix: + include: + - runner: ubuntu-latest + task: test + - runner: ubuntu-latest + task: lint + - runner: ubuntu-latest + task: security + max-parallel: 3 +``` + +
+ +## Debugging & Troubleshooting + +### 🐛 Debug Tools + +
+Debug GitHub Workflow Issues + +#### Debug Mode +```yaml +- name: Debug Swarm + run: | + npx ruv-swarm actions debug \ + --verbose \ + --trace-agents \ + --export-logs + env: + ACTIONS_STEP_DEBUG: true +``` + +#### Performance Profiling +```bash +# Profile workflow performance +npx ruv-swarm actions profile \ + --workflow "ci.yml" \ + --identify-slow-steps \ + --suggest-optimizations +``` + +#### Failure Analysis +```bash +# Analyze failed runs +gh run view --json jobs,conclusion | \ + npx ruv-swarm actions analyze-failure \ + --suggest-fixes \ + --auto-retry-flaky +``` + +#### Log Analysis +```bash +# Download and analyze logs +gh run download +npx ruv-swarm actions analyze-logs \ + --directory ./logs \ + --identify-errors +``` + +
+ +## Real-World Examples + +### 🚀 Complete Workflows + +
+Production-Ready Integration Examples + +#### Example 1: Full-Stack Application CI/CD +```yaml +name: Full-Stack CI/CD with Swarms +on: + push: + branches: [main, develop] + pull_request: + +jobs: + initialize: + runs-on: ubuntu-latest + outputs: + swarm-id: ${{ steps.init.outputs.swarm-id }} + steps: + - id: init + run: | + SWARM_ID=$(npx ruv-swarm init --topology mesh --output json | jq -r '.id') + echo "swarm-id=${SWARM_ID}" >> $GITHUB_OUTPUT + + backend: + needs: initialize + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Backend Tests + run: | + npx ruv-swarm agents spawn --type tester \ + --task "Run backend test suite" \ + --swarm-id ${{ needs.initialize.outputs.swarm-id }} + + frontend: + needs: initialize + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Frontend Tests + run: | + npx ruv-swarm agents spawn --type tester \ + --task "Run frontend test suite" \ + --swarm-id ${{ needs.initialize.outputs.swarm-id }} + + security: + needs: initialize + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Security Scan + run: | + npx ruv-swarm agents spawn --type security \ + --task "Security audit" \ + --swarm-id ${{ needs.initialize.outputs.swarm-id }} + + deploy: + needs: [backend, frontend, security] + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + steps: + - name: Deploy + run: | + npx ruv-swarm actions deploy \ + --strategy progressive \ + --swarm-id ${{ needs.initialize.outputs.swarm-id }} +``` + +#### Example 2: Monorepo Management +```yaml +name: Monorepo Coordination +on: push + +jobs: + detect-changes: + runs-on: ubuntu-latest + outputs: + packages: ${{ steps.detect.outputs.packages }} + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - id: detect + run: | + PACKAGES=$(npx ruv-swarm actions detect-changes \ + --monorepo \ + --output json) + echo "packages=${PACKAGES}" >> $GITHUB_OUTPUT + + build-packages: + needs: detect-changes + runs-on: ubuntu-latest + strategy: + matrix: + package: ${{ fromJson(needs.detect-changes.outputs.packages) }} + steps: + - name: Build Package + run: | + npx ruv-swarm actions build \ + --package ${{ matrix.package }} \ + --parallel-deps +``` + +#### Example 3: Multi-Repo Synchronization +```bash +# Synchronize multiple repositories +npx Codex-flow@alpha github sync-coordinator \ + "Synchronize version updates across: + - github.com/org/repo-a + - github.com/org/repo-b + - github.com/org/repo-c + + Update dependencies, align versions, create PRs" +``` + +
+ +## Command Reference + +### 📚 Quick Command Guide + +
+All Available Commands + +#### Workflow Generation +```bash +npx ruv-swarm actions generate-workflow [options] + --analyze-codebase Analyze repository structure + --detect-languages Detect programming languages + --create-optimal-pipeline Generate optimized workflow +``` + +#### Optimization +```bash +npx ruv-swarm actions optimize [options] + --workflow Path to workflow file + --suggest-parallelization Suggest parallel execution + --reduce-redundancy Remove redundant steps + --estimate-savings Estimate time/cost savings +``` + +#### Analysis +```bash +npx ruv-swarm actions analyze [options] + --commit Analyze specific commit + --suggest-tests Suggest test improvements + --optimize-pipeline Optimize pipeline structure +``` + +#### Testing +```bash +npx ruv-swarm actions smart-test [options] + --changed-files Files that changed + --impact-analysis Analyze test impact + --parallel-safe Only parallel-safe tests +``` + +#### Security +```bash +npx ruv-swarm actions security [options] + --deep-scan Deep security analysis + --format Output format (json/text) + --create-issues Auto-create GitHub issues +``` + +#### Deployment +```bash +npx ruv-swarm actions deploy [options] + --strategy Deployment strategy + --risk Risk assessment level + --auto-execute Execute automatically +``` + +#### Monitoring +```bash +npx ruv-swarm actions analytics [options] + --workflow Workflow to analyze + --period Analysis period + --identify-bottlenecks Find bottlenecks + --suggest-improvements Improvement suggestions +``` + +
+ +## Integration Checklist + +### ✅ Setup Verification + +
+Verify Your Setup + +- [ ] GitHub CLI (`gh`) installed and authenticated +- [ ] Git configured with user credentials +- [ ] Node.js v16+ installed +- [ ] `Codex-flow@alpha` package available +- [ ] Repository has `.github/workflows` directory +- [ ] GitHub Actions enabled on repository +- [ ] Necessary secrets configured +- [ ] Runner permissions verified + +#### Quick Setup Script +```bash +#!/bin/bash +# setup-github-automation.sh + +# Install dependencies +npm install -g Codex-flow@alpha + +# Verify GitHub CLI +gh auth status || gh auth login + +# Create workflow directory +mkdir -p .github/workflows + +# Generate initial workflow +npx ruv-swarm actions generate-workflow \ + --analyze-codebase \ + --create-optimal-pipeline > .github/workflows/ci.yml + +echo "✅ GitHub workflow automation setup complete" +``` + +
+ +## Related Skills + +- `github-pr-enhancement` - Advanced PR management +- `release-coordination` - Release automation +- `swarm-coordination` - Multi-agent orchestration +- `ci-cd-optimization` - Pipeline optimization + +## Support & Documentation + +- **GitHub CLI Docs**: https://cli.github.com/manual/ +- **GitHub Actions**: https://docs.github.com/en/actions +- **Codex-Flow**: https://github.com/ruvnet/Codex-flow +- **Ruv-Swarm**: https://github.com/ruvnet/ruv-swarm + +## Version History + +- **v1.0.0** (2025-01-19): Initial skill consolidation + - Merged workflow-automation.md (441 lines) + - Merged github-modes.md (146 lines) + - Added progressive disclosure + - Enhanced with swarm coordination patterns + - Added comprehensive examples and best practices + +--- + +**Skill Status**: ✅ Production Ready +**Last Updated**: 2025-01-19 +**Maintainer**: Codex-flow team diff --git a/.agents/skills/hooks-automation/SKILL.md b/.agents/skills/hooks-automation/SKILL.md new file mode 100644 index 0000000..4ee9309 --- /dev/null +++ b/.agents/skills/hooks-automation/SKILL.md @@ -0,0 +1,1201 @@ +--- +name: Hooks Automation +description: Automated coordination, formatting, and learning from Codex operations using intelligent hooks with MCP integration. Includes pre/post task hooks, session management, Git integration, memory coordination, and neural pattern training for enhanced development workflows. +--- + +# Hooks Automation + +Intelligent automation system that coordinates, validates, and learns from Codex operations through hooks integrated with MCP tools and neural pattern training. + +## What This Skill Does + +This skill provides a comprehensive hook system that automatically manages development operations, coordinates swarm agents, maintains session state, and continuously learns from coding patterns. It enables automated agent assignment, code formatting, performance tracking, and cross-session memory persistence. + +**Key Capabilities:** +- **Pre-Operation Hooks**: Validate, prepare, and auto-assign agents before operations +- **Post-Operation Hooks**: Format, analyze, and train patterns after operations +- **Session Management**: Persist state, restore context, generate summaries +- **Memory Coordination**: Synchronize knowledge across swarm agents +- **Git Integration**: Automated commit hooks with quality verification +- **Neural Training**: Continuous learning from successful patterns +- **MCP Integration**: Seamless coordination with swarm tools + +## Prerequisites + +**Required:** +- Codex Flow CLI installed (`npm install -g Codex-flow@alpha`) +- Codex with hooks enabled +- `.Codex/settings.json` with hook configurations + +**Optional:** +- MCP servers configured (Codex-flow, ruv-swarm, flow-nexus) +- Git repository for version control +- Testing framework for quality verification + +## Quick Start + +### Initialize Hooks System + +```bash +# Initialize with default hooks configuration +npx Codex-flow init --hooks +``` + +This creates: +- `.Codex/settings.json` with pre-configured hooks +- Hook command documentation in `.Codex/commands/hooks/` +- Default hook handlers for common operations + +### Basic Hook Usage + +```bash +# Pre-task hook (auto-spawns agents) +npx Codex-flow hook pre-task --description "Implement authentication" + +# Post-edit hook (auto-formats and stores in memory) +npx Codex-flow hook post-edit --file "src/auth.js" --memory-key "auth/login" + +# Session end hook (saves state and metrics) +npx Codex-flow hook session-end --session-id "dev-session" --export-metrics +``` + +--- + +## Complete Guide + +### Available Hooks + +#### Pre-Operation Hooks + +Hooks that execute BEFORE operations to prepare and validate: + +**pre-edit** - Validate and assign agents before file modifications +```bash +npx Codex-flow hook pre-edit [options] + +Options: + --file, -f File path to be edited + --auto-assign-agent Automatically assign best agent (default: true) + --validate-syntax Pre-validate syntax before edit + --check-conflicts Check for merge conflicts + --backup-file Create backup before editing + +Examples: + npx Codex-flow hook pre-edit --file "src/auth/login.js" + npx Codex-flow hook pre-edit -f "config/db.js" --validate-syntax + npx Codex-flow hook pre-edit -f "production.env" --backup-file --check-conflicts +``` + +**Features:** +- Auto agent assignment based on file type +- Syntax validation to prevent broken code +- Conflict detection for concurrent edits +- Automatic file backups for safety + +**pre-bash** - Check command safety and resource requirements +```bash +npx Codex-flow hook pre-bash --command + +Options: + --command, -c Command to validate + --check-safety Verify command safety (default: true) + --estimate-resources Estimate resource usage + --require-confirmation Request user confirmation for risky commands + +Examples: + npx Codex-flow hook pre-bash -c "rm -rf /tmp/cache" + npx Codex-flow hook pre-bash --command "docker build ." --estimate-resources +``` + +**Features:** +- Command safety validation +- Resource requirement estimation +- Destructive command confirmation +- Permission checks + +**pre-task** - Auto-spawn agents and prepare for complex tasks +```bash +npx Codex-flow hook pre-task [options] + +Options: + --description, -d Task description for context + --auto-spawn-agents Automatically spawn required agents (default: true) + --load-memory Load relevant memory from previous sessions + --optimize-topology Select optimal swarm topology + --estimate-complexity Analyze task complexity + +Examples: + npx Codex-flow hook pre-task --description "Implement user authentication" + npx Codex-flow hook pre-task -d "Continue API dev" --load-memory + npx Codex-flow hook pre-task -d "Refactor codebase" --optimize-topology +``` + +**Features:** +- Automatic agent spawning based on task analysis +- Memory loading for context continuity +- Topology optimization for task structure +- Complexity estimation and time prediction + +**pre-search** - Prepare and optimize search operations +```bash +npx Codex-flow hook pre-search --query + +Options: + --query, -q Search query + --check-cache Check cache first (default: true) + --optimize-query Optimize search pattern + +Examples: + npx Codex-flow hook pre-search -q "authentication middleware" +``` + +**Features:** +- Cache checking for faster results +- Query optimization +- Search pattern improvement + +#### Post-Operation Hooks + +Hooks that execute AFTER operations to process and learn: + +**post-edit** - Auto-format, validate, and update memory +```bash +npx Codex-flow hook post-edit [options] + +Options: + --file, -f File path that was edited + --auto-format Automatically format code (default: true) + --memory-key, -m Store edit context in memory + --train-patterns Train neural patterns from edit + --validate-output Validate edited file + +Examples: + npx Codex-flow hook post-edit --file "src/components/Button.jsx" + npx Codex-flow hook post-edit -f "api/auth.js" --memory-key "auth/login" + npx Codex-flow hook post-edit -f "utils/helpers.ts" --train-patterns +``` + +**Features:** +- Language-specific auto-formatting (Prettier, Black, gofmt) +- Memory storage for edit context and decisions +- Neural pattern training for continuous improvement +- Output validation with linting + +**post-bash** - Log execution and update metrics +```bash +npx Codex-flow hook post-bash --command + +Options: + --command, -c Command that was executed + --log-output Log command output (default: true) + --update-metrics Update performance metrics + --store-result Store result in memory + +Examples: + npx Codex-flow hook post-bash -c "npm test" --update-metrics +``` + +**Features:** +- Command execution logging +- Performance metric tracking +- Result storage for analysis +- Error pattern detection + +**post-task** - Performance analysis and decision storage +```bash +npx Codex-flow hook post-task [options] + +Options: + --task-id, -t Task identifier for tracking + --analyze-performance Generate performance metrics (default: true) + --store-decisions Save task decisions to memory + --export-learnings Export neural pattern learnings + --generate-report Create task completion report + +Examples: + npx Codex-flow hook post-task --task-id "auth-implementation" + npx Codex-flow hook post-task -t "api-refactor" --analyze-performance + npx Codex-flow hook post-task -t "bug-fix-123" --store-decisions +``` + +**Features:** +- Execution time and token usage measurement +- Decision and implementation choice recording +- Neural learning pattern export +- Completion report generation + +**post-search** - Cache results and improve patterns +```bash +npx Codex-flow hook post-search --query --results + +Options: + --query, -q Original search query + --results, -r Results file path + --cache-results Cache for future use (default: true) + --train-patterns Improve search patterns + +Examples: + npx Codex-flow hook post-search -q "auth" -r "results.json" --train-patterns +``` + +**Features:** +- Result caching for faster subsequent searches +- Search pattern improvement +- Relevance scoring + +#### MCP Integration Hooks + +Hooks that coordinate with MCP swarm tools: + +**mcp-initialized** - Persist swarm configuration +```bash +npx Codex-flow hook mcp-initialized --swarm-id + +Features: +- Save swarm topology and configuration +- Store agent roster in memory +- Initialize coordination namespace +``` + +**agent-spawned** - Update agent roster and memory +```bash +npx Codex-flow hook agent-spawned --agent-id --type + +Features: +- Register agent in coordination memory +- Update agent roster +- Initialize agent-specific memory namespace +``` + +**task-orchestrated** - Monitor task progress +```bash +npx Codex-flow hook task-orchestrated --task-id + +Features: +- Track task progress through memory +- Monitor agent assignments +- Update coordination state +``` + +**neural-trained** - Save pattern improvements +```bash +npx Codex-flow hook neural-trained --pattern + +Features: +- Export trained neural patterns +- Update coordination models +- Share learning across agents +``` + +#### Memory Coordination Hooks + +**memory-write** - Triggered when agents write to coordination memory +```bash +Features: +- Validate memory key format +- Update cross-agent indexes +- Trigger dependent hooks +- Notify subscribed agents +``` + +**memory-read** - Triggered when agents read from coordination memory +```bash +Features: +- Log access patterns +- Update popularity metrics +- Preload related data +- Track usage statistics +``` + +**memory-sync** - Synchronize memory across swarm agents +```bash +npx Codex-flow hook memory-sync --namespace + +Features: +- Sync memory state across agents +- Resolve conflicts +- Propagate updates +- Maintain consistency +``` + +#### Session Hooks + +**session-start** - Initialize new session +```bash +npx Codex-flow hook session-start --session-id + +Options: + --session-id, -s Session identifier + --load-context Load context from previous session + --init-agents Initialize required agents + +Features: +- Create session directory +- Initialize metrics tracking +- Load previous context +- Set up coordination namespace +``` + +**session-restore** - Load previous session state +```bash +npx Codex-flow hook session-restore --session-id + +Options: + --session-id, -s Session to restore + --restore-memory Restore memory state (default: true) + --restore-agents Restore agent configurations + +Examples: + npx Codex-flow hook session-restore --session-id "swarm-20241019" + npx Codex-flow hook session-restore -s "feature-auth" --restore-memory +``` + +**Features:** +- Load previous session context +- Restore memory state and decisions +- Reconfigure agents to previous state +- Resume in-progress tasks + +**session-end** - Cleanup and persist session state +```bash +npx Codex-flow hook session-end [options] + +Options: + --session-id, -s Session identifier to end + --save-state Save current session state (default: true) + --export-metrics Export session metrics + --generate-summary Create session summary + --cleanup-temp Remove temporary files + +Examples: + npx Codex-flow hook session-end --session-id "dev-session-2024" + npx Codex-flow hook session-end -s "feature-auth" --export-metrics --generate-summary + npx Codex-flow hook session-end -s "quick-fix" --cleanup-temp +``` + +**Features:** +- Save current context and progress +- Export session metrics (duration, commands, tokens, files) +- Generate work summary with decisions and next steps +- Cleanup temporary files and optimize storage + +**notify** - Custom notifications with swarm status +```bash +npx Codex-flow hook notify --message + +Options: + --message, -m Notification message + --level Notification level (info|warning|error) + --swarm-status Include swarm status (default: true) + --broadcast Send to all agents + +Examples: + npx Codex-flow hook notify -m "Task completed" --level info + npx Codex-flow hook notify -m "Critical error" --level error --broadcast +``` + +**Features:** +- Send notifications to coordination system +- Include swarm status and metrics +- Broadcast to all agents +- Log important events + +### Configuration + +#### Basic Configuration + +Edit `.Codex/settings.json` to configure hooks: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "^(Write|Edit|MultiEdit)$", + "hooks": [{ + "type": "command", + "command": "npx Codex-flow hook pre-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/current'" + }] + }, + { + "matcher": "^Bash$", + "hooks": [{ + "type": "command", + "command": "npx Codex-flow hook pre-bash --command '${tool.params.command}'" + }] + } + ], + "PostToolUse": [ + { + "matcher": "^(Write|Edit|MultiEdit)$", + "hooks": [{ + "type": "command", + "command": "npx Codex-flow hook post-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/complete' --auto-format --train-patterns" + }] + }, + { + "matcher": "^Bash$", + "hooks": [{ + "type": "command", + "command": "npx Codex-flow hook post-bash --command '${tool.params.command}' --update-metrics" + }] + } + ] + } +} +``` + +#### Advanced Configuration + +Complete hook configuration with all features: + +```json +{ + "hooks": { + "enabled": true, + "debug": false, + "timeout": 5000, + + "PreToolUse": [ + { + "matcher": "^(Write|Edit|MultiEdit)$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook pre-edit --file '${tool.params.file_path}' --auto-assign-agent --validate-syntax", + "timeout": 3000, + "continueOnError": true + } + ] + }, + { + "matcher": "^Task$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook pre-task --description '${tool.params.task}' --auto-spawn-agents --load-memory", + "async": true + } + ] + }, + { + "matcher": "^Grep$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook pre-search --query '${tool.params.pattern}' --check-cache" + } + ] + } + ], + + "PostToolUse": [ + { + "matcher": "^(Write|Edit|MultiEdit)$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook post-edit --file '${tool.params.file_path}' --memory-key 'edits/${tool.params.file_path}' --auto-format --train-patterns", + "async": true + } + ] + }, + { + "matcher": "^Task$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook post-task --task-id '${result.task_id}' --analyze-performance --store-decisions --export-learnings", + "async": true + } + ] + }, + { + "matcher": "^Grep$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook post-search --query '${tool.params.pattern}' --cache-results --train-patterns" + } + ] + } + ], + + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook session-start --session-id '${session.id}' --load-context" + } + ] + } + ], + + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook session-end --session-id '${session.id}' --export-metrics --generate-summary --cleanup-temp" + } + ] + } + ] + } +} +``` + +#### Protected File Patterns + +Add protection for sensitive files: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "^(Write|Edit|MultiEdit)$", + "hooks": [ + { + "type": "command", + "command": "npx Codex-flow hook check-protected --file '${tool.params.file_path}'" + } + ] + } + ] + } +} +``` + +#### Automatic Testing + +Run tests after file modifications: + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "^Write$", + "hooks": [ + { + "type": "command", + "command": "test -f '${tool.params.file_path%.js}.test.js' && npm test '${tool.params.file_path%.js}.test.js'", + "continueOnError": true + } + ] + } + ] + } +} +``` + +### MCP Tool Integration + +Hooks automatically integrate with MCP tools for coordination: + +#### Pre-Task Hook with Agent Spawning + +```javascript +// Hook command +npx Codex-flow hook pre-task --description "Build REST API" + +// Internally calls MCP tools: +mcp__claude-flow__agent_spawn { + type: "backend-dev", + capabilities: ["api", "database", "testing"] +} + +mcp__claude-flow__memory_usage { + action: "store", + key: "swarm/task/api-build/context", + namespace: "coordination", + value: JSON.stringify({ + description: "Build REST API", + agents: ["backend-dev"], + started: Date.now() + }) +} +``` + +#### Post-Edit Hook with Memory Storage + +```javascript +// Hook command +npx Codex-flow hook post-edit --file "api/auth.js" + +// Internally calls MCP tools: +mcp__claude-flow__memory_usage { + action: "store", + key: "swarm/edits/api/auth.js", + namespace: "coordination", + value: JSON.stringify({ + file: "api/auth.js", + timestamp: Date.now(), + changes: { added: 45, removed: 12 }, + formatted: true, + linted: true + }) +} + +mcp__claude-flow__neural_train { + pattern_type: "coordination", + training_data: { /* edit patterns */ } +} +``` + +#### Session End Hook with State Persistence + +```javascript +// Hook command +npx Codex-flow hook session-end --session-id "dev-2024" + +// Internally calls MCP tools: +mcp__claude-flow__memory_persist { + sessionId: "dev-2024" +} + +mcp__claude-flow__swarm_status { + swarmId: "current" +} + +// Generates metrics and summary +``` + +### Memory Coordination Protocol + +All hooks follow a standardized memory coordination pattern: + +#### Three-Phase Memory Protocol + +**Phase 1: STATUS** - Hook starts +```javascript +mcp__claude-flow__memory_usage { + action: "store", + key: "swarm/hooks/pre-edit/status", + namespace: "coordination", + value: JSON.stringify({ + status: "running", + hook: "pre-edit", + file: "src/auth.js", + timestamp: Date.now() + }) +} +``` + +**Phase 2: PROGRESS** - Hook processes +```javascript +mcp__claude-flow__memory_usage { + action: "store", + key: "swarm/hooks/pre-edit/progress", + namespace: "coordination", + value: JSON.stringify({ + progress: 50, + action: "validating syntax", + file: "src/auth.js" + }) +} +``` + +**Phase 3: COMPLETE** - Hook finishes +```javascript +mcp__claude-flow__memory_usage { + action: "store", + key: "swarm/hooks/pre-edit/complete", + namespace: "coordination", + value: JSON.stringify({ + status: "complete", + result: "success", + agent_assigned: "backend-dev", + syntax_valid: true, + backup_created: true + }) +} +``` + +### Hook Response Format + +Hooks return JSON responses to control operation flow: + +#### Continue Response +```json +{ + "continue": true, + "reason": "All validations passed", + "metadata": { + "agent_assigned": "backend-dev", + "syntax_valid": true, + "file": "src/auth.js" + } +} +``` + +#### Block Response +```json +{ + "continue": false, + "reason": "Protected file - manual review required", + "metadata": { + "file": ".env.production", + "protection_level": "high", + "requires": "manual_approval" + } +} +``` + +#### Warning Response +```json +{ + "continue": true, + "reason": "Syntax valid but complexity high", + "warnings": [ + "Cyclomatic complexity: 15 (threshold: 10)", + "Consider refactoring for better maintainability" + ], + "metadata": { + "complexity": 15, + "threshold": 10 + } +} +``` + +### Git Integration + +Hooks can integrate with Git operations for quality control: + +#### Pre-Commit Hook +```bash +# Add to .git/hooks/pre-commit or use husky + +#!/bin/bash +# Run quality checks before commit + +# Get staged files +FILES=$(git diff --cached --name-only --diff-filter=ACM) + +for FILE in $FILES; do + # Run pre-edit hook for validation + npx Codex-flow hook pre-edit --file "$FILE" --validate-syntax + + if [ $? -ne 0 ]; then + echo "Validation failed for $FILE" + exit 1 + fi + + # Run post-edit hook for formatting + npx Codex-flow hook post-edit --file "$FILE" --auto-format +done + +# Run tests +npm test + +exit $? +``` + +#### Post-Commit Hook +```bash +# Add to .git/hooks/post-commit + +#!/bin/bash +# Track commit metrics + +COMMIT_HASH=$(git rev-parse HEAD) +COMMIT_MSG=$(git log -1 --pretty=%B) + +npx Codex-flow hook notify \ + --message "Commit completed: $COMMIT_MSG" \ + --level info \ + --swarm-status +``` + +#### Pre-Push Hook +```bash +# Add to .git/hooks/pre-push + +#!/bin/bash +# Quality gate before push + +# Run full test suite +npm run test:all + +# Run quality checks +npx Codex-flow hook session-end \ + --generate-report \ + --export-metrics + +# Verify quality thresholds +TRUTH_SCORE=$(npx Codex-flow metrics score --format json | jq -r '.truth_score') + +if (( $(echo "$TRUTH_SCORE < 0.95" | bc -l) )); then + echo "Truth score below threshold: $TRUTH_SCORE < 0.95" + exit 1 +fi + +exit 0 +``` + +### Agent Coordination Workflow + +How agents use hooks for coordination: + +#### Agent Workflow Example + +```bash +# Agent 1: Backend Developer +# STEP 1: Pre-task preparation +npx Codex-flow hook pre-task \ + --description "Implement user authentication API" \ + --auto-spawn-agents \ + --load-memory + +# STEP 2: Work begins - pre-edit validation +npx Codex-flow hook pre-edit \ + --file "api/auth.js" \ + --auto-assign-agent \ + --validate-syntax + +# STEP 3: Edit file (via Codex Edit tool) +# ... code changes ... + +# STEP 4: Post-edit processing +npx Codex-flow hook post-edit \ + --file "api/auth.js" \ + --memory-key "swarm/backend/auth-api" \ + --auto-format \ + --train-patterns + +# STEP 5: Notify coordination system +npx Codex-flow hook notify \ + --message "Auth API implementation complete" \ + --swarm-status \ + --broadcast + +# STEP 6: Task completion +npx Codex-flow hook post-task \ + --task-id "auth-api" \ + --analyze-performance \ + --store-decisions \ + --export-learnings +``` + +```bash +# Agent 2: Test Engineer (receives notification) +# STEP 1: Check memory for API details +npx Codex-flow hook session-restore \ + --session-id "swarm-current" \ + --restore-memory + +# Memory contains: swarm/backend/auth-api with implementation details + +# STEP 2: Generate tests +npx Codex-flow hook pre-task \ + --description "Write tests for auth API" \ + --load-memory + +# STEP 3: Create test file +npx Codex-flow hook post-edit \ + --file "api/auth.test.js" \ + --memory-key "swarm/testing/auth-api-tests" \ + --train-patterns + +# STEP 4: Share test results +npx Codex-flow hook notify \ + --message "Auth API tests complete - 100% coverage" \ + --broadcast +``` + +### Custom Hook Creation + +Create custom hooks for specific workflows: + +#### Custom Hook Template + +```javascript +// .Codex/hooks/custom-quality-check.js + +module.exports = { + name: 'custom-quality-check', + type: 'pre', + matcher: /\.(ts|js)$/, + + async execute(context) { + const { file, content } = context; + + // Custom validation logic + const complexity = await analyzeComplexity(content); + const securityIssues = await scanSecurity(content); + + // Store in memory + await storeInMemory({ + key: `quality/${file}`, + value: { complexity, securityIssues } + }); + + // Return decision + if (complexity > 15 || securityIssues.length > 0) { + return { + continue: false, + reason: 'Quality checks failed', + warnings: [ + `Complexity: ${complexity} (max: 15)`, + `Security issues: ${securityIssues.length}` + ] + }; + } + + return { + continue: true, + reason: 'Quality checks passed', + metadata: { complexity, securityIssues: 0 } + }; + } +}; +``` + +#### Register Custom Hook + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "^(Write|Edit)$", + "hooks": [ + { + "type": "script", + "script": ".Codex/hooks/custom-quality-check.js" + } + ] + } + ] + } +} +``` + +### Real-World Examples + +#### Example 1: Full-Stack Development Workflow + +```bash +# Session start - initialize coordination +npx Codex-flow hook session-start --session-id "fullstack-feature" + +# Pre-task planning +npx Codex-flow hook pre-task \ + --description "Build user profile feature - frontend + backend + tests" \ + --auto-spawn-agents \ + --optimize-topology + +# Backend work +npx Codex-flow hook pre-edit --file "api/profile.js" +# ... implement backend ... +npx Codex-flow hook post-edit \ + --file "api/profile.js" \ + --memory-key "profile/backend" \ + --train-patterns + +# Frontend work (reads backend details from memory) +npx Codex-flow hook pre-edit --file "components/Profile.jsx" +# ... implement frontend ... +npx Codex-flow hook post-edit \ + --file "components/Profile.jsx" \ + --memory-key "profile/frontend" \ + --train-patterns + +# Testing (reads both backend and frontend from memory) +npx Codex-flow hook pre-task \ + --description "Test profile feature" \ + --load-memory + +# Session end - export everything +npx Codex-flow hook session-end \ + --session-id "fullstack-feature" \ + --export-metrics \ + --generate-summary +``` + +#### Example 2: Debugging with Hooks + +```bash +# Start debugging session +npx Codex-flow hook session-start --session-id "debug-memory-leak" + +# Pre-task: analyze issue +npx Codex-flow hook pre-task \ + --description "Debug memory leak in event handlers" \ + --load-memory \ + --estimate-complexity + +# Search for event emitters +npx Codex-flow hook pre-search --query "EventEmitter" +# ... search executes ... +npx Codex-flow hook post-search \ + --query "EventEmitter" \ + --cache-results + +# Fix the issue +npx Codex-flow hook pre-edit \ + --file "services/events.js" \ + --backup-file +# ... fix code ... +npx Codex-flow hook post-edit \ + --file "services/events.js" \ + --memory-key "debug/memory-leak-fix" \ + --validate-output + +# Verify fix +npx Codex-flow hook post-task \ + --task-id "memory-leak-fix" \ + --analyze-performance \ + --generate-report + +# End session +npx Codex-flow hook session-end \ + --session-id "debug-memory-leak" \ + --export-metrics +``` + +#### Example 3: Multi-Agent Refactoring + +```bash +# Initialize swarm for refactoring +npx Codex-flow hook pre-task \ + --description "Refactor legacy codebase to modern patterns" \ + --auto-spawn-agents \ + --optimize-topology + +# Agent 1: Code Analyzer +npx Codex-flow hook pre-task --description "Analyze code complexity" +# ... analysis ... +npx Codex-flow hook post-task \ + --task-id "analysis" \ + --store-decisions + +# Agent 2: Refactoring (reads analysis from memory) +npx Codex-flow hook session-restore \ + --session-id "swarm-refactor" \ + --restore-memory + +for file in src/**/*.js; do + npx Codex-flow hook pre-edit --file "$file" --backup-file + # ... refactor ... + npx Codex-flow hook post-edit \ + --file "$file" \ + --memory-key "refactor/$file" \ + --auto-format \ + --train-patterns +done + +# Agent 3: Testing (reads refactored code from memory) +npx Codex-flow hook pre-task \ + --description "Generate tests for refactored code" \ + --load-memory + +# Broadcast completion +npx Codex-flow hook notify \ + --message "Refactoring complete - all tests passing" \ + --broadcast +``` + +### Performance Tips + +1. **Keep Hooks Lightweight** - Target < 100ms execution time +2. **Use Async for Heavy Operations** - Don't block the main flow +3. **Cache Aggressively** - Store frequently accessed data +4. **Batch Related Operations** - Combine multiple actions +5. **Use Memory Wisely** - Set appropriate TTLs +6. **Monitor Hook Performance** - Track execution times +7. **Parallelize When Possible** - Run independent hooks concurrently + +### Debugging Hooks + +Enable debug mode for troubleshooting: + +```bash +# Enable debug output +export CLAUDE_FLOW_DEBUG=true + +# Test specific hook with verbose output +npx Codex-flow hook pre-edit --file "test.js" --debug + +# Check hook execution logs +cat .Codex-flow/logs/hooks-$(date +%Y-%m-%d).log + +# Validate configuration +npx Codex-flow hook validate-config +``` + +### Benefits + +- **Automatic Agent Assignment**: Right agent for every file type +- **Consistent Code Formatting**: Language-specific formatters +- **Continuous Learning**: Neural patterns improve over time +- **Cross-Session Memory**: Context persists between sessions +- **Performance Tracking**: Comprehensive metrics and analytics +- **Automatic Coordination**: Agents sync via memory +- **Smart Agent Spawning**: Task-based agent selection +- **Quality Gates**: Pre-commit validation and verification +- **Error Prevention**: Syntax validation before edits +- **Knowledge Sharing**: Decisions stored and shared +- **Reduced Manual Work**: Automation of repetitive tasks +- **Better Collaboration**: Seamless multi-agent coordination + +### Best Practices + +1. **Configure Hooks Early** - Set up during project initialization +2. **Use Memory Keys Strategically** - Organize with clear namespaces +3. **Enable Auto-Formatting** - Maintain code consistency +4. **Train Patterns Continuously** - Learn from successful operations +5. **Monitor Performance** - Track hook execution times +6. **Validate Configuration** - Test hooks before production use +7. **Document Custom Hooks** - Maintain hook documentation +8. **Set Appropriate Timeouts** - Prevent hanging operations +9. **Handle Errors Gracefully** - Use continueOnError when appropriate +10. **Review Metrics Regularly** - Optimize based on usage patterns + +### Troubleshooting + +#### Hooks Not Executing +- Verify `.Codex/settings.json` syntax +- Check hook matcher patterns +- Enable debug mode +- Review permission settings +- Ensure Codex-flow CLI is in PATH + +#### Hook Timeouts +- Increase timeout values in configuration +- Make hooks asynchronous for heavy operations +- Optimize hook logic +- Check network connectivity for MCP tools + +#### Memory Issues +- Set appropriate TTLs for memory keys +- Clean up old memory entries +- Use memory namespaces effectively +- Monitor memory usage + +#### Performance Problems +- Profile hook execution times +- Use caching for repeated operations +- Batch operations when possible +- Reduce hook complexity + +### Related Commands + +- `npx Codex-flow init --hooks` - Initialize hooks system +- `npx Codex-flow hook --list` - List available hooks +- `npx Codex-flow hook --test ` - Test specific hook +- `npx Codex-flow memory usage` - Manage memory +- `npx Codex-flow agent spawn` - Spawn agents +- `npx Codex-flow swarm init` - Initialize swarm + +### Integration with Other Skills + +This skill works seamlessly with: +- **SPARC Methodology** - Hooks enhance SPARC workflows +- **Pair Programming** - Automated quality in pairing sessions +- **Verification Quality** - Truth-score validation in hooks +- **GitHub Workflows** - Git integration for commits/PRs +- **Performance Analysis** - Metrics collection in hooks +- **Swarm Advanced** - Multi-agent coordination via hooks diff --git a/.agents/skills/pair-programming/SKILL.md b/.agents/skills/pair-programming/SKILL.md new file mode 100644 index 0000000..a76e93c --- /dev/null +++ b/.agents/skills/pair-programming/SKILL.md @@ -0,0 +1,1202 @@ +--- +name: Pair Programming +description: AI-assisted pair programming with multiple modes (driver/navigator/switch), real-time verification, quality monitoring, and comprehensive testing. Supports TDD, debugging, refactoring, and learning sessions. Features automatic role switching, continuous code review, security scanning, and performance optimization with truth-score verification. +--- + +# Pair Programming + +Collaborative AI pair programming with intelligent role management, real-time quality monitoring, and comprehensive development workflows. + +## What This Skill Does + +This skill provides professional pair programming capabilities with AI assistance, supporting multiple collaboration modes, continuous verification, and integrated testing. It manages driver/navigator roles, performs real-time code review, tracks quality metrics, and ensures high standards through truth-score verification. + +**Key Capabilities:** +- **Multiple Modes**: Driver, Navigator, Switch, TDD, Review, Mentor, Debug +- **Real-Time Verification**: Automatic quality scoring with rollback on failures +- **Role Management**: Seamless switching between driver/navigator roles +- **Testing Integration**: Auto-generate tests, track coverage, continuous testing +- **Code Review**: Security scanning, performance analysis, best practice enforcement +- **Session Persistence**: Auto-save, recovery, export, and sharing + +## Prerequisites + +**Required:** +- Codex Flow CLI installed (`npm install -g Codex-flow@alpha`) +- Git repository (optional but recommended) + +**Recommended:** +- Testing framework (Jest, pytest, etc.) +- Linter configured (ESLint, pylint, etc.) +- Code formatter (Prettier, Black, etc.) + +## Quick Start + +### Basic Session +```bash +# Start simple pair programming +Codex-flow pair --start +``` + +### TDD Session +```bash +# Test-driven development +Codex-flow pair --start \ + --mode tdd \ + --test-first \ + --coverage 90 +``` + +--- + +## Complete Guide + +### Session Control Commands + +#### Starting Sessions +```bash +# Basic start +Codex-flow pair --start + +# Expert refactoring session +Codex-flow pair --start \ + --agent senior-dev \ + --focus refactor \ + --verify \ + --threshold 0.98 + +# Debugging session +Codex-flow pair --start \ + --agent debugger-expert \ + --focus debug \ + --review + +# Learning session +Codex-flow pair --start \ + --mode mentor \ + --pace slow \ + --examples +``` + +#### Session Management +```bash +# Check status +Codex-flow pair --status + +# View history +Codex-flow pair --history + +# Pause session +/pause [--reason ] + +# Resume session +/resume + +# End session +Codex-flow pair --end [--save] [--report] +``` + +### Available Modes + +#### Driver Mode +You write code while AI provides guidance. + +```bash +Codex-flow pair --start --mode driver +``` + +**Your Responsibilities:** +- Write actual code +- Implement solutions +- Make immediate decisions +- Handle syntax and structure + +**AI Navigator:** +- Strategic guidance +- Spot potential issues +- Suggest improvements +- Real-time review +- Track overall direction + +**Best For:** +- Learning new patterns +- Implementing familiar features +- Quick iterations +- Hands-on debugging + +**Commands:** +``` +/suggest - Get implementation suggestions +/review - Request code review +/explain - Ask for explanations +/optimize - Request optimization ideas +/patterns - Get pattern recommendations +``` + +#### Navigator Mode +AI writes code while you provide direction. + +```bash +Codex-flow pair --start --mode navigator +``` + +**Your Responsibilities:** +- Provide high-level direction +- Review generated code +- Make architectural decisions +- Ensure business requirements + +**AI Driver:** +- Write implementation code +- Handle syntax details +- Implement your guidance +- Manage boilerplate +- Execute refactoring + +**Best For:** +- Rapid prototyping +- Boilerplate generation +- Learning from AI patterns +- Exploring solutions + +**Commands:** +``` +/implement - Direct implementation +/refactor - Request refactoring +/test - Generate tests +/document - Add documentation +/alternate - See alternative approaches +``` + +#### Switch Mode +Automatically alternates roles at intervals. + +```bash +# Default 10-minute intervals +Codex-flow pair --start --mode switch + +# 5-minute intervals (rapid) +Codex-flow pair --start --mode switch --interval 5m + +# 15-minute intervals (deep focus) +Codex-flow pair --start --mode switch --interval 15m +``` + +**Handoff Process:** +1. 30-second warning before switch +2. Current driver completes thought +3. Context summary generated +4. Roles swap smoothly +5. New driver continues + +**Best For:** +- Balanced collaboration +- Knowledge sharing +- Complex features +- Extended sessions + +#### Specialized Modes + +**TDD Mode** - Test-Driven Development: +```bash +Codex-flow pair --start \ + --mode tdd \ + --test-first \ + --coverage 100 +``` +Workflow: Write failing test → Implement → Refactor → Repeat + +**Review Mode** - Continuous code review: +```bash +Codex-flow pair --start \ + --mode review \ + --strict \ + --security +``` +Features: Real-time feedback, security scanning, performance analysis + +**Mentor Mode** - Learning-focused: +```bash +Codex-flow pair --start \ + --mode mentor \ + --explain-all \ + --pace slow +``` +Features: Detailed explanations, step-by-step guidance, pattern teaching + +**Debug Mode** - Problem-solving: +```bash +Codex-flow pair --start \ + --mode debug \ + --verbose \ + --trace +``` +Features: Issue identification, root cause analysis, fix suggestions + +### In-Session Commands + +#### Code Commands +``` +/explain [--level basic|detailed|expert] + Explain the current code or selection + +/suggest [--type refactor|optimize|security|style] + Get improvement suggestions + +/implement + Request implementation (navigator mode) + +/refactor [--pattern ] [--scope function|file|module] + Refactor selected code + +/optimize [--target speed|memory|both] + Optimize code for performance + +/document [--format jsdoc|markdown|inline] + Add documentation to code + +/comment [--verbose] + Add inline comments + +/pattern [--example] + Apply a design pattern +``` + +#### Testing Commands +``` +/test [--watch] [--coverage] [--only ] + Run test suite + +/test-gen [--type unit|integration|e2e] + Generate tests for current code + +/coverage [--report html|json|terminal] + Check test coverage + +/mock [--realistic] + Generate mock data or functions + +/test-watch [--on-save] + Enable test watching + +/snapshot [--update] + Create test snapshots +``` + +#### Review Commands +``` +/review [--scope current|file|changes] [--strict] + Perform code review + +/security [--deep] [--fix] + Security analysis + +/perf [--profile] [--suggestions] + Performance analysis + +/quality [--detailed] + Check code quality metrics + +/lint [--fix] [--config ] + Run linters + +/complexity [--threshold ] + Analyze code complexity +``` + +#### Navigation Commands +``` +/goto [:line[:column]] + Navigate to file or location + +/find [--regex] [--case-sensitive] + Search in project + +/recent [--limit ] + Show recent files + +/bookmark [add|list|goto|remove] [] + Manage bookmarks + +/history [--limit ] [--filter ] + Show command history + +/tree [--depth ] [--filter ] + Show project structure +``` + +#### Git Commands +``` +/diff [--staged] [--file ] + Show git diff + +/commit [--message ] [--amend] + Commit with verification + +/branch [create|switch|delete|list] [] + Branch operations + +/stash [save|pop|list|apply] [] + Stash operations + +/log [--oneline] [--limit ] + View git log + +/blame [] + Show git blame +``` + +#### AI Partner Commands +``` +/agent [switch|info|config] [] + Manage AI agent + +/teach + Teach the AI your preferences + +/feedback [positive|negative] + Provide feedback to AI + +/personality [professional|friendly|concise|verbose] + Adjust AI personality + +/expertise [add|remove|list] [] + Set AI expertise focus +``` + +#### Metrics Commands +``` +/metrics [--period today|session|week|all] + Show session metrics + +/score [--breakdown] + Show quality scores + +/productivity [--chart] + Show productivity metrics + +/leaderboard [--personal|team] + Show improvement leaderboard +``` + +#### Role & Mode Commands +``` +/switch [--immediate] + Switch driver/navigator roles + +/mode + Change mode (driver|navigator|switch|tdd|review|mentor|debug) + +/role + Show current role + +/handoff + Prepare role handoff +``` + +### Command Shortcuts + +| Alias | Full Command | +|-------|-------------| +| `/s` | `/suggest` | +| `/e` | `/explain` | +| `/t` | `/test` | +| `/r` | `/review` | +| `/c` | `/commit` | +| `/g` | `/goto` | +| `/f` | `/find` | +| `/h` | `/help` | +| `/sw` | `/switch` | +| `/st` | `/status` | + +### Configuration + +#### Basic Configuration +Create `.Codex-flow/pair-config.json`: + +```json +{ + "pair": { + "enabled": true, + "defaultMode": "switch", + "defaultAgent": "auto", + "autoStart": false, + "theme": "professional" + } +} +``` + +#### Complete Configuration + +```json +{ + "pair": { + "general": { + "enabled": true, + "defaultMode": "switch", + "defaultAgent": "senior-dev", + "language": "javascript", + "timezone": "UTC" + }, + + "modes": { + "driver": { + "enabled": true, + "suggestions": true, + "realTimeReview": true, + "autoComplete": false + }, + "navigator": { + "enabled": true, + "codeGeneration": true, + "explanations": true, + "alternatives": true + }, + "switch": { + "enabled": true, + "interval": "10m", + "warning": "30s", + "autoSwitch": true, + "pauseOnIdle": true + } + }, + + "verification": { + "enabled": true, + "threshold": 0.95, + "autoRollback": true, + "preCommitCheck": true, + "continuousMonitoring": true, + "blockOnFailure": true + }, + + "testing": { + "enabled": true, + "autoRun": true, + "framework": "jest", + "onSave": true, + "coverage": { + "enabled": true, + "minimum": 80, + "enforce": true, + "reportFormat": "html" + } + }, + + "review": { + "enabled": true, + "continuous": true, + "preCommit": true, + "security": true, + "performance": true, + "style": true, + "complexity": { + "maxComplexity": 10, + "maxDepth": 4, + "maxLines": 100 + } + }, + + "git": { + "enabled": true, + "autoCommit": false, + "commitTemplate": "feat: {message}", + "signCommits": false, + "pushOnEnd": false, + "branchProtection": true + }, + + "session": { + "autoSave": true, + "saveInterval": "5m", + "maxDuration": "4h", + "idleTimeout": "15m", + "breakReminder": "45m", + "metricsInterval": "1m" + }, + + "ai": { + "model": "advanced", + "temperature": 0.7, + "maxTokens": 4000, + "personality": "professional", + "expertise": ["backend", "testing", "security"], + "learningEnabled": true + } + } +} +``` + +#### Built-in Agents + +```json +{ + "agents": { + "senior-dev": { + "expertise": ["architecture", "patterns", "optimization"], + "style": "thorough", + "reviewLevel": "strict" + }, + "tdd-specialist": { + "expertise": ["testing", "mocks", "coverage"], + "style": "test-first", + "reviewLevel": "comprehensive" + }, + "debugger-expert": { + "expertise": ["debugging", "profiling", "tracing"], + "style": "analytical", + "reviewLevel": "focused" + }, + "junior-dev": { + "expertise": ["learning", "basics", "documentation"], + "style": "questioning", + "reviewLevel": "educational" + } + } +} +``` + +#### CLI Configuration +```bash +# Set configuration +Codex-flow pair config set defaultMode switch +Codex-flow pair config set verification.threshold 0.98 + +# Get configuration +Codex-flow pair config get +Codex-flow pair config get defaultMode + +# Export/Import +Codex-flow pair config export > config.json +Codex-flow pair config import config.json + +# Reset +Codex-flow pair config reset +``` + +#### Profile Management + +Create reusable profiles: + +```bash +# Create profile +Codex-flow pair profile create refactoring \ + --mode driver \ + --verify true \ + --threshold 0.98 \ + --focus refactor + +# Use profile +Codex-flow pair --start --profile refactoring + +# List profiles +Codex-flow pair profile list +``` + +Profile configuration: +```json +{ + "profiles": { + "refactoring": { + "mode": "driver", + "verification": { + "enabled": true, + "threshold": 0.98 + }, + "focus": "refactor" + }, + "debugging": { + "mode": "navigator", + "agent": "debugger-expert", + "trace": true, + "verbose": true + }, + "learning": { + "mode": "mentor", + "pace": "slow", + "explanations": "detailed", + "examples": true + } + } +} +``` + +### Real-World Examples + +#### Example 1: Feature Implementation + +Implementing user authentication with JWT tokens: + +```bash +# Session setup +Codex-flow pair --start \ + --mode switch \ + --agent senior-dev \ + --focus implement \ + --verify \ + --test +``` + +**Session Flow:** +``` +👥 Starting pair programming for authentication feature... + +[DRIVER: You - 10 minutes] +/explain JWT authentication flow +> AI explains JWT concepts and best practices + +/suggest implementation approach +> AI suggests using middleware pattern with refresh tokens + +# You write the basic auth middleware structure + +[SWITCH TO NAVIGATOR] + +[NAVIGATOR: AI - 10 minutes] +/implement JWT token generation with refresh tokens +> AI generates secure token implementation + +/test-gen +> AI creates comprehensive test suite + +[SWITCH TO DRIVER] + +[DRIVER: You - 10 minutes] +# You refine the implementation +/review --security +> AI performs security review, suggests improvements + +/commit --message "feat: JWT authentication with refresh tokens" +✅ Truth Score: 0.98 - Committed successfully +``` + +#### Example 2: Bug Fixing + +Debugging a memory leak in Node.js: + +```bash +# Session setup +Codex-flow pair --start \ + --mode navigator \ + --agent debugger-expert \ + --focus debug \ + --trace +``` + +**Session Flow:** +``` +👥 Starting debugging session... + +/status +> Analyzing application for memory issues... + +/perf --profile +> Memory usage growing: 150MB → 450MB over 10 minutes + +/find "new EventEmitter" --regex +> Found 3 instances of EventEmitter creation + +/inspect eventEmitters --deep +> Discovering listeners not being removed + +/suggest fix for memory leak +> AI suggests: "Add removeListener in cleanup functions" + +/implement cleanup functions for all event emitters +> AI generates proper cleanup code + +/test +> Memory stable at 150MB ✅ + +/commit --message "fix: memory leak in event emitters" +``` + +#### Example 3: TDD Session + +Building shopping cart with test-driven development: + +```bash +# Session setup +Codex-flow pair --start \ + --mode tdd \ + --agent tdd-specialist \ + --test-first +``` + +**Session Flow:** +``` +👥 TDD Session: Shopping Cart Feature + +[RED PHASE] +/test-gen "add item to cart" +> AI writes failing test: + ✗ should add item to cart + ✗ should update quantity for existing item + ✗ should calculate total price + +[GREEN PHASE] +/implement minimal cart functionality +> You write just enough code to pass tests + +/test +> Tests passing: 3/3 ✅ + +[REFACTOR PHASE] +/refactor --pattern repository +> AI refactors to repository pattern + +/test +> Tests still passing: 3/3 ✅ + +[NEXT CYCLE] +/test-gen "remove item from cart" +> AI writes new failing tests... +``` + +#### Example 4: Code Refactoring + +Modernizing legacy code: + +```bash +# Session setup +Codex-flow pair --start \ + --mode driver \ + --focus refactor \ + --verify \ + --threshold 0.98 +``` + +**Session Flow:** +``` +👥 Refactoring Session: Modernizing UserService + +/analyze UserService.js +> AI identifies: + - Callback hell (5 levels deep) + - No error handling + - Tight coupling + - No tests + +/suggest refactoring plan +> AI suggests: + 1. Convert callbacks to async/await + 2. Add error boundaries + 3. Extract dependencies + 4. Add unit tests + +/test-gen --before-refactor +> AI generates tests for current behavior + +/refactor callbacks to async/await +# You refactor with AI guidance + +/test +> All tests passing ✅ + +/review --compare +> AI shows before/after comparison +> Code complexity: 35 → 12 +> Truth score: 0.99 ✅ + +/commit --message "refactor: modernize UserService with async/await" +``` + +#### Example 5: Performance Optimization + +Optimizing slow React application: + +```bash +# Session setup +Codex-flow pair --start \ + --mode switch \ + --agent performance-expert \ + --focus optimize \ + --profile +``` + +**Session Flow:** +``` +👥 Performance Optimization Session + +/perf --profile +> React DevTools Profiler Results: + - ProductList: 450ms render + - CartSummary: 200ms render + - Unnecessary re-renders: 15 + +/suggest optimizations for ProductList +> AI suggests: + 1. Add React.memo + 2. Use useMemo for expensive calculations + 3. Implement virtualization for long lists + +/implement React.memo and useMemo +# You implement with AI guidance + +/perf --profile +> ProductList: 45ms render (90% improvement!) ✅ + +/implement virtualization with react-window +> AI implements virtual scrolling + +/perf --profile +> ProductList: 12ms render (97% improvement!) ✅ +> FPS: 60 stable ✅ + +/commit --message "perf: optimize ProductList with memoization and virtualization" +``` + +#### Example 6: API Development + +Building RESTful API with Express: + +```bash +# Session setup +Codex-flow pair --start \ + --mode navigator \ + --agent backend-expert \ + --focus implement \ + --test +``` + +**Session Flow:** +``` +👥 API Development Session + +/design REST API for blog platform +> AI designs endpoints: + POST /api/posts + GET /api/posts + GET /api/posts/:id + PUT /api/posts/:id + DELETE /api/posts/:id + +/implement CRUD endpoints with validation +> AI implements with Express + Joi validation + +/test-gen --integration +> AI generates integration tests + +/security --api +> AI adds: + - Rate limiting + - Input sanitization + - JWT authentication + - CORS configuration + +/document --openapi +> AI generates OpenAPI documentation + +/test --integration +> All endpoints tested: 15/15 ✅ +``` + +### Session Templates + +#### Quick Start Templates + +```bash +# Refactoring template +Codex-flow pair --template refactor +# Focus: Code improvement +# Verification: High (0.98) +# Testing: After each change +# Review: Continuous + +# Feature template +Codex-flow pair --template feature +# Focus: Implementation +# Verification: Standard (0.95) +# Testing: On completion +# Review: Pre-commit + +# Debug template +Codex-flow pair --template debug +# Focus: Problem solving +# Verification: Moderate (0.90) +# Testing: Regression tests +# Review: Root cause + +# Learning template +Codex-flow pair --template learn +# Mode: Mentor +# Pace: Slow +# Explanations: Detailed +# Examples: Many +``` + +### Session Management + +#### Session Status + +```bash +Codex-flow pair --status +``` + +**Output:** +``` +👥 Pair Programming Session +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Session ID: pair_1755021234567 +Duration: 45 minutes +Status: Active + +Partner: senior-dev +Current Role: DRIVER (you) +Mode: Switch (10m intervals) +Next Switch: in 3 minutes + +📊 Metrics: +├── Truth Score: 0.982 ✅ +├── Lines Changed: 234 +├── Files Modified: 5 +├── Tests Added: 12 +├── Coverage: 87% ↑3% +└── Commits: 3 + +🎯 Focus: Implementation +📝 Current File: src/auth/login.js +``` + +#### Session History + +```bash +Codex-flow pair --history +``` + +**Output:** +``` +📚 Session History +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +1. 2024-01-15 14:30 - 16:45 (2h 15m) + Partner: expert-coder + Focus: Refactoring + Truth Score: 0.975 + Changes: +340 -125 lines + +2. 2024-01-14 10:00 - 11:30 (1h 30m) + Partner: tdd-specialist + Focus: Testing + Truth Score: 0.991 + Tests Added: 24 + +3. 2024-01-13 15:00 - 17:00 (2h) + Partner: debugger-expert + Focus: Bug Fixing + Truth Score: 0.968 + Issues Fixed: 5 +``` + +#### Session Persistence + +```bash +# Save session +Codex-flow pair --save [--name ] + +# Load session +Codex-flow pair --load + +# Export session +Codex-flow pair --export [--format json|md] + +# Generate report +Codex-flow pair --report +``` + +#### Background Sessions + +```bash +# Start in background +Codex-flow pair --start --background + +# Monitor background session +Codex-flow pair --monitor + +# Attach to background session +Codex-flow pair --attach + +# End background session +Codex-flow pair --end +``` + +### Advanced Features + +#### Custom Commands + +Define in configuration: + +```json +{ + "customCommands": { + "tdd": "/test-gen && /test --watch", + "full-review": "/lint --fix && /test && /review --strict", + "quick-fix": "/suggest --type fix && /implement && /test" + } +} +``` + +Use custom commands: +``` +/custom tdd +/custom full-review +``` + +#### Command Chaining + +``` +/test && /commit && /push +/lint --fix && /test && /review --strict +``` + +#### Session Recording + +```bash +# Start with recording +Codex-flow pair --start --record + +# Replay session +Codex-flow pair --replay + +# Session analytics +Codex-flow pair --analytics +``` + +#### Integration Options + +**With Git:** +```bash +Codex-flow pair --start --git --auto-commit +``` + +**With CI/CD:** +```bash +Codex-flow pair --start --ci --non-interactive +``` + +**With IDE:** +```bash +Codex-flow pair --start --ide vscode +``` + +### Best Practices + +#### Session Practices +1. **Clear Goals** - Define session objectives upfront +2. **Appropriate Mode** - Choose based on task type +3. **Enable Verification** - For critical code paths +4. **Regular Testing** - Maintain quality continuously +5. **Session Notes** - Document important decisions +6. **Regular Breaks** - Take breaks every 45-60 minutes + +#### Code Practices +1. **Test Early** - Run tests after each change +2. **Verify Before Commit** - Check truth scores +3. **Review Security** - Always for sensitive code +4. **Profile Performance** - Use `/perf` for optimization +5. **Save Sessions** - For complex work +6. **Learn from AI** - Ask questions frequently + +#### Mode Selection +- **Driver Mode**: When learning, controlling implementation +- **Navigator Mode**: For rapid prototyping, generation +- **Switch Mode**: Long sessions, balanced collaboration +- **TDD Mode**: Building with tests +- **Review Mode**: Quality focus +- **Mentor Mode**: Learning priority +- **Debug Mode**: Fixing issues + +### Troubleshooting + +#### Session Won't Start +- Check agent availability +- Verify configuration file syntax +- Ensure clean workspace +- Review log files + +#### Session Disconnected +- Use `--recover` to restore +- Check network connection +- Verify background processes +- Review auto-save files + +#### Poor Performance +- Reduce verification threshold +- Disable continuous testing +- Check system resources +- Use lighter AI model + +#### Configuration Issues +- Validate JSON syntax +- Check file permissions +- Review priority order (CLI > env > project > user > global) +- Run `Codex-flow pair config validate` + +### Quality Metrics + +#### Truth Score Thresholds +``` +Error: < 0.90 ❌ +Warning: 0.90 - 0.95 ⚠️ +Good: 0.95 - 0.98 ✅ +Excellent: > 0.98 🌟 +``` + +#### Coverage Thresholds +``` +Error: < 70% ❌ +Warning: 70% - 80% ⚠️ +Good: 80% - 90% ✅ +Excellent: > 90% 🌟 +``` + +#### Complexity Thresholds +``` +Error: > 15 ❌ +Warning: 10 - 15 ⚠️ +Good: 5 - 10 ✅ +Excellent: < 5 🌟 +``` + +### Environment Variables + +Override configuration via environment: + +```bash +export CLAUDE_PAIR_MODE=driver +export CLAUDE_PAIR_VERIFY=true +export CLAUDE_PAIR_THRESHOLD=0.98 +export CLAUDE_PAIR_AGENT=senior-dev +export CLAUDE_PAIR_AUTO_TEST=true +``` + +### Command History + +Navigate history: +- `↑/↓` - Navigate through command history +- `Ctrl+R` - Search command history +- `!!` - Repeat last command +- `!` - Run command n from history + +### Keyboard Shortcuts (Configurable) + +Default shortcuts: +```json +{ + "shortcuts": { + "switch": "ctrl+shift+s", + "suggest": "ctrl+space", + "review": "ctrl+r", + "test": "ctrl+t" + } +} +``` + +### Related Commands + +- `Codex-flow pair --help` - Show help +- `Codex-flow pair config` - Manage configuration +- `Codex-flow pair profile` - Manage profiles +- `Codex-flow pair templates` - List templates +- `Codex-flow pair agents` - List available agents diff --git a/.agents/skills/reasoningbank-agentdb/SKILL.md b/.agents/skills/reasoningbank-agentdb/SKILL.md new file mode 100644 index 0000000..08add6f --- /dev/null +++ b/.agents/skills/reasoningbank-agentdb/SKILL.md @@ -0,0 +1,446 @@ +--- +name: "ReasoningBank with AgentDB" +description: "Implement ReasoningBank adaptive learning with AgentDB's 150x faster vector database. Includes trajectory tracking, verdict judgment, memory distillation, and pattern recognition. Use when building self-learning agents, optimizing decision-making, or implementing experience replay systems." +--- + +# ReasoningBank with AgentDB + +## What This Skill Does + +Provides ReasoningBank adaptive learning patterns using AgentDB's high-performance backend (150x-12,500x faster). Enables agents to learn from experiences, judge outcomes, distill memories, and improve decision-making over time with 100% backward compatibility. + +**Performance**: 150x faster pattern retrieval, 500x faster batch operations, <1ms memory access. + +## Prerequisites + +- Node.js 18+ +- AgentDB v1.0.7+ (via agentic-flow) +- Understanding of reinforcement learning concepts (optional) + +--- + +## Quick Start with CLI + +### Initialize ReasoningBank Database + +```bash +# Initialize AgentDB for ReasoningBank +npx agentdb@latest init ./.agentdb/reasoningbank.db --dimension 1536 + +# Start MCP server for Codex integration +npx agentdb@latest mcp +Codex mcp add agentdb npx agentdb@latest mcp +``` + +### Migrate from Legacy ReasoningBank + +```bash +# Automatic migration with validation +npx agentdb@latest migrate --source .swarm/memory.db + +# Verify migration +npx agentdb@latest stats ./.agentdb/reasoningbank.db +``` + +--- + +## Quick Start with API + +```typescript +import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank'; + +// Initialize ReasoningBank with AgentDB +const rb = await createAgentDBAdapter({ + dbPath: '.agentdb/reasoningbank.db', + enableLearning: true, // Enable learning plugins + enableReasoning: true, // Enable reasoning agents + cacheSize: 1000, // 1000 pattern cache +}); + +// Store successful experience +const query = "How to optimize database queries?"; +const embedding = await computeEmbedding(query); + +await rb.insertPattern({ + id: '', + type: 'experience', + domain: 'database-optimization', + pattern_data: JSON.stringify({ + embedding, + pattern: { + query, + approach: 'indexing + query optimization', + outcome: 'success', + metrics: { latency_reduction: 0.85 } + } + }), + confidence: 0.95, + usage_count: 1, + success_count: 1, + created_at: Date.now(), + last_used: Date.now(), +}); + +// Retrieve similar experiences with reasoning +const result = await rb.retrieveWithReasoning(embedding, { + domain: 'database-optimization', + k: 5, + useMMR: true, // Diverse results + synthesizeContext: true, // Rich context synthesis +}); + +console.log('Memories:', result.memories); +console.log('Context:', result.context); +console.log('Patterns:', result.patterns); +``` + +--- + +## Core ReasoningBank Concepts + +### 1. Trajectory Tracking + +Track agent execution paths and outcomes: + +```typescript +// Record trajectory (sequence of actions) +const trajectory = { + task: 'optimize-api-endpoint', + steps: [ + { action: 'analyze-bottleneck', result: 'found N+1 query' }, + { action: 'add-eager-loading', result: 'reduced queries' }, + { action: 'add-caching', result: 'improved latency' } + ], + outcome: 'success', + metrics: { latency_before: 2500, latency_after: 150 } +}; + +const embedding = await computeEmbedding(JSON.stringify(trajectory)); + +await rb.insertPattern({ + id: '', + type: 'trajectory', + domain: 'api-optimization', + pattern_data: JSON.stringify({ embedding, pattern: trajectory }), + confidence: 0.9, + usage_count: 1, + success_count: 1, + created_at: Date.now(), + last_used: Date.now(), +}); +``` + +### 2. Verdict Judgment + +Judge whether a trajectory was successful: + +```typescript +// Retrieve similar past trajectories +const similar = await rb.retrieveWithReasoning(queryEmbedding, { + domain: 'api-optimization', + k: 10, +}); + +// Judge based on similarity to successful patterns +const verdict = similar.memories.filter(m => + m.pattern.outcome === 'success' && + m.similarity > 0.8 +).length > 5 ? 'likely_success' : 'needs_review'; + +console.log('Verdict:', verdict); +console.log('Confidence:', similar.memories[0]?.similarity || 0); +``` + +### 3. Memory Distillation + +Consolidate similar experiences into patterns: + +```typescript +// Get all experiences in domain +const experiences = await rb.retrieveWithReasoning(embedding, { + domain: 'api-optimization', + k: 100, + optimizeMemory: true, // Automatic consolidation +}); + +// Distill into high-level pattern +const distilledPattern = { + domain: 'api-optimization', + pattern: 'For N+1 queries: add eager loading, then cache', + success_rate: 0.92, + sample_size: experiences.memories.length, + confidence: 0.95 +}; + +await rb.insertPattern({ + id: '', + type: 'distilled-pattern', + domain: 'api-optimization', + pattern_data: JSON.stringify({ + embedding: await computeEmbedding(JSON.stringify(distilledPattern)), + pattern: distilledPattern + }), + confidence: 0.95, + usage_count: 0, + success_count: 0, + created_at: Date.now(), + last_used: Date.now(), +}); +``` + +--- + +## Integration with Reasoning Agents + +AgentDB provides 4 reasoning modules that enhance ReasoningBank: + +### 1. PatternMatcher + +Find similar successful patterns: + +```typescript +const result = await rb.retrieveWithReasoning(queryEmbedding, { + domain: 'problem-solving', + k: 10, + useMMR: true, // Maximal Marginal Relevance for diversity +}); + +// PatternMatcher returns diverse, relevant memories +result.memories.forEach(mem => { + console.log(`Pattern: ${mem.pattern.approach}`); + console.log(`Similarity: ${mem.similarity}`); + console.log(`Success Rate: ${mem.success_count / mem.usage_count}`); +}); +``` + +### 2. ContextSynthesizer + +Generate rich context from multiple memories: + +```typescript +const result = await rb.retrieveWithReasoning(queryEmbedding, { + domain: 'code-optimization', + synthesizeContext: true, // Enable context synthesis + k: 5, +}); + +// ContextSynthesizer creates coherent narrative +console.log('Synthesized Context:', result.context); +// "Based on 5 similar optimizations, the most effective approach +// involves profiling, identifying bottlenecks, and applying targeted +// improvements. Success rate: 87%" +``` + +### 3. MemoryOptimizer + +Automatically consolidate and prune: + +```typescript +const result = await rb.retrieveWithReasoning(queryEmbedding, { + domain: 'testing', + optimizeMemory: true, // Enable automatic optimization +}); + +// MemoryOptimizer consolidates similar patterns and prunes low-quality +console.log('Optimizations:', result.optimizations); +// { consolidated: 15, pruned: 3, improved_quality: 0.12 } +``` + +### 4. ExperienceCurator + +Filter by quality and relevance: + +```typescript +const result = await rb.retrieveWithReasoning(queryEmbedding, { + domain: 'debugging', + k: 20, + minConfidence: 0.8, // Only high-confidence experiences +}); + +// ExperienceCurator returns only quality experiences +result.memories.forEach(mem => { + console.log(`Confidence: ${mem.confidence}`); + console.log(`Success Rate: ${mem.success_count / mem.usage_count}`); +}); +``` + +--- + +## Legacy API Compatibility + +AgentDB maintains 100% backward compatibility with legacy ReasoningBank: + +```typescript +import { + retrieveMemories, + judgeTrajectory, + distillMemories +} from 'agentic-flow/reasoningbank'; + +// Legacy API works unchanged (uses AgentDB backend automatically) +const memories = await retrieveMemories(query, { + domain: 'code-generation', + agent: 'coder' +}); + +const verdict = await judgeTrajectory(trajectory, query); + +const newMemories = await distillMemories( + trajectory, + verdict, + query, + { domain: 'code-generation' } +); +``` + +--- + +## Performance Characteristics + +- **Pattern Search**: 150x faster (100µs vs 15ms) +- **Memory Retrieval**: <1ms (with cache) +- **Batch Insert**: 500x faster (2ms vs 1s for 100 patterns) +- **Trajectory Judgment**: <5ms (including retrieval + analysis) +- **Memory Distillation**: <50ms (consolidate 100 patterns) + +--- + +## Advanced Patterns + +### Hierarchical Memory + +Organize memories by abstraction level: + +```typescript +// Low-level: Specific implementation +await rb.insertPattern({ + type: 'concrete', + domain: 'debugging/null-pointer', + pattern_data: JSON.stringify({ + embedding, + pattern: { bug: 'NPE in UserService.getUser()', fix: 'Add null check' } + }), + confidence: 0.9, + // ... +}); + +// Mid-level: Pattern across similar cases +await rb.insertPattern({ + type: 'pattern', + domain: 'debugging', + pattern_data: JSON.stringify({ + embedding, + pattern: { category: 'null-pointer', approach: 'defensive-checks' } + }), + confidence: 0.85, + // ... +}); + +// High-level: General principle +await rb.insertPattern({ + type: 'principle', + domain: 'software-engineering', + pattern_data: JSON.stringify({ + embedding, + pattern: { principle: 'fail-fast with clear errors' } + }), + confidence: 0.95, + // ... +}); +``` + +### Multi-Domain Learning + +Transfer learning across domains: + +```typescript +// Learn from backend optimization +const backendExperience = await rb.retrieveWithReasoning(embedding, { + domain: 'backend-optimization', + k: 10, +}); + +// Apply to frontend optimization +const transferredKnowledge = backendExperience.memories.map(mem => ({ + ...mem, + domain: 'frontend-optimization', + adapted: true, +})); +``` + +--- + +## CLI Operations + +### Database Management + +```bash +# Export trajectories and patterns +npx agentdb@latest export ./.agentdb/reasoningbank.db ./backup.json + +# Import experiences +npx agentdb@latest import ./experiences.json + +# Get statistics +npx agentdb@latest stats ./.agentdb/reasoningbank.db +# Shows: total patterns, domains, confidence distribution +``` + +### Migration + +```bash +# Migrate from legacy ReasoningBank +npx agentdb@latest migrate --source .swarm/memory.db --target .agentdb/reasoningbank.db + +# Validate migration +npx agentdb@latest stats .agentdb/reasoningbank.db +``` + +--- + +## Troubleshooting + +### Issue: Migration fails +```bash +# Check source database exists +ls -la .swarm/memory.db + +# Run with verbose logging +DEBUG=agentdb:* npx agentdb@latest migrate --source .swarm/memory.db +``` + +### Issue: Low confidence scores +```typescript +// Enable context synthesis for better quality +const result = await rb.retrieveWithReasoning(embedding, { + synthesizeContext: true, + useMMR: true, + k: 10, +}); +``` + +### Issue: Memory growing too large +```typescript +// Enable automatic optimization +const result = await rb.retrieveWithReasoning(embedding, { + optimizeMemory: true, // Consolidates similar patterns +}); + +// Or manually optimize +await rb.optimize(); +``` + +--- + +## Learn More + +- **AgentDB Integration**: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md +- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb +- **MCP Integration**: `npx agentdb@latest mcp` +- **Website**: https://agentdb.ruv.io + +--- + +**Category**: Machine Learning / Reinforcement Learning +**Difficulty**: Intermediate +**Estimated Time**: 20-30 minutes diff --git a/.agents/skills/reasoningbank-intelligence/SKILL.md b/.agents/skills/reasoningbank-intelligence/SKILL.md new file mode 100644 index 0000000..bf3e845 --- /dev/null +++ b/.agents/skills/reasoningbank-intelligence/SKILL.md @@ -0,0 +1,201 @@ +--- +name: "ReasoningBank Intelligence" +description: "Implement adaptive learning with ReasoningBank for pattern recognition, strategy optimization, and continuous improvement. Use when building self-learning agents, optimizing workflows, or implementing meta-cognitive systems." +--- + +# ReasoningBank Intelligence + +## What This Skill Does + +Implements ReasoningBank's adaptive learning system for AI agents to learn from experience, recognize patterns, and optimize strategies over time. Enables meta-cognitive capabilities and continuous improvement. + +## Prerequisites + +- agentic-flow v3.0.0-alpha.1+ +- AgentDB v3.0.0-alpha.10+ (for persistence) +- Node.js 18+ + +## Quick Start + +```typescript +import { ReasoningBank } from 'agentic-flow/reasoningbank'; + +// Initialize ReasoningBank +const rb = new ReasoningBank({ + persist: true, + learningRate: 0.1, + adapter: 'agentdb' // Use AgentDB for storage +}); + +// Record task outcome +await rb.recordExperience({ + task: 'code_review', + approach: 'static_analysis_first', + outcome: { + success: true, + metrics: { + bugs_found: 5, + time_taken: 120, + false_positives: 1 + } + }, + context: { + language: 'typescript', + complexity: 'medium' + } +}); + +// Get optimal strategy +const strategy = await rb.recommendStrategy('code_review', { + language: 'typescript', + complexity: 'high' +}); +``` + +## Core Features + +### 1. Pattern Recognition +```typescript +// Learn patterns from data +await rb.learnPattern({ + pattern: 'api_errors_increase_after_deploy', + triggers: ['deployment', 'traffic_spike'], + actions: ['rollback', 'scale_up'], + confidence: 0.85 +}); + +// Match patterns +const matches = await rb.matchPatterns(currentSituation); +``` + +### 2. Strategy Optimization +```typescript +// Compare strategies +const comparison = await rb.compareStrategies('bug_fixing', [ + 'tdd_approach', + 'debug_first', + 'reproduce_then_fix' +]); + +// Get best strategy +const best = comparison.strategies[0]; +console.log(`Best: ${best.name} (score: ${best.score})`); +``` + +### 3. Continuous Learning +```typescript +// Enable auto-learning from all tasks +await rb.enableAutoLearning({ + threshold: 0.7, // Only learn from high-confidence outcomes + updateFrequency: 100 // Update models every 100 experiences +}); +``` + +## Advanced Usage + +### Meta-Learning +```typescript +// Learn about learning +await rb.metaLearn({ + observation: 'parallel_execution_faster_for_independent_tasks', + confidence: 0.95, + applicability: { + task_types: ['batch_processing', 'data_transformation'], + conditions: ['tasks_independent', 'io_bound'] + } +}); +``` + +### Transfer Learning +```typescript +// Apply knowledge from one domain to another +await rb.transferKnowledge({ + from: 'code_review_javascript', + to: 'code_review_typescript', + similarity: 0.8 +}); +``` + +### Adaptive Agents +```typescript +// Create self-improving agent +class AdaptiveAgent { + async execute(task: Task) { + // Get optimal strategy + const strategy = await rb.recommendStrategy(task.type, task.context); + + // Execute with strategy + const result = await this.executeWithStrategy(task, strategy); + + // Learn from outcome + await rb.recordExperience({ + task: task.type, + approach: strategy.name, + outcome: result, + context: task.context + }); + + return result; + } +} +``` + +## Integration with AgentDB + +```typescript +// Persist ReasoningBank data +await rb.configure({ + storage: { + type: 'agentdb', + options: { + database: './reasoning-bank.db', + enableVectorSearch: true + } + } +}); + +// Query learned patterns +const patterns = await rb.query({ + category: 'optimization', + minConfidence: 0.8, + timeRange: { last: '30d' } +}); +``` + +## Performance Metrics + +```typescript +// Track learning effectiveness +const metrics = await rb.getMetrics(); +console.log(` + Total Experiences: ${metrics.totalExperiences} + Patterns Learned: ${metrics.patternsLearned} + Strategy Success Rate: ${metrics.strategySuccessRate} + Improvement Over Time: ${metrics.improvement} +`); +``` + +## Best Practices + +1. **Record consistently**: Log all task outcomes, not just successes +2. **Provide context**: Rich context improves pattern matching +3. **Set thresholds**: Filter low-confidence learnings +4. **Review periodically**: Audit learned patterns for quality +5. **Use vector search**: Enable semantic pattern matching + +## Troubleshooting + +### Issue: Poor recommendations +**Solution**: Ensure sufficient training data (100+ experiences per task type) + +### Issue: Slow pattern matching +**Solution**: Enable vector indexing in AgentDB + +### Issue: Memory growing large +**Solution**: Set TTL for old experiences or enable pruning + +## Learn More + +- ReasoningBank Guide: agentic-flow/src/reasoningbank/README.md +- AgentDB Integration: packages/agentdb/docs/reasoningbank.md +- Pattern Learning: docs/reasoning/patterns.md diff --git a/.agents/skills/skill-builder/SKILL.md b/.agents/skills/skill-builder/SKILL.md new file mode 100644 index 0000000..8849c62 --- /dev/null +++ b/.agents/skills/skill-builder/SKILL.md @@ -0,0 +1,910 @@ +--- +name: "Skill Builder" +description: "Create new Codex Skills with proper YAML frontmatter, progressive disclosure structure, and complete directory organization. Use when you need to build custom skills for specific workflows, generate skill templates, or understand the Codex Skills specification." +--- + +# Skill Builder + +## What This Skill Does + +Creates production-ready Codex Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file/folder structure. This skill guides you through building skills that Codex can autonomously discover and use across all surfaces (Codex.ai, Codex, SDK, API). + +## Prerequisites + +- Codex 2.0+ or Codex.ai with Skills support +- Basic understanding of Markdown and YAML +- Text editor or IDE + +## Quick Start + +### Creating Your First Skill + +```bash +# 1. Create skill directory (MUST be at top level, NOT in subdirectories!) +mkdir -p ~/.Codex/skills/my-first-skill + +# 2. Create SKILL.md with proper format +cat > ~/.Codex/skills/my-first-skill/SKILL.md << 'EOF' +--- +name: "My First Skill" +description: "Brief description of what this skill does and when Codex should use it. Maximum 1024 characters." +--- + +# My First Skill + +## What This Skill Does +[Your instructions here] + +## Quick Start +[Basic usage] +EOF + +# 3. Verify skill is detected +# Restart Codex or refresh Codex.ai +``` + +--- + +## Complete Specification + +### 📋 YAML Frontmatter (REQUIRED) + +Every SKILL.md **must** start with YAML frontmatter containing exactly two required fields: + +```yaml +--- +name: "Skill Name" # REQUIRED: Max 64 chars +description: "What this skill does # REQUIRED: Max 1024 chars +and when Codex should use it." # Include BOTH what & when +--- +``` + +#### Field Requirements + +**`name`** (REQUIRED): +- **Type**: String +- **Max Length**: 64 characters +- **Format**: Human-friendly display name +- **Usage**: Shown in skill lists, UI, and loaded into Codex's system prompt +- **Best Practice**: Use Title Case, be concise and descriptive +- **Examples**: + - ✅ "API Documentation Generator" + - ✅ "React Component Builder" + - ✅ "Database Schema Designer" + - ❌ "skill-1" (not descriptive) + - ❌ "This is a very long skill name that exceeds sixty-four characters" (too long) + +**`description`** (REQUIRED): +- **Type**: String +- **Max Length**: 1024 characters +- **Format**: Plain text or minimal markdown +- **Content**: MUST include: + 1. **What** the skill does (functionality) + 2. **When** Codex should invoke it (trigger conditions) +- **Usage**: Loaded into Codex's system prompt for autonomous matching +- **Best Practice**: Front-load key trigger words, be specific about use cases +- **Examples**: + - ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications." + - ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components." + - ❌ "A comprehensive guide to API documentation" (no "when" clause) + - ❌ "Documentation tool" (too vague) + +#### YAML Formatting Rules + +```yaml +--- +# ✅ CORRECT: Simple string +name: "API Builder" +description: "Creates REST APIs with Express and TypeScript." + +# ✅ CORRECT: Multi-line description +name: "Full-Stack Generator" +description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications." + +# ✅ CORRECT: Special characters quoted +name: "JSON:API Builder" +description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships." + +# ❌ WRONG: Missing quotes with special chars +name: API:Builder # YAML parse error! + +# ❌ WRONG: Extra fields (ignored but discouraged) +name: "My Skill" +description: "My description" +version: "1.0.0" # NOT part of spec +author: "Me" # NOT part of spec +tags: ["dev", "api"] # NOT part of spec +--- +``` + +**Critical**: Only `name` and `description` are used by Codex. Additional fields are ignored. + +--- + +### 📂 Directory Structure + +#### Minimal Skill (Required) +``` +~/.Codex/skills/ # Personal skills location +└── my-skill/ # Skill directory (MUST be at top level!) + └── SKILL.md # REQUIRED: Main skill file +``` + +**IMPORTANT**: Skills MUST be directly under `~/.Codex/skills/[skill-name]/`. +Codex does NOT support nested subdirectories or namespaces! + +#### Full-Featured Skill (Recommended) +``` +~/.Codex/skills/ +└── my-skill/ # Top-level skill directory + ├── SKILL.md # REQUIRED: Main skill file + ├── README.md # Optional: Human-readable docs + ├── scripts/ # Optional: Executable scripts + │ ├── setup.sh + │ ├── validate.js + │ └── deploy.py + ├── resources/ # Optional: Supporting files + │ ├── templates/ + │ │ ├── api-template.js + │ │ └── component.tsx + │ ├── examples/ + │ │ └── sample-output.json + │ └── schemas/ + │ └── config-schema.json + └── docs/ # Optional: Additional documentation + ├── ADVANCED.md + ├── TROUBLESHOOTING.md + └── API_REFERENCE.md +``` + +#### Skills Locations + +**Personal Skills** (available across all projects): +``` +~/.Codex/skills/ +└── [your-skills]/ +``` +- **Path**: `~/.Codex/skills/` or `$HOME/.Codex/skills/` +- **Scope**: Available in all projects for this user +- **Version Control**: NOT committed to git (outside repo) +- **Use Case**: Personal productivity tools, custom workflows + +**Project Skills** (team-shared, version controlled): +``` +/.Codex/skills/ +└── [team-skills]/ +``` +- **Path**: `.Codex/skills/` in project root +- **Scope**: Available only in this project +- **Version Control**: SHOULD be committed to git +- **Use Case**: Team workflows, project-specific tools, shared knowledge + +--- + +### 🎯 Progressive Disclosure Architecture + +Codex uses a **3-level progressive disclosure system** to scale to 100+ skills without context penalty: + +#### Level 1: Metadata (Name + Description) +**Loaded**: At Codex startup, always +**Size**: ~200 chars per skill +**Purpose**: Enable autonomous skill matching +**Context**: Loaded into system prompt for ALL skills + +```yaml +--- +name: "API Builder" # 11 chars +description: "Creates REST APIs..." # ~50 chars +--- +# Total: ~61 chars per skill +# 100 skills = ~6KB context (minimal!) +``` + +#### Level 2: SKILL.md Body +**Loaded**: When skill is triggered/matched +**Size**: ~1-10KB typically +**Purpose**: Main instructions and procedures +**Context**: Only loaded for ACTIVE skills + +```markdown +# API Builder + +## What This Skill Does +[Main instructions - loaded only when skill is active] + +## Quick Start +[Basic procedures] + +## Step-by-Step Guide +[Detailed instructions] +``` + +#### Level 3+: Referenced Files +**Loaded**: On-demand as Codex navigates +**Size**: Variable (KB to MB) +**Purpose**: Deep reference, examples, schemas +**Context**: Loaded only when Codex accesses specific files + +```markdown +# In SKILL.md +See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. +See [API Reference](docs/API_REFERENCE.md) for complete documentation. +Use template: `resources/templates/api-template.js` + +# Codex will load these files ONLY if needed +``` + +**Benefit**: Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context. + +--- + +### 📝 SKILL.md Content Structure + +#### Recommended 4-Level Structure + +```markdown +--- +name: "Your Skill Name" +description: "What it does and when to use it" +--- + +# Your Skill Name + +## Level 1: Overview (Always Read First) +Brief 2-3 sentence description of the skill. + +## Prerequisites +- Requirement 1 +- Requirement 2 + +## What This Skill Does +1. Primary function +2. Secondary function +3. Key benefit + +--- + +## Level 2: Quick Start (For Fast Onboarding) + +### Basic Usage +```bash +# Simplest use case +command --option value +``` + +### Common Scenarios +1. **Scenario 1**: How to... +2. **Scenario 2**: How to... + +--- + +## Level 3: Detailed Instructions (For Deep Work) + +### Step-by-Step Guide + +#### Step 1: Initial Setup +```bash +# Commands +``` +Expected output: +``` +Success message +``` + +#### Step 2: Configuration +- Configuration option 1 +- Configuration option 2 + +#### Step 3: Execution +- Run the main command +- Verify results + +### Advanced Options + +#### Option 1: Custom Configuration +```bash +# Advanced usage +``` + +#### Option 2: Integration +```bash +# Integration steps +``` + +--- + +## Level 4: Reference (Rarely Needed) + +### Troubleshooting + +#### Issue: Common Problem +**Symptoms**: What you see +**Cause**: Why it happens +**Solution**: How to fix +```bash +# Fix command +``` + +#### Issue: Another Problem +**Solution**: Steps to resolve + +### Complete API Reference +See [API_REFERENCE.md](docs/API_REFERENCE.md) + +### Examples +See [examples/](resources/examples/) + +### Related Skills +- [Related Skill 1](#) +- [Related Skill 2](#) + +### Resources +- [External Link 1](https://example.com) +- [Documentation](https://docs.example.com) +``` + +--- + +### 🎨 Content Best Practices + +#### Writing Effective Descriptions + +**Front-Load Keywords**: +```yaml +# ✅ GOOD: Keywords first +description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients." + +# ❌ BAD: Keywords buried +description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces." +``` + +**Include Trigger Conditions**: +```yaml +# ✅ GOOD: Clear "when" clause +description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size." + +# ❌ BAD: No trigger conditions +description: "Helps with React performance debugging." +``` + +**Be Specific**: +```yaml +# ✅ GOOD: Specific technologies +description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints." + +# ❌ BAD: Too generic +description: "Build API endpoints with proper validation and testing." +``` + +#### Progressive Disclosure Writing + +**Keep Level 1 Brief** (Overview): +```markdown +## What This Skill Does +Creates production-ready React components with TypeScript, hooks, and tests in 3 steps. +``` + +**Level 2 for Common Paths** (Quick Start): +```markdown +## Quick Start +```bash +# Most common use case (80% of users) +generate-component MyComponent +``` +``` + +**Level 3 for Details** (Step-by-Step): +```markdown +## Step-by-Step Guide + +### Creating a Basic Component +1. Run generator +2. Choose template +3. Customize options +[Detailed explanations] +``` + +**Level 4 for Edge Cases** (Reference): +```markdown +## Advanced Configuration +For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md). +``` + +--- + +### 🛠️ Adding Scripts and Resources + +#### Scripts Directory + +**Purpose**: Executable scripts that Codex can run +**Location**: `scripts/` in skill directory +**Usage**: Referenced from SKILL.md + +Example: +```bash +# In skill directory +scripts/ +├── setup.sh # Initialization script +├── validate.js # Validation logic +├── generate.py # Code generation +└── deploy.sh # Deployment script +``` + +Reference from SKILL.md: +```markdown +## Setup +Run the setup script: +```bash +./scripts/setup.sh +``` + +## Validation +Validate your configuration: +```bash +node scripts/validate.js config.json +``` +``` + +#### Resources Directory + +**Purpose**: Templates, examples, schemas, static files +**Location**: `resources/` in skill directory +**Usage**: Referenced or copied by scripts + +Example: +```bash +resources/ +├── templates/ +│ ├── component.tsx.template +│ ├── test.spec.ts.template +│ └── story.stories.tsx.template +├── examples/ +│ ├── basic-example/ +│ ├── advanced-example/ +│ └── integration-example/ +└── schemas/ + ├── config.schema.json + └── output.schema.json +``` + +Reference from SKILL.md: +```markdown +## Templates +Use the component template: +```bash +cp resources/templates/component.tsx.template src/components/MyComponent.tsx +``` + +## Examples +See working examples in `resources/examples/`: +- `basic-example/` - Simple component +- `advanced-example/` - With hooks and context +``` + +--- + +### 🔗 File References and Navigation + +Codex can navigate to referenced files automatically. Use these patterns: + +#### Markdown Links +```markdown +See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. +See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors. +``` + +#### Relative File Paths +```markdown +Use the template located at `resources/templates/api-template.js` +See examples in `resources/examples/basic-usage/` +``` + +#### Inline File Content +```markdown +## Example Configuration +See `resources/examples/config.json`: +```json +{ + "option": "value" +} +``` +``` + +**Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Codex will load only what's needed. + +--- + +### ✅ Validation Checklist + +Before publishing a skill, verify: + +**YAML Frontmatter**: +- [ ] Starts with `---` +- [ ] Contains `name` field (max 64 chars) +- [ ] Contains `description` field (max 1024 chars) +- [ ] Description includes "what" and "when" +- [ ] Ends with `---` +- [ ] No YAML syntax errors + +**File Structure**: +- [ ] SKILL.md exists in skill directory +- [ ] Directory is DIRECTLY in `~/.Codex/skills/[skill-name]/` or `.Codex/skills/[skill-name]/` +- [ ] Uses clear, descriptive directory name +- [ ] **NO nested subdirectories** (Codex requires top-level structure) + +**Content Quality**: +- [ ] Level 1 (Overview) is brief and clear +- [ ] Level 2 (Quick Start) shows common use case +- [ ] Level 3 (Details) provides step-by-step guide +- [ ] Level 4 (Reference) links to advanced content +- [ ] Examples are concrete and runnable +- [ ] Troubleshooting section addresses common issues + +**Progressive Disclosure**: +- [ ] Core instructions in SKILL.md (~2-5KB) +- [ ] Advanced content in separate docs/ +- [ ] Large resources in resources/ directory +- [ ] Clear navigation between levels + +**Testing**: +- [ ] Skill appears in Codex's skill list +- [ ] Description triggers on relevant queries +- [ ] Instructions are clear and actionable +- [ ] Scripts execute successfully (if included) +- [ ] Examples work as documented + +--- + +## Skill Builder Templates + +### Template 1: Basic Skill (Minimal) + +```markdown +--- +name: "My Basic Skill" +description: "One sentence what. One sentence when to use." +--- + +# My Basic Skill + +## What This Skill Does +[2-3 sentences describing functionality] + +## Quick Start +```bash +# Single command to get started +``` + +## Step-by-Step Guide + +### Step 1: Setup +[Instructions] + +### Step 2: Usage +[Instructions] + +### Step 3: Verify +[Instructions] + +## Troubleshooting +- **Issue**: Problem description + - **Solution**: Fix description +``` + +### Template 2: Intermediate Skill (With Scripts) + +```markdown +--- +name: "My Intermediate Skill" +description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building." +--- + +# My Intermediate Skill + +## Prerequisites +- Requirement 1 +- Requirement 2 + +## What This Skill Does +1. Primary function +2. Secondary function +3. Integration capability + +## Quick Start +```bash +./scripts/setup.sh +./scripts/generate.sh my-project +``` + +## Configuration +Edit `config.json`: +```json +{ + "option1": "value1", + "option2": "value2" +} +``` + +## Step-by-Step Guide + +### Basic Usage +[Steps for 80% use case] + +### Advanced Usage +[Steps for complex scenarios] + +## Available Scripts +- `scripts/setup.sh` - Initial setup +- `scripts/generate.sh` - Code generation +- `scripts/validate.sh` - Validation + +## Resources +- Templates: `resources/templates/` +- Examples: `resources/examples/` + +## Troubleshooting +[Common issues and solutions] +``` + +### Template 3: Advanced Skill (Full-Featured) + +```markdown +--- +name: "My Advanced Skill" +description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]." +--- + +# My Advanced Skill + +## Overview +[Brief 2-3 sentence description] + +## Prerequisites +- Technology 1 (version X+) +- Technology 2 (version Y+) +- API keys or credentials + +## What This Skill Does +1. **Core Feature**: Description +2. **Integration**: Description +3. **Automation**: Description + +--- + +## Quick Start (60 seconds) + +### Installation +```bash +./scripts/install.sh +``` + +### First Use +```bash +./scripts/quickstart.sh +``` + +Expected output: +``` +✓ Setup complete +✓ Configuration validated +→ Ready to use +``` + +--- + +## Configuration + +### Basic Configuration +Edit `config.json`: +```json +{ + "mode": "production", + "features": ["feature1", "feature2"] +} +``` + +### Advanced Configuration +See [Configuration Guide](docs/CONFIGURATION.md) + +--- + +## Step-by-Step Guide + +### 1. Initial Setup +[Detailed steps] + +### 2. Core Workflow +[Main procedures] + +### 3. Integration +[Integration steps] + +--- + +## Advanced Features + +### Feature 1: Custom Templates +```bash +./scripts/generate.sh --template custom +``` + +### Feature 2: Batch Processing +```bash +./scripts/batch.sh --input data.json +``` + +### Feature 3: CI/CD Integration +See [CI/CD Guide](docs/CICD.md) + +--- + +## Scripts Reference + +| Script | Purpose | Usage | +|--------|---------|-------| +| `install.sh` | Install dependencies | `./scripts/install.sh` | +| `generate.sh` | Generate code | `./scripts/generate.sh [name]` | +| `validate.sh` | Validate output | `./scripts/validate.sh` | +| `deploy.sh` | Deploy to environment | `./scripts/deploy.sh [env]` | + +--- + +## Resources + +### Templates +- `resources/templates/basic.template` - Basic template +- `resources/templates/advanced.template` - Advanced template + +### Examples +- `resources/examples/basic/` - Simple example +- `resources/examples/advanced/` - Complex example +- `resources/examples/integration/` - Integration example + +### Schemas +- `resources/schemas/config.schema.json` - Configuration schema +- `resources/schemas/output.schema.json` - Output validation + +--- + +## Troubleshooting + +### Issue: Installation Failed +**Symptoms**: Error during `install.sh` +**Cause**: Missing dependencies +**Solution**: +```bash +# Install prerequisites +npm install -g required-package +./scripts/install.sh --force +``` + +### Issue: Validation Errors +**Symptoms**: Validation script fails +**Solution**: See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) + +--- + +## API Reference +Complete API documentation: [API_REFERENCE.md](docs/API_REFERENCE.md) + +## Related Skills +- [Related Skill 1](../related-skill-1/) +- [Related Skill 2](../related-skill-2/) + +## Resources +- [Official Documentation](https://example.com/docs) +- [GitHub Repository](https://github.com/example/repo) +- [Community Forum](https://forum.example.com) + +--- + +**Created**: 2025-10-19 +**Category**: Advanced +**Difficulty**: Intermediate +**Estimated Time**: 15-30 minutes +``` + +--- + +## Examples from the Wild + +### Example 1: Simple Documentation Skill + +```markdown +--- +name: "README Generator" +description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs." +--- + +# README Generator + +## What This Skill Does +Creates well-structured README.md files with badges, installation, usage, and contribution sections. + +## Quick Start +```bash +# Answer a few questions +./scripts/generate-readme.sh + +# README.md created with: +# - Project title and description +# - Installation instructions +# - Usage examples +# - Contribution guidelines +``` + +## Customization +Edit sections in `resources/templates/sections/` before generating. +``` + +### Example 2: Code Generation Skill + +```markdown +--- +name: "React Component Generator" +description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns." +--- + +# React Component Generator + +## Prerequisites +- Node.js 18+ +- React 18+ +- TypeScript 5+ + +## Quick Start +```bash +./scripts/generate-component.sh MyComponent + +# Creates: +# - src/components/MyComponent/MyComponent.tsx +# - src/components/MyComponent/MyComponent.test.tsx +# - src/components/MyComponent/MyComponent.stories.tsx +# - src/components/MyComponent/index.ts +``` + +## Step-by-Step Guide + +### 1. Run Generator +```bash +./scripts/generate-component.sh ComponentName +``` + +### 2. Choose Template +- Basic: Simple functional component +- With State: useState hooks +- With Context: useContext integration +- With API: Data fetching component + +### 3. Customize +Edit generated files in `src/components/ComponentName/` + +## Templates +See `resources/templates/` for available component templates. +``` + +--- + +## Learn More + +### Official Resources +- [Anthropic Agent Skills Documentation](https://docs.Codex.com/en/docs/agents-and-tools/agent-skills) +- [GitHub Skills Repository](https://github.com/anthropics/skills) +- [Codex Documentation](https://docs.Codex.com/en/docs/Codex) + +### Community +- [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills +- [Anthropic Discord](https://discord.gg/anthropic) - Get help from community + +### Advanced Topics +- Multi-file skills with complex navigation +- Skills that spawn other skills +- Integration with MCP tools +- Dynamic skill generation + +--- + +**Created**: 2025-10-19 +**Version**: 1.0.0 +**Maintained By**: agentic-flow team +**License**: MIT diff --git a/.agents/skills/soft-delete-relogin-consistency/SKILL.md b/.agents/skills/soft-delete-relogin-consistency/SKILL.md new file mode 100644 index 0000000..5ed1e94 --- /dev/null +++ b/.agents/skills/soft-delete-relogin-consistency/SKILL.md @@ -0,0 +1,144 @@ +--- +name: soft-delete-relogin-consistency +description: | + Fix for missing auth/identity records after account deletion + device re-login. + Use when: (1) User deletes account but device records are intentionally kept + (e.g., to prevent trial abuse), (2) Re-login via device succeeds but user + appears to have wrong identity type, (3) Frontend shows incorrect UI because + auth_methods or similar identity records are empty/wrong after re-login, + (4) Soft-deleted records cause stale cache entries that misrepresent user state. + Covers GORM soft-delete, device-based auth, cache invalidation after re-creation. +author: Codex +version: 1.0.0 +date: 2026-03-11 +--- + +# Soft-Delete + Re-Login Auth Consistency + +## Problem + +When a system uses soft-delete for auth/identity records during account deletion but +intentionally keeps primary records (like device records) for abuse prevention, re-login +flows may succeed at the "find existing record" step but fail to re-create the +soft-deleted identity records. This causes the user to exist in an inconsistent state +where they're authenticated but missing critical identity metadata. + +## Context / Trigger Conditions + +- Account deletion (注销) soft-deletes `auth_methods` (or equivalent identity records) +- Device/hardware records are intentionally kept to prevent trial reward abuse +- Device-based re-login finds existing device record -> reuses old user_id +- But the "device found" code path skips identity record creation (only the + "device not found" registration path creates them) +- Result: User is logged in but `auth_methods` is empty or missing the expected type +- Frontend UI breaks because it relies on `auth_methods[0].auth_type` to determine + login mode and show/hide UI elements + +### Symptoms + +- Buttons or UI elements that should be hidden for device-only users appear after + account deletion + re-login +- API returns user info with empty or unexpected `auth_methods` array +- `isDeviceLogin()` or similar identity checks return wrong results +- Cache returns stale user data even after re-login + +## Solution + +### Step 1: Identify the re-login code path + +Find the "device found" branch in the login logic. This is the code path that runs +when a device record already exists (as opposed to the registration path). + +### Step 2: Add identity record existence check + +After finding the user via device record, check if the expected identity record exists: + +```go +// After finding user via existing device record +hasDeviceAuth := false +for _, am := range userInfo.AuthMethods { + if am.AuthType == "device" && am.AuthIdentifier == req.Identifier { + hasDeviceAuth = true + break + } +} +if !hasDeviceAuth { + // Re-create the soft-deleted auth record + authMethod := &user.AuthMethods{ + UserId: userInfo.Id, + AuthType: "device", + AuthIdentifier: req.Identifier, + Verified: true, + } + if createErr := db.Create(authMethod).Error; createErr != nil { + log.Error("re-create auth method failed", err) + } else { + // CRITICAL: Clear user cache so subsequent reads return updated data + _ = userModel.ClearUserCache(ctx, userInfo) + } +} +``` + +### Step 3: Ensure cache invalidation + +After re-creating the identity record, clear the user cache. This is critical because +cached user data (with `Preload("AuthMethods")`) will still show the old empty state +until the cache is invalidated. + +### Step 4: Verify GORM soft-delete behavior + +GORM's soft-delete (`deleted_at IS NULL` filter) means: +- `Preload("AuthMethods")` will NOT return soft-deleted records +- `db.Create()` will create a NEW record (not undelete the old one) +- The old soft-deleted record remains in the database (harmless) + +## Verification + +1. Delete account (注销) +2. Re-login via device +3. Call user info API - verify `auth_methods` contains the device type +4. Check frontend UI - verify device-specific UI state is correct + +## Example + +**Before fix:** +``` +1. User has auth_methods: [device_A, email_A] +2. User deletes account -> auth_methods all soft-deleted +3. Device record kept (abuse prevention) +4. User re-logins via same device +5. FindOneDeviceByIdentifier finds device -> reuses user_id +6. FindOne returns user with AuthMethods=[] (soft-deleted, filtered out) +7. Frontend: isDeviceLogin() = false (no auth_methods) -> shows wrong buttons +``` + +**After fix:** +``` +1-4. Same as above +5. FindOneDeviceByIdentifier finds device -> reuses user_id +6. FindOne returns user with AuthMethods=[] +7. NEW: Detects missing device auth_method, re-creates it, clears cache +8. Frontend: isDeviceLogin() = true -> correct UI +``` + +## Notes + +- This pattern applies broadly to any system where: + - Account deletion removes identity records but keeps usage records + - Re-login can succeed via the usage records + - UI/business logic depends on the identity records existing +- The "don't delete device records" design is intentional for preventing abuse + (e.g., users repeatedly deleting and re-creating accounts to get trial rewards) +- Cache invalidation is the most commonly missed step - without it, the fix appears + to not work because cached data is served until TTL expires +- Consider whether `Unscoped()` (GORM) should be used to also query soft-deleted + records, or whether re-creation is the better approach (usually re-creation is + cleaner as it creates a fresh record with correct timestamps) + +## Related Patterns + +- **Cache key dependency chains**: When `ClearUserCache` depends on `AuthMethods` + to generate email cache keys, capture auth_methods BEFORE deletion, then explicitly + clear derived cache keys after the transaction +- **Family ownership transfer**: When an owner exits a shared resource group, transfer + ownership to a remaining member instead of dissolving the group diff --git a/.agents/skills/stream-chain/SKILL.md b/.agents/skills/stream-chain/SKILL.md new file mode 100644 index 0000000..14333dd --- /dev/null +++ b/.agents/skills/stream-chain/SKILL.md @@ -0,0 +1,563 @@ +--- +name: stream-chain +description: Stream-JSON chaining for multi-agent pipelines, data transformation, and sequential workflows +version: 1.0.0 +category: workflow +tags: [streaming, pipeline, chaining, multi-agent, workflow] +--- + +# Stream-Chain Skill + +Execute sophisticated multi-step workflows where each agent's output flows into the next, enabling complex data transformations and sequential processing pipelines. + +## Overview + +Stream-Chain provides two powerful modes for orchestrating multi-agent workflows: + +1. **Custom Chains** (`run`): Execute custom prompt sequences with full control +2. **Predefined Pipelines** (`pipeline`): Use battle-tested workflows for common tasks + +Each step in a chain receives the complete output from the previous step, enabling sophisticated multi-agent coordination through streaming data flow. + +--- + +## Quick Start + +### Run a Custom Chain + +```bash +Codex-flow stream-chain run \ + "Analyze codebase structure" \ + "Identify improvement areas" \ + "Generate action plan" +``` + +### Execute a Pipeline + +```bash +Codex-flow stream-chain pipeline analysis +``` + +--- + +## Custom Chains (`run`) + +Execute custom stream chains with your own prompts for maximum flexibility. + +### Syntax + +```bash +Codex-flow stream-chain run [...] [options] +``` + +**Requirements:** +- Minimum 2 prompts required +- Each prompt becomes a step in the chain +- Output flows sequentially through all steps + +### Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--verbose` | Show detailed execution information | `false` | +| `--timeout ` | Timeout per step | `30` | +| `--debug` | Enable debug mode with full logging | `false` | + +### How Context Flows + +Each step receives the previous output as context: + +``` +Step 1: "Write a sorting function" +Output: [function implementation] + +Step 2 receives: + "Previous step output: + [function implementation] + + Next task: Add comprehensive tests" + +Step 3 receives: + "Previous steps output: + [function + tests] + + Next task: Optimize performance" +``` + +### Examples + +#### Basic Development Chain + +```bash +Codex-flow stream-chain run \ + "Write a user authentication function" \ + "Add input validation and error handling" \ + "Create unit tests with edge cases" +``` + +#### Security Audit Workflow + +```bash +Codex-flow stream-chain run \ + "Analyze authentication system for vulnerabilities" \ + "Identify and categorize security issues by severity" \ + "Propose fixes with implementation priority" \ + "Generate security test cases" \ + --timeout 45 \ + --verbose +``` + +#### Code Refactoring Chain + +```bash +Codex-flow stream-chain run \ + "Identify code smells in src/ directory" \ + "Create refactoring plan with specific changes" \ + "Apply refactoring to top 3 priority items" \ + "Verify refactored code maintains behavior" \ + --debug +``` + +#### Data Processing Pipeline + +```bash +Codex-flow stream-chain run \ + "Extract data from API responses" \ + "Transform data into normalized format" \ + "Validate data against schema" \ + "Generate data quality report" +``` + +--- + +## Predefined Pipelines (`pipeline`) + +Execute battle-tested workflows optimized for common development tasks. + +### Syntax + +```bash +Codex-flow stream-chain pipeline [options] +``` + +### Available Pipelines + +#### 1. Analysis Pipeline + +Comprehensive codebase analysis and improvement identification. + +```bash +Codex-flow stream-chain pipeline analysis +``` + +**Workflow Steps:** +1. **Structure Analysis**: Map directory structure and identify components +2. **Issue Detection**: Find potential improvements and problems +3. **Recommendations**: Generate actionable improvement report + +**Use Cases:** +- New codebase onboarding +- Technical debt assessment +- Architecture review +- Code quality audits + +#### 2. Refactor Pipeline + +Systematic code refactoring with prioritization. + +```bash +Codex-flow stream-chain pipeline refactor +``` + +**Workflow Steps:** +1. **Candidate Identification**: Find code needing refactoring +2. **Prioritization**: Create ranked refactoring plan +3. **Implementation**: Provide refactored code for top priorities + +**Use Cases:** +- Technical debt reduction +- Code quality improvement +- Legacy code modernization +- Design pattern implementation + +#### 3. Test Pipeline + +Comprehensive test generation with coverage analysis. + +```bash +Codex-flow stream-chain pipeline test +``` + +**Workflow Steps:** +1. **Coverage Analysis**: Identify areas lacking tests +2. **Test Design**: Create test cases for critical functions +3. **Implementation**: Generate unit tests with assertions + +**Use Cases:** +- Increasing test coverage +- TDD workflow support +- Regression test creation +- Quality assurance + +#### 4. Optimize Pipeline + +Performance optimization with profiling and implementation. + +```bash +Codex-flow stream-chain pipeline optimize +``` + +**Workflow Steps:** +1. **Profiling**: Identify performance bottlenecks +2. **Strategy**: Analyze and suggest optimization approaches +3. **Implementation**: Provide optimized code + +**Use Cases:** +- Performance improvement +- Resource optimization +- Scalability enhancement +- Latency reduction + +### Pipeline Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--verbose` | Show detailed execution | `false` | +| `--timeout ` | Timeout per step | `30` | +| `--debug` | Enable debug mode | `false` | + +### Pipeline Examples + +#### Quick Analysis + +```bash +Codex-flow stream-chain pipeline analysis +``` + +#### Extended Refactoring + +```bash +Codex-flow stream-chain pipeline refactor --timeout 60 --verbose +``` + +#### Debug Test Generation + +```bash +Codex-flow stream-chain pipeline test --debug +``` + +#### Comprehensive Optimization + +```bash +Codex-flow stream-chain pipeline optimize --timeout 90 --verbose +``` + +### Pipeline Output + +Each pipeline execution provides: + +- **Progress**: Step-by-step execution status +- **Results**: Success/failure per step +- **Timing**: Total and per-step execution time +- **Summary**: Consolidated results and recommendations + +--- + +## Custom Pipeline Definitions + +Define reusable pipelines in `.Codex-flow/config.json`: + +### Configuration Format + +```json +{ + "streamChain": { + "pipelines": { + "security": { + "name": "Security Audit Pipeline", + "description": "Comprehensive security analysis", + "prompts": [ + "Scan codebase for security vulnerabilities", + "Categorize issues by severity (critical/high/medium/low)", + "Generate fixes with priority and implementation steps", + "Create security test suite" + ], + "timeout": 45 + }, + "documentation": { + "name": "Documentation Generation Pipeline", + "prompts": [ + "Analyze code structure and identify undocumented areas", + "Generate API documentation with examples", + "Create usage guides and tutorials", + "Build architecture diagrams and flow charts" + ] + } + } + } +} +``` + +### Execute Custom Pipeline + +```bash +Codex-flow stream-chain pipeline security +Codex-flow stream-chain pipeline documentation +``` + +--- + +## Advanced Use Cases + +### Multi-Agent Coordination + +Chain different agent types for complex workflows: + +```bash +Codex-flow stream-chain run \ + "Research best practices for API design" \ + "Design REST API with discovered patterns" \ + "Implement API endpoints with validation" \ + "Generate OpenAPI specification" \ + "Create integration tests" \ + "Write deployment documentation" +``` + +### Data Transformation Pipeline + +Process and transform data through multiple stages: + +```bash +Codex-flow stream-chain run \ + "Extract user data from CSV files" \ + "Normalize and validate data format" \ + "Enrich data with external API calls" \ + "Generate analytics report" \ + "Create visualization code" +``` + +### Code Migration Workflow + +Systematic code migration with validation: + +```bash +Codex-flow stream-chain run \ + "Analyze legacy codebase dependencies" \ + "Create migration plan with risk assessment" \ + "Generate modernized code for high-priority modules" \ + "Create migration tests" \ + "Document migration steps and rollback procedures" +``` + +### Quality Assurance Chain + +Comprehensive code quality workflow: + +```bash +Codex-flow stream-chain pipeline analysis +Codex-flow stream-chain pipeline refactor +Codex-flow stream-chain pipeline test +Codex-flow stream-chain pipeline optimize +``` + +--- + +## Best Practices + +### 1. Clear and Specific Prompts + +**Good:** +```bash +"Analyze authentication.js for SQL injection vulnerabilities" +``` + +**Avoid:** +```bash +"Check security" +``` + +### 2. Logical Progression + +Order prompts to build on previous outputs: +```bash +1. "Identify the problem" +2. "Analyze root causes" +3. "Design solution" +4. "Implement solution" +5. "Verify implementation" +``` + +### 3. Appropriate Timeouts + +- Simple tasks: 30 seconds (default) +- Analysis tasks: 45-60 seconds +- Implementation tasks: 60-90 seconds +- Complex workflows: 90-120 seconds + +### 4. Verification Steps + +Include validation in your chains: +```bash +Codex-flow stream-chain run \ + "Implement feature X" \ + "Write tests for feature X" \ + "Verify tests pass and cover edge cases" +``` + +### 5. Iterative Refinement + +Use chains for iterative improvement: +```bash +Codex-flow stream-chain run \ + "Generate initial implementation" \ + "Review and identify issues" \ + "Refine based on issues found" \ + "Final quality check" +``` + +--- + +## Integration with Codex Flow + +### Combine with Swarm Coordination + +```bash +# Initialize swarm for coordination +Codex-flow swarm init --topology mesh + +# Execute stream chain with swarm agents +Codex-flow stream-chain run \ + "Agent 1: Research task" \ + "Agent 2: Implement solution" \ + "Agent 3: Test implementation" \ + "Agent 4: Review and refine" +``` + +### Memory Integration + +Stream chains automatically store context in memory for cross-session persistence: + +```bash +# Execute chain with memory +Codex-flow stream-chain run \ + "Analyze requirements" \ + "Design architecture" \ + --verbose + +# Results stored in .Codex-flow/memory/stream-chain/ +``` + +### Neural Pattern Training + +Successful chains train neural patterns for improved performance: + +```bash +# Enable neural training +Codex-flow stream-chain pipeline optimize --debug + +# Patterns learned and stored for future optimizations +``` + +--- + +## Troubleshooting + +### Chain Timeout + +If steps timeout, increase timeout value: + +```bash +Codex-flow stream-chain run "complex task" --timeout 120 +``` + +### Context Loss + +If context not flowing properly, use `--debug`: + +```bash +Codex-flow stream-chain run "step 1" "step 2" --debug +``` + +### Pipeline Not Found + +Verify pipeline name and custom definitions: + +```bash +# Check available pipelines +cat .Codex-flow/config.json | grep -A 10 "streamChain" +``` + +--- + +## Performance Characteristics + +- **Throughput**: 2-5 steps per minute (varies by complexity) +- **Context Size**: Up to 100K tokens per step +- **Memory Usage**: ~50MB per active chain +- **Concurrency**: Supports parallel chain execution + +--- + +## Related Skills + +- **SPARC Methodology**: Systematic development workflow +- **Swarm Coordination**: Multi-agent orchestration +- **Memory Management**: Persistent context storage +- **Neural Patterns**: Adaptive learning + +--- + +## Examples Repository + +### Complete Development Workflow + +```bash +# Full feature development chain +Codex-flow stream-chain run \ + "Analyze requirements for user profile feature" \ + "Design database schema and API endpoints" \ + "Implement backend with validation" \ + "Create frontend components" \ + "Write comprehensive tests" \ + "Generate API documentation" \ + --timeout 60 \ + --verbose +``` + +### Code Review Pipeline + +```bash +# Automated code review workflow +Codex-flow stream-chain run \ + "Analyze recent git changes" \ + "Identify code quality issues" \ + "Check for security vulnerabilities" \ + "Verify test coverage" \ + "Generate code review report with recommendations" +``` + +### Migration Assistant + +```bash +# Framework migration helper +Codex-flow stream-chain run \ + "Analyze current Vue 2 codebase" \ + "Identify Vue 3 breaking changes" \ + "Create migration checklist" \ + "Generate migration scripts" \ + "Provide updated code examples" +``` + +--- + +## Conclusion + +Stream-Chain enables sophisticated multi-step workflows by: + +- **Sequential Processing**: Each step builds on previous results +- **Context Preservation**: Full output history flows through chain +- **Flexible Orchestration**: Custom chains or predefined pipelines +- **Agent Coordination**: Natural multi-agent collaboration pattern +- **Data Transformation**: Complex processing through simple steps + +Use `run` for custom workflows and `pipeline` for battle-tested solutions. diff --git a/.agents/skills/swarm-advanced/SKILL.md b/.agents/skills/swarm-advanced/SKILL.md new file mode 100644 index 0000000..2853579 --- /dev/null +++ b/.agents/skills/swarm-advanced/SKILL.md @@ -0,0 +1,973 @@ +--- +name: swarm-advanced +description: Advanced swarm orchestration patterns for research, development, testing, and complex distributed workflows +version: 2.0.0 +category: orchestration +tags: [swarm, distributed, parallel, research, testing, development, coordination] +author: Codex Flow Team +--- + +# Advanced Swarm Orchestration + +Master advanced swarm patterns for distributed research, development, and testing workflows. This skill covers comprehensive orchestration strategies using both MCP tools and CLI commands. + +## Quick Start + +### Prerequisites +```bash +# Ensure Codex Flow is installed +npm install -g Codex-flow@alpha + +# Add MCP server (if using MCP tools) +Codex mcp add Codex-flow npx Codex-flow@alpha mcp start +``` + +### Basic Pattern +```javascript +// 1. Initialize swarm topology +mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 6 }) + +// 2. Spawn specialized agents +mcp__claude-flow__agent_spawn({ type: "researcher", name: "Agent 1" }) + +// 3. Orchestrate tasks +mcp__claude-flow__task_orchestrate({ task: "...", strategy: "parallel" }) +``` + +## Core Concepts + +### Swarm Topologies + +**Mesh Topology** - Peer-to-peer communication, best for research and analysis +- All agents communicate directly +- High flexibility and resilience +- Use for: Research, analysis, brainstorming + +**Hierarchical Topology** - Coordinator with subordinates, best for development +- Clear command structure +- Sequential workflow support +- Use for: Development, structured workflows + +**Star Topology** - Central coordinator, best for testing +- Centralized control and monitoring +- Parallel execution with coordination +- Use for: Testing, validation, quality assurance + +**Ring Topology** - Sequential processing chain +- Step-by-step processing +- Pipeline workflows +- Use for: Multi-stage processing, data pipelines + +### Agent Strategies + +**Adaptive** - Dynamic adjustment based on task complexity +**Balanced** - Equal distribution of work across agents +**Specialized** - Task-specific agent assignment +**Parallel** - Maximum concurrent execution + +## Pattern 1: Research Swarm + +### Purpose +Deep research through parallel information gathering, analysis, and synthesis. + +### Architecture +```javascript +// Initialize research swarm +mcp__claude-flow__swarm_init({ + "topology": "mesh", + "maxAgents": 6, + "strategy": "adaptive" +}) + +// Spawn research team +const researchAgents = [ + { + type: "researcher", + name: "Web Researcher", + capabilities: ["web-search", "content-extraction", "source-validation"] + }, + { + type: "researcher", + name: "Academic Researcher", + capabilities: ["paper-analysis", "citation-tracking", "literature-review"] + }, + { + type: "analyst", + name: "Data Analyst", + capabilities: ["data-processing", "statistical-analysis", "visualization"] + }, + { + type: "analyst", + name: "Pattern Analyzer", + capabilities: ["trend-detection", "correlation-analysis", "outlier-detection"] + }, + { + type: "documenter", + name: "Report Writer", + capabilities: ["synthesis", "technical-writing", "formatting"] + } +] + +// Spawn all agents +researchAgents.forEach(agent => { + mcp__claude-flow__agent_spawn({ + type: agent.type, + name: agent.name, + capabilities: agent.capabilities + }) +}) +``` + +### Research Workflow + +#### Phase 1: Information Gathering +```javascript +// Parallel information collection +mcp__claude-flow__parallel_execute({ + "tasks": [ + { + "id": "web-search", + "command": "search recent publications and articles" + }, + { + "id": "academic-search", + "command": "search academic databases and papers" + }, + { + "id": "data-collection", + "command": "gather relevant datasets and statistics" + }, + { + "id": "expert-search", + "command": "identify domain experts and thought leaders" + } + ] +}) + +// Store research findings in memory +mcp__claude-flow__memory_usage({ + "action": "store", + "key": "research-findings-" + Date.now(), + "value": JSON.stringify(findings), + "namespace": "research", + "ttl": 604800 // 7 days +}) +``` + +#### Phase 2: Analysis and Validation +```javascript +// Pattern recognition in findings +mcp__claude-flow__pattern_recognize({ + "data": researchData, + "patterns": ["trend", "correlation", "outlier", "emerging-pattern"] +}) + +// Cognitive analysis +mcp__claude-flow__cognitive_analyze({ + "behavior": "research-synthesis" +}) + +// Quality assessment +mcp__claude-flow__quality_assess({ + "target": "research-sources", + "criteria": ["credibility", "relevance", "recency", "authority"] +}) + +// Cross-reference validation +mcp__claude-flow__neural_patterns({ + "action": "analyze", + "operation": "fact-checking", + "metadata": { "sources": sourcesArray } +}) +``` + +#### Phase 3: Knowledge Management +```javascript +// Search existing knowledge base +mcp__claude-flow__memory_search({ + "pattern": "topic X", + "namespace": "research", + "limit": 20 +}) + +// Create knowledge graph connections +mcp__claude-flow__neural_patterns({ + "action": "learn", + "operation": "knowledge-graph", + "metadata": { + "topic": "X", + "connections": relatedTopics, + "depth": 3 + } +}) + +// Store connections for future use +mcp__claude-flow__memory_usage({ + "action": "store", + "key": "knowledge-graph-X", + "value": JSON.stringify(knowledgeGraph), + "namespace": "research/graphs", + "ttl": 2592000 // 30 days +}) +``` + +#### Phase 4: Report Generation +```javascript +// Orchestrate report generation +mcp__claude-flow__task_orchestrate({ + "task": "generate comprehensive research report", + "strategy": "sequential", + "priority": "high", + "dependencies": ["gather", "analyze", "validate", "synthesize"] +}) + +// Monitor research progress +mcp__claude-flow__swarm_status({ + "swarmId": "research-swarm" +}) + +// Generate final report +mcp__claude-flow__workflow_execute({ + "workflowId": "research-report-generation", + "params": { + "findings": findings, + "format": "comprehensive", + "sections": ["executive-summary", "methodology", "findings", "analysis", "conclusions", "references"] + } +}) +``` + +### CLI Fallback +```bash +# Quick research swarm +npx Codex-flow swarm "research AI trends in 2025" \ + --strategy research \ + --mode distributed \ + --max-agents 6 \ + --parallel \ + --output research-report.md +``` + +## Pattern 2: Development Swarm + +### Purpose +Full-stack development through coordinated specialist agents. + +### Architecture +```javascript +// Initialize development swarm with hierarchy +mcp__claude-flow__swarm_init({ + "topology": "hierarchical", + "maxAgents": 8, + "strategy": "balanced" +}) + +// Spawn development team +const devTeam = [ + { type: "architect", name: "System Architect", role: "coordinator" }, + { type: "coder", name: "Backend Developer", capabilities: ["node", "api", "database"] }, + { type: "coder", name: "Frontend Developer", capabilities: ["react", "ui", "ux"] }, + { type: "coder", name: "Database Engineer", capabilities: ["sql", "nosql", "optimization"] }, + { type: "tester", name: "QA Engineer", capabilities: ["unit", "integration", "e2e"] }, + { type: "reviewer", name: "Code Reviewer", capabilities: ["security", "performance", "best-practices"] }, + { type: "documenter", name: "Technical Writer", capabilities: ["api-docs", "guides", "tutorials"] }, + { type: "monitor", name: "DevOps Engineer", capabilities: ["ci-cd", "deployment", "monitoring"] } +] + +// Spawn all team members +devTeam.forEach(member => { + mcp__claude-flow__agent_spawn({ + type: member.type, + name: member.name, + capabilities: member.capabilities, + swarmId: "dev-swarm" + }) +}) +``` + +### Development Workflow + +#### Phase 1: Architecture and Design +```javascript +// System architecture design +mcp__claude-flow__task_orchestrate({ + "task": "design system architecture for REST API", + "strategy": "sequential", + "priority": "critical", + "assignTo": "System Architect" +}) + +// Store architecture decisions +mcp__claude-flow__memory_usage({ + "action": "store", + "key": "architecture-decisions", + "value": JSON.stringify(architectureDoc), + "namespace": "development/design" +}) +``` + +#### Phase 2: Parallel Implementation +```javascript +// Parallel development tasks +mcp__claude-flow__parallel_execute({ + "tasks": [ + { + "id": "backend-api", + "command": "implement REST API endpoints", + "assignTo": "Backend Developer" + }, + { + "id": "frontend-ui", + "command": "build user interface components", + "assignTo": "Frontend Developer" + }, + { + "id": "database-schema", + "command": "design and implement database schema", + "assignTo": "Database Engineer" + }, + { + "id": "api-documentation", + "command": "create API documentation", + "assignTo": "Technical Writer" + } + ] +}) + +// Monitor development progress +mcp__claude-flow__swarm_monitor({ + "swarmId": "dev-swarm", + "interval": 5000 +}) +``` + +#### Phase 3: Testing and Validation +```javascript +// Comprehensive testing +mcp__claude-flow__batch_process({ + "items": [ + { type: "unit", target: "all-modules" }, + { type: "integration", target: "api-endpoints" }, + { type: "e2e", target: "user-flows" }, + { type: "performance", target: "critical-paths" } + ], + "operation": "execute-tests" +}) + +// Quality assessment +mcp__claude-flow__quality_assess({ + "target": "codebase", + "criteria": ["coverage", "complexity", "maintainability", "security"] +}) +``` + +#### Phase 4: Review and Deployment +```javascript +// Code review workflow +mcp__claude-flow__workflow_execute({ + "workflowId": "code-review-process", + "params": { + "reviewers": ["Code Reviewer"], + "criteria": ["security", "performance", "best-practices"] + } +}) + +// CI/CD pipeline +mcp__claude-flow__pipeline_create({ + "config": { + "stages": ["build", "test", "security-scan", "deploy"], + "environment": "production" + } +}) +``` + +### CLI Fallback +```bash +# Quick development swarm +npx Codex-flow swarm "build REST API with authentication" \ + --strategy development \ + --mode hierarchical \ + --monitor \ + --output sqlite +``` + +## Pattern 3: Testing Swarm + +### Purpose +Comprehensive quality assurance through distributed testing. + +### Architecture +```javascript +// Initialize testing swarm with star topology +mcp__claude-flow__swarm_init({ + "topology": "star", + "maxAgents": 7, + "strategy": "parallel" +}) + +// Spawn testing team +const testingTeam = [ + { + type: "tester", + name: "Unit Test Coordinator", + capabilities: ["unit-testing", "mocking", "coverage", "tdd"] + }, + { + type: "tester", + name: "Integration Tester", + capabilities: ["integration", "api-testing", "contract-testing"] + }, + { + type: "tester", + name: "E2E Tester", + capabilities: ["e2e", "ui-testing", "user-flows", "selenium"] + }, + { + type: "tester", + name: "Performance Tester", + capabilities: ["load-testing", "stress-testing", "benchmarking"] + }, + { + type: "monitor", + name: "Security Tester", + capabilities: ["security-testing", "penetration-testing", "vulnerability-scanning"] + }, + { + type: "analyst", + name: "Test Analyst", + capabilities: ["coverage-analysis", "test-optimization", "reporting"] + }, + { + type: "documenter", + name: "Test Documenter", + capabilities: ["test-documentation", "test-plans", "reports"] + } +] + +// Spawn all testers +testingTeam.forEach(tester => { + mcp__claude-flow__agent_spawn({ + type: tester.type, + name: tester.name, + capabilities: tester.capabilities, + swarmId: "testing-swarm" + }) +}) +``` + +### Testing Workflow + +#### Phase 1: Test Planning +```javascript +// Analyze test coverage requirements +mcp__claude-flow__quality_assess({ + "target": "test-coverage", + "criteria": [ + "line-coverage", + "branch-coverage", + "function-coverage", + "edge-cases" + ] +}) + +// Identify test scenarios +mcp__claude-flow__pattern_recognize({ + "data": testScenarios, + "patterns": [ + "edge-case", + "boundary-condition", + "error-path", + "happy-path" + ] +}) + +// Store test plan +mcp__claude-flow__memory_usage({ + "action": "store", + "key": "test-plan-" + Date.now(), + "value": JSON.stringify(testPlan), + "namespace": "testing/plans" +}) +``` + +#### Phase 2: Parallel Test Execution +```javascript +// Execute all test suites in parallel +mcp__claude-flow__parallel_execute({ + "tasks": [ + { + "id": "unit-tests", + "command": "npm run test:unit", + "assignTo": "Unit Test Coordinator" + }, + { + "id": "integration-tests", + "command": "npm run test:integration", + "assignTo": "Integration Tester" + }, + { + "id": "e2e-tests", + "command": "npm run test:e2e", + "assignTo": "E2E Tester" + }, + { + "id": "performance-tests", + "command": "npm run test:performance", + "assignTo": "Performance Tester" + }, + { + "id": "security-tests", + "command": "npm run test:security", + "assignTo": "Security Tester" + } + ] +}) + +// Batch process test suites +mcp__claude-flow__batch_process({ + "items": testSuites, + "operation": "execute-test-suite" +}) +``` + +#### Phase 3: Performance and Security +```javascript +// Run performance benchmarks +mcp__claude-flow__benchmark_run({ + "suite": "comprehensive-performance" +}) + +// Bottleneck analysis +mcp__claude-flow__bottleneck_analyze({ + "component": "application", + "metrics": ["response-time", "throughput", "memory", "cpu"] +}) + +// Security scanning +mcp__claude-flow__security_scan({ + "target": "application", + "depth": "comprehensive" +}) + +// Vulnerability analysis +mcp__claude-flow__error_analysis({ + "logs": securityScanLogs +}) +``` + +#### Phase 4: Monitoring and Reporting +```javascript +// Real-time test monitoring +mcp__claude-flow__swarm_monitor({ + "swarmId": "testing-swarm", + "interval": 2000 +}) + +// Generate comprehensive test report +mcp__claude-flow__performance_report({ + "format": "detailed", + "timeframe": "current-run" +}) + +// Get test results +mcp__claude-flow__task_results({ + "taskId": "test-execution-001" +}) + +// Trend analysis +mcp__claude-flow__trend_analysis({ + "metric": "test-coverage", + "period": "30d" +}) +``` + +### CLI Fallback +```bash +# Quick testing swarm +npx Codex-flow swarm "test application comprehensively" \ + --strategy testing \ + --mode star \ + --parallel \ + --timeout 600 +``` + +## Pattern 4: Analysis Swarm + +### Purpose +Deep code and system analysis through specialized analyzers. + +### Architecture +```javascript +// Initialize analysis swarm +mcp__claude-flow__swarm_init({ + "topology": "mesh", + "maxAgents": 5, + "strategy": "adaptive" +}) + +// Spawn analysis specialists +const analysisTeam = [ + { + type: "analyst", + name: "Code Analyzer", + capabilities: ["static-analysis", "complexity-analysis", "dead-code-detection"] + }, + { + type: "analyst", + name: "Security Analyzer", + capabilities: ["security-scan", "vulnerability-detection", "dependency-audit"] + }, + { + type: "analyst", + name: "Performance Analyzer", + capabilities: ["profiling", "bottleneck-detection", "optimization"] + }, + { + type: "analyst", + name: "Architecture Analyzer", + capabilities: ["dependency-analysis", "coupling-detection", "modularity-assessment"] + }, + { + type: "documenter", + name: "Analysis Reporter", + capabilities: ["reporting", "visualization", "recommendations"] + } +] + +// Spawn all analysts +analysisTeam.forEach(analyst => { + mcp__claude-flow__agent_spawn({ + type: analyst.type, + name: analyst.name, + capabilities: analyst.capabilities + }) +}) +``` + +### Analysis Workflow +```javascript +// Parallel analysis execution +mcp__claude-flow__parallel_execute({ + "tasks": [ + { "id": "analyze-code", "command": "analyze codebase structure and quality" }, + { "id": "analyze-security", "command": "scan for security vulnerabilities" }, + { "id": "analyze-performance", "command": "identify performance bottlenecks" }, + { "id": "analyze-architecture", "command": "assess architectural patterns" } + ] +}) + +// Generate comprehensive analysis report +mcp__claude-flow__performance_report({ + "format": "detailed", + "timeframe": "current" +}) + +// Cost analysis +mcp__claude-flow__cost_analysis({ + "timeframe": "30d" +}) +``` + +## Advanced Techniques + +### Error Handling and Fault Tolerance + +```javascript +// Setup fault tolerance for all agents +mcp__claude-flow__daa_fault_tolerance({ + "agentId": "all", + "strategy": "auto-recovery" +}) + +// Error handling pattern +try { + await mcp__claude-flow__task_orchestrate({ + "task": "complex operation", + "strategy": "parallel", + "priority": "high" + }) +} catch (error) { + // Check swarm health + const status = await mcp__claude-flow__swarm_status({}) + + // Analyze error patterns + await mcp__claude-flow__error_analysis({ + "logs": [error.message] + }) + + // Auto-recovery attempt + if (status.healthy) { + await mcp__claude-flow__task_orchestrate({ + "task": "retry failed operation", + "strategy": "sequential" + }) + } +} +``` + +### Memory and State Management + +```javascript +// Cross-session persistence +mcp__claude-flow__memory_persist({ + "sessionId": "swarm-session-001" +}) + +// Namespace management for different swarms +mcp__claude-flow__memory_namespace({ + "namespace": "research-swarm", + "action": "create" +}) + +// Create state snapshot +mcp__claude-flow__state_snapshot({ + "name": "development-checkpoint-1" +}) + +// Restore from snapshot if needed +mcp__claude-flow__context_restore({ + "snapshotId": "development-checkpoint-1" +}) + +// Backup memory stores +mcp__claude-flow__memory_backup({ + "path": "/workspaces/Codex-flow/backups/swarm-memory.json" +}) +``` + +### Neural Pattern Learning + +```javascript +// Train neural patterns from successful workflows +mcp__claude-flow__neural_train({ + "pattern_type": "coordination", + "training_data": JSON.stringify(successfulWorkflows), + "epochs": 50 +}) + +// Adaptive learning from experience +mcp__claude-flow__learning_adapt({ + "experience": { + "workflow": "research-to-report", + "success": true, + "duration": 3600, + "quality": 0.95 + } +}) + +// Pattern recognition for optimization +mcp__claude-flow__pattern_recognize({ + "data": workflowMetrics, + "patterns": ["bottleneck", "optimization-opportunity", "efficiency-gain"] +}) +``` + +### Workflow Automation + +```javascript +// Create reusable workflow +mcp__claude-flow__workflow_create({ + "name": "full-stack-development", + "steps": [ + { "phase": "design", "agents": ["architect"] }, + { "phase": "implement", "agents": ["backend-dev", "frontend-dev"], "parallel": true }, + { "phase": "test", "agents": ["tester", "security-tester"], "parallel": true }, + { "phase": "review", "agents": ["reviewer"] }, + { "phase": "deploy", "agents": ["devops"] } + ], + "triggers": ["on-commit", "scheduled-daily"] +}) + +// Setup automation rules +mcp__claude-flow__automation_setup({ + "rules": [ + { + "trigger": "file-changed", + "pattern": "*.js", + "action": "run-tests" + }, + { + "trigger": "PR-created", + "action": "code-review-swarm" + } + ] +}) + +// Event-driven triggers +mcp__claude-flow__trigger_setup({ + "events": ["code-commit", "PR-merge", "deployment"], + "actions": ["test", "analyze", "document"] +}) +``` + +### Performance Optimization + +```javascript +// Topology optimization +mcp__claude-flow__topology_optimize({ + "swarmId": "current-swarm" +}) + +// Load balancing +mcp__claude-flow__load_balance({ + "swarmId": "development-swarm", + "tasks": taskQueue +}) + +// Agent coordination sync +mcp__claude-flow__coordination_sync({ + "swarmId": "development-swarm" +}) + +// Auto-scaling +mcp__claude-flow__swarm_scale({ + "swarmId": "development-swarm", + "targetSize": 12 +}) +``` + +### Monitoring and Metrics + +```javascript +// Real-time swarm monitoring +mcp__claude-flow__swarm_monitor({ + "swarmId": "active-swarm", + "interval": 3000 +}) + +// Collect comprehensive metrics +mcp__claude-flow__metrics_collect({ + "components": ["agents", "tasks", "memory", "performance"] +}) + +// Health monitoring +mcp__claude-flow__health_check({ + "components": ["swarm", "agents", "neural", "memory"] +}) + +// Usage statistics +mcp__claude-flow__usage_stats({ + "component": "swarm-orchestration" +}) + +// Trend analysis +mcp__claude-flow__trend_analysis({ + "metric": "agent-performance", + "period": "7d" +}) +``` + +## Best Practices + +### 1. Choosing the Right Topology + +- **Mesh**: Research, brainstorming, collaborative analysis +- **Hierarchical**: Structured development, sequential workflows +- **Star**: Testing, validation, centralized coordination +- **Ring**: Pipeline processing, staged workflows + +### 2. Agent Specialization + +- Assign specific capabilities to each agent +- Avoid overlapping responsibilities +- Use coordination agents for complex workflows +- Leverage memory for agent communication + +### 3. Parallel Execution + +- Identify independent tasks for parallelization +- Use sequential execution for dependent tasks +- Monitor resource usage during parallel execution +- Implement proper error handling + +### 4. Memory Management + +- Use namespaces to organize memory +- Set appropriate TTL values +- Create regular backups +- Implement state snapshots for checkpoints + +### 5. Monitoring and Optimization + +- Monitor swarm health regularly +- Collect and analyze metrics +- Optimize topology based on performance +- Use neural patterns to learn from success + +### 6. Error Recovery + +- Implement fault tolerance strategies +- Use auto-recovery mechanisms +- Analyze error patterns +- Create fallback workflows + +## Real-World Examples + +### Example 1: AI Research Project +```javascript +// Research AI trends, analyze findings, generate report +mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 6 }) +// Spawn: 2 researchers, 2 analysts, 1 synthesizer, 1 documenter +// Parallel gather → Analyze patterns → Synthesize → Report +``` + +### Example 2: Full-Stack Application +```javascript +// Build complete web application with testing +mcp__claude-flow__swarm_init({ topology: "hierarchical", maxAgents: 8 }) +// Spawn: 1 architect, 2 devs, 1 db engineer, 2 testers, 1 reviewer, 1 devops +// Design → Parallel implement → Test → Review → Deploy +``` + +### Example 3: Security Audit +```javascript +// Comprehensive security analysis +mcp__claude-flow__swarm_init({ topology: "star", maxAgents: 5 }) +// Spawn: 1 coordinator, 1 code analyzer, 1 security scanner, 1 penetration tester, 1 reporter +// Parallel scan → Vulnerability analysis → Penetration test → Report +``` + +### Example 4: Performance Optimization +```javascript +// Identify and fix performance bottlenecks +mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 4 }) +// Spawn: 1 profiler, 1 bottleneck analyzer, 1 optimizer, 1 tester +// Profile → Identify bottlenecks → Optimize → Validate +``` + +## Troubleshooting + +### Common Issues + +**Issue**: Swarm agents not coordinating properly +**Solution**: Check topology selection, verify memory usage, enable monitoring + +**Issue**: Parallel execution failing +**Solution**: Verify task dependencies, check resource limits, implement error handling + +**Issue**: Memory persistence not working +**Solution**: Verify namespaces, check TTL settings, ensure backup configuration + +**Issue**: Performance degradation +**Solution**: Optimize topology, reduce agent count, analyze bottlenecks + +## Related Skills + +- `sparc-methodology` - Systematic development workflow +- `github-integration` - Repository management and automation +- `neural-patterns` - AI-powered coordination optimization +- `memory-management` - Cross-session state persistence + +## References + +- [Codex Flow Documentation](https://github.com/ruvnet/Codex-flow) +- [Swarm Orchestration Guide](https://github.com/ruvnet/Codex-flow/wiki/swarm) +- [MCP Tools Reference](https://github.com/ruvnet/Codex-flow/wiki/mcp) +- [Performance Optimization](https://github.com/ruvnet/Codex-flow/wiki/performance) + +--- + +**Version**: 2.0.0 +**Last Updated**: 2025-10-19 +**Skill Level**: Advanced +**Estimated Learning Time**: 2-3 hours diff --git a/.agents/skills/v3-cli-modernization/SKILL.md b/.agents/skills/v3-cli-modernization/SKILL.md new file mode 100644 index 0000000..1ba5f35 --- /dev/null +++ b/.agents/skills/v3-cli-modernization/SKILL.md @@ -0,0 +1,872 @@ +--- +name: "V3 CLI Modernization" +description: "CLI modernization and hooks system enhancement for Codex-flow v3. Implements interactive prompts, command decomposition, enhanced hooks integration, and intelligent workflow automation." +--- + +# V3 CLI Modernization + +## What This Skill Does + +Modernizes Codex-flow v3 CLI with interactive prompts, intelligent command decomposition, enhanced hooks integration, performance optimization, and comprehensive workflow automation capabilities. + +## Quick Start + +```bash +# Initialize CLI modernization analysis +Task("CLI architecture", "Analyze current CLI structure and identify optimization opportunities", "cli-hooks-developer") + +# Modernization implementation (parallel) +Task("Command decomposition", "Break down large CLI files into focused modules", "cli-hooks-developer") +Task("Interactive prompts", "Implement intelligent interactive CLI experience", "cli-hooks-developer") +Task("Hooks enhancement", "Deep integrate hooks with CLI lifecycle", "cli-hooks-developer") +``` + +## CLI Architecture Modernization + +### Current State Analysis +``` +Current CLI Issues: +├── index.ts: 108KB monolithic file +├── enterprise.ts: 68KB feature module +├── Limited interactivity: Basic command parsing +├── Hooks integration: Basic pre/post execution +└── No intelligent workflows: Manual command chaining + +Target Architecture: +├── Modular Commands: <500 lines per command +├── Interactive Prompts: Smart context-aware UX +├── Enhanced Hooks: Deep lifecycle integration +├── Workflow Automation: Intelligent command orchestration +└── Performance: <200ms command response time +``` + +### Modular Command Architecture +```typescript +// src/cli/core/command-registry.ts +interface CommandModule { + name: string; + description: string; + category: CommandCategory; + handler: CommandHandler; + middleware: MiddlewareStack; + permissions: Permission[]; + examples: CommandExample[]; +} + +export class ModularCommandRegistry { + private commands = new Map(); + private categories = new Map(); + private aliases = new Map(); + + registerCommand(command: CommandModule): void { + this.commands.set(command.name, command); + + // Register in category index + if (!this.categories.has(command.category)) { + this.categories.set(command.category, []); + } + this.categories.get(command.category)!.push(command); + } + + async executeCommand(name: string, args: string[]): Promise { + const command = this.resolveCommand(name); + if (!command) { + throw new CommandNotFoundError(name, this.getSuggestions(name)); + } + + // Execute middleware stack + const context = await this.buildExecutionContext(command, args); + const result = await command.middleware.execute(context); + + return result; + } + + private resolveCommand(name: string): CommandModule | undefined { + // Try exact match first + if (this.commands.has(name)) { + return this.commands.get(name); + } + + // Try alias + const aliasTarget = this.aliases.get(name); + if (aliasTarget) { + return this.commands.get(aliasTarget); + } + + // Try fuzzy match + return this.findFuzzyMatch(name); + } +} +``` + +## Command Decomposition Strategy + +### Swarm Commands Module +```typescript +// src/cli/commands/swarm/swarm.command.ts +@Command({ + name: 'swarm', + description: 'Swarm coordination and management', + category: 'orchestration' +}) +export class SwarmCommand { + constructor( + private swarmCoordinator: UnifiedSwarmCoordinator, + private promptService: InteractivePromptService + ) {} + + @SubCommand('init') + @Option('--topology', 'Swarm topology (mesh|hierarchical|adaptive)', 'hierarchical') + @Option('--agents', 'Number of agents to spawn', 5) + @Option('--interactive', 'Interactive agent configuration', false) + async init( + @Arg('projectName') projectName: string, + options: SwarmInitOptions + ): Promise { + + if (options.interactive) { + return this.interactiveSwarmInit(projectName); + } + + return this.quickSwarmInit(projectName, options); + } + + private async interactiveSwarmInit(projectName: string): Promise { + console.log(`🚀 Initializing Swarm for ${projectName}`); + + // Interactive topology selection + const topology = await this.promptService.select({ + message: 'Select swarm topology:', + choices: [ + { name: 'Hierarchical (Queen-led coordination)', value: 'hierarchical' }, + { name: 'Mesh (Peer-to-peer collaboration)', value: 'mesh' }, + { name: 'Adaptive (Dynamic topology switching)', value: 'adaptive' } + ] + }); + + // Agent configuration + const agents = await this.promptAgentConfiguration(); + + // Initialize with configuration + const swarm = await this.swarmCoordinator.initialize({ + name: projectName, + topology, + agents, + hooks: { + onAgentSpawn: this.handleAgentSpawn.bind(this), + onTaskComplete: this.handleTaskComplete.bind(this), + onSwarmComplete: this.handleSwarmComplete.bind(this) + } + }); + + return CommandResult.success({ + message: `✅ Swarm ${projectName} initialized with ${agents.length} agents`, + data: { swarmId: swarm.id, topology, agentCount: agents.length } + }); + } + + @SubCommand('status') + async status(): Promise { + const swarms = await this.swarmCoordinator.listActiveSwarms(); + + if (swarms.length === 0) { + return CommandResult.info('No active swarms found'); + } + + // Interactive swarm selection if multiple + const selectedSwarm = swarms.length === 1 + ? swarms[0] + : await this.promptService.select({ + message: 'Select swarm to inspect:', + choices: swarms.map(s => ({ + name: `${s.name} (${s.agents.length} agents, ${s.topology})`, + value: s + })) + }); + + return this.displaySwarmStatus(selectedSwarm); + } +} +``` + +### Learning Commands Module +```typescript +// src/cli/commands/learning/learning.command.ts +@Command({ + name: 'learning', + description: 'Learning system management and optimization', + category: 'intelligence' +}) +export class LearningCommand { + constructor( + private learningService: IntegratedLearningService, + private promptService: InteractivePromptService + ) {} + + @SubCommand('start') + @Option('--algorithm', 'RL algorithm to use', 'auto') + @Option('--tier', 'Learning tier (basic|standard|advanced)', 'standard') + async start(options: LearningStartOptions): Promise { + // Auto-detect optimal algorithm if not specified + if (options.algorithm === 'auto') { + const taskContext = await this.analyzeCurrentContext(); + options.algorithm = this.learningService.selectOptimalAlgorithm(taskContext); + + console.log(`🧠 Auto-selected ${options.algorithm} algorithm based on context`); + } + + const session = await this.learningService.startSession({ + algorithm: options.algorithm, + tier: options.tier, + userId: await this.getCurrentUser() + }); + + return CommandResult.success({ + message: `🚀 Learning session started with ${options.algorithm}`, + data: { sessionId: session.id, algorithm: options.algorithm, tier: options.tier } + }); + } + + @SubCommand('feedback') + @Arg('reward', 'Reward value (0-1)', 'number') + async feedback( + @Arg('reward') reward: number, + @Option('--context', 'Additional context for learning') + context?: string + ): Promise { + const activeSession = await this.learningService.getActiveSession(); + if (!activeSession) { + return CommandResult.error('No active learning session found. Start one with `learning start`'); + } + + await this.learningService.submitFeedback({ + sessionId: activeSession.id, + reward, + context, + timestamp: new Date() + }); + + return CommandResult.success({ + message: `📊 Feedback recorded (reward: ${reward})`, + data: { reward, sessionId: activeSession.id } + }); + } + + @SubCommand('metrics') + async metrics(): Promise { + const metrics = await this.learningService.getMetrics(); + + // Interactive metrics display + await this.displayInteractiveMetrics(metrics); + + return CommandResult.success('Metrics displayed'); + } +} +``` + +## Interactive Prompt System + +### Advanced Prompt Service +```typescript +// src/cli/services/interactive-prompt.service.ts +interface PromptOptions { + message: string; + type: 'select' | 'multiselect' | 'input' | 'confirm' | 'progress'; + choices?: PromptChoice[]; + default?: any; + validate?: (input: any) => boolean | string; + transform?: (input: any) => any; +} + +export class InteractivePromptService { + private inquirer: any; // Dynamic import for tree-shaking + + async select(options: SelectPromptOptions): Promise { + const { default: inquirer } = await import('inquirer'); + + const result = await inquirer.prompt([{ + type: 'list', + name: 'selection', + message: options.message, + choices: options.choices, + default: options.default + }]); + + return result.selection; + } + + async multiSelect(options: MultiSelectPromptOptions): Promise { + const { default: inquirer } = await import('inquirer'); + + const result = await inquirer.prompt([{ + type: 'checkbox', + name: 'selections', + message: options.message, + choices: options.choices, + validate: (input: T[]) => { + if (options.minSelections && input.length < options.minSelections) { + return `Please select at least ${options.minSelections} options`; + } + if (options.maxSelections && input.length > options.maxSelections) { + return `Please select at most ${options.maxSelections} options`; + } + return true; + } + }]); + + return result.selections; + } + + async input(options: InputPromptOptions): Promise { + const { default: inquirer } = await import('inquirer'); + + const result = await inquirer.prompt([{ + type: 'input', + name: 'input', + message: options.message, + default: options.default, + validate: options.validate, + transformer: options.transform + }]); + + return result.input; + } + + async progressTask( + task: ProgressTask, + options: ProgressOptions + ): Promise { + const { default: cliProgress } = await import('cli-progress'); + + const progressBar = new cliProgress.SingleBar({ + format: `${options.title} |{bar}| {percentage}% | {status}`, + barCompleteChar: '█', + barIncompleteChar: '░', + hideCursor: true + }); + + progressBar.start(100, 0, { status: 'Starting...' }); + + try { + const result = await task({ + updateProgress: (percent: number, status?: string) => { + progressBar.update(percent, { status: status || 'Processing...' }); + } + }); + + progressBar.update(100, { status: 'Complete!' }); + progressBar.stop(); + + return result; + } catch (error) { + progressBar.stop(); + throw error; + } + } + + async confirmWithDetails( + message: string, + details: ConfirmationDetails + ): Promise { + console.log('\n' + chalk.bold(message)); + console.log(chalk.gray('Details:')); + + for (const [key, value] of Object.entries(details)) { + console.log(chalk.gray(` ${key}: ${value}`)); + } + + return this.confirm('\nProceed?'); + } +} +``` + +## Enhanced Hooks Integration + +### Deep CLI Hooks Integration +```typescript +// src/cli/hooks/cli-hooks-manager.ts +interface CLIHookEvent { + type: 'command_start' | 'command_end' | 'command_error' | 'agent_spawn' | 'task_complete'; + command: string; + args: string[]; + context: ExecutionContext; + timestamp: Date; +} + +export class CLIHooksManager { + private hooks: Map = new Map(); + private learningIntegration: LearningHooksIntegration; + + constructor() { + this.learningIntegration = new LearningHooksIntegration(); + this.setupDefaultHooks(); + } + + private setupDefaultHooks(): void { + // Learning integration hooks + this.registerHook('command_start', async (event: CLIHookEvent) => { + await this.learningIntegration.recordCommandStart(event); + }); + + this.registerHook('command_end', async (event: CLIHookEvent) => { + await this.learningIntegration.recordCommandSuccess(event); + }); + + this.registerHook('command_error', async (event: CLIHookEvent) => { + await this.learningIntegration.recordCommandError(event); + }); + + // Intelligent suggestions + this.registerHook('command_start', async (event: CLIHookEvent) => { + const suggestions = await this.generateIntelligentSuggestions(event); + if (suggestions.length > 0) { + this.displaySuggestions(suggestions); + } + }); + + // Performance monitoring + this.registerHook('command_end', async (event: CLIHookEvent) => { + await this.recordPerformanceMetrics(event); + }); + } + + async executeHooks(type: string, event: CLIHookEvent): Promise { + const handlers = this.hooks.get(type) || []; + + await Promise.all(handlers.map(handler => + this.executeHookSafely(handler, event) + )); + } + + private async generateIntelligentSuggestions(event: CLIHookEvent): Promise { + const context = await this.learningIntegration.getExecutionContext(event); + const patterns = await this.learningIntegration.findSimilarPatterns(context); + + return patterns.map(pattern => ({ + type: 'optimization', + message: `Based on similar executions, consider: ${pattern.suggestion}`, + confidence: pattern.confidence + })); + } +} +``` + +### Learning Integration +```typescript +// src/cli/hooks/learning-hooks-integration.ts +export class LearningHooksIntegration { + constructor( + private agenticFlowHooks: AgenticFlowHooksClient, + private agentDBLearning: AgentDBLearningClient + ) {} + + async recordCommandStart(event: CLIHookEvent): Promise { + // Start trajectory tracking + await this.agenticFlowHooks.trajectoryStart({ + sessionId: event.context.sessionId, + command: event.command, + args: event.args, + context: event.context + }); + + // Record experience in AgentDB + await this.agentDBLearning.recordExperience({ + type: 'command_execution', + state: this.encodeCommandState(event), + action: event.command, + timestamp: event.timestamp + }); + } + + async recordCommandSuccess(event: CLIHookEvent): Promise { + const executionTime = Date.now() - event.timestamp.getTime(); + const reward = this.calculateReward(event, executionTime, true); + + // Complete trajectory + await this.agenticFlowHooks.trajectoryEnd({ + sessionId: event.context.sessionId, + success: true, + reward, + verdict: 'positive' + }); + + // Submit feedback to learning system + await this.agentDBLearning.submitFeedback({ + sessionId: event.context.learningSessionId, + reward, + success: true, + latencyMs: executionTime + }); + + // Store successful pattern + if (reward > 0.8) { + await this.agenticFlowHooks.storePattern({ + pattern: event.command, + solution: event.context.result, + confidence: reward + }); + } + } + + async recordCommandError(event: CLIHookEvent): Promise { + const executionTime = Date.now() - event.timestamp.getTime(); + const reward = this.calculateReward(event, executionTime, false); + + // Complete trajectory with error + await this.agenticFlowHooks.trajectoryEnd({ + sessionId: event.context.sessionId, + success: false, + reward, + verdict: 'negative', + error: event.context.error + }); + + // Learn from failure + await this.agentDBLearning.submitFeedback({ + sessionId: event.context.learningSessionId, + reward, + success: false, + latencyMs: executionTime, + error: event.context.error + }); + } + + private calculateReward(event: CLIHookEvent, executionTime: number, success: boolean): number { + if (!success) return 0; + + // Base reward for success + let reward = 0.5; + + // Performance bonus (faster execution) + const expectedTime = this.getExpectedExecutionTime(event.command); + if (executionTime < expectedTime) { + reward += 0.3 * (1 - executionTime / expectedTime); + } + + // Complexity bonus + const complexity = this.calculateCommandComplexity(event); + reward += complexity * 0.2; + + return Math.min(reward, 1.0); + } +} +``` + +## Intelligent Workflow Automation + +### Workflow Orchestrator +```typescript +// src/cli/workflows/workflow-orchestrator.ts +interface WorkflowStep { + id: string; + command: string; + args: string[]; + dependsOn: string[]; + condition?: WorkflowCondition; + retryPolicy?: RetryPolicy; +} + +export class WorkflowOrchestrator { + constructor( + private commandRegistry: ModularCommandRegistry, + private promptService: InteractivePromptService + ) {} + + async executeWorkflow(workflow: Workflow): Promise { + const context = new WorkflowExecutionContext(workflow); + + // Display workflow overview + await this.displayWorkflowOverview(workflow); + + const confirmed = await this.promptService.confirm( + 'Execute this workflow?' + ); + + if (!confirmed) { + return WorkflowResult.cancelled(); + } + + // Execute steps + return this.promptService.progressTask( + async ({ updateProgress }) => { + const steps = this.sortStepsByDependencies(workflow.steps); + + for (let i = 0; i < steps.length; i++) { + const step = steps[i]; + updateProgress((i / steps.length) * 100, `Executing ${step.command}`); + + await this.executeStep(step, context); + } + + return WorkflowResult.success(context.getResults()); + }, + { title: `Workflow: ${workflow.name}` } + ); + } + + async generateWorkflowFromIntent(intent: string): Promise { + // Use learning system to generate workflow + const patterns = await this.findWorkflowPatterns(intent); + + if (patterns.length === 0) { + throw new Error('Could not generate workflow for intent'); + } + + // Select best pattern or let user choose + const selectedPattern = patterns.length === 1 + ? patterns[0] + : await this.promptService.select({ + message: 'Select workflow template:', + choices: patterns.map(p => ({ + name: `${p.name} (${p.confidence}% match)`, + value: p + })) + }); + + return this.customizeWorkflow(selectedPattern, intent); + } + + private async executeStep(step: WorkflowStep, context: WorkflowExecutionContext): Promise { + // Check conditions + if (step.condition && !this.evaluateCondition(step.condition, context)) { + context.skipStep(step.id, 'Condition not met'); + return; + } + + // Check dependencies + const missingDeps = step.dependsOn.filter(dep => !context.isStepCompleted(dep)); + if (missingDeps.length > 0) { + throw new WorkflowError(`Step ${step.id} has unmet dependencies: ${missingDeps.join(', ')}`); + } + + // Execute with retry policy + const retryPolicy = step.retryPolicy || { maxAttempts: 1 }; + let lastError: Error | null = null; + + for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt++) { + try { + const result = await this.commandRegistry.executeCommand(step.command, step.args); + context.completeStep(step.id, result); + return; + } catch (error) { + lastError = error as Error; + + if (attempt < retryPolicy.maxAttempts) { + await this.delay(retryPolicy.backoffMs || 1000); + } + } + } + + throw new WorkflowError(`Step ${step.id} failed after ${retryPolicy.maxAttempts} attempts: ${lastError?.message}`); + } +} +``` + +## Performance Optimization + +### Command Performance Monitoring +```typescript +// src/cli/performance/command-performance.ts +export class CommandPerformanceMonitor { + private metrics = new Map(); + + async measureCommand( + commandName: string, + executor: () => Promise + ): Promise { + const start = performance.now(); + const memBefore = process.memoryUsage(); + + try { + const result = await executor(); + const end = performance.now(); + const memAfter = process.memoryUsage(); + + this.recordMetrics(commandName, { + executionTime: end - start, + memoryDelta: memAfter.heapUsed - memBefore.heapUsed, + success: true + }); + + return result; + } catch (error) { + const end = performance.now(); + + this.recordMetrics(commandName, { + executionTime: end - start, + memoryDelta: 0, + success: false, + error: error as Error + }); + + throw error; + } + } + + private recordMetrics(command: string, measurement: PerformanceMeasurement): void { + if (!this.metrics.has(command)) { + this.metrics.set(command, new CommandMetrics(command)); + } + + const metrics = this.metrics.get(command)!; + metrics.addMeasurement(measurement); + + // Alert if performance degrades + if (metrics.getP95ExecutionTime() > 5000) { // 5 seconds + console.warn(`⚠️ Command '${command}' is performing slowly (P95: ${metrics.getP95ExecutionTime()}ms)`); + } + } + + getCommandReport(command: string): PerformanceReport { + const metrics = this.metrics.get(command); + if (!metrics) { + throw new Error(`No metrics found for command: ${command}`); + } + + return { + command, + totalExecutions: metrics.getTotalExecutions(), + successRate: metrics.getSuccessRate(), + avgExecutionTime: metrics.getAverageExecutionTime(), + p95ExecutionTime: metrics.getP95ExecutionTime(), + avgMemoryUsage: metrics.getAverageMemoryUsage(), + recommendations: this.generateRecommendations(metrics) + }; + } +} +``` + +## Smart Auto-completion + +### Intelligent Command Completion +```typescript +// src/cli/completion/intelligent-completion.ts +export class IntelligentCompletion { + constructor( + private learningService: LearningService, + private commandRegistry: ModularCommandRegistry + ) {} + + async generateCompletions( + partial: string, + context: CompletionContext + ): Promise { + const completions: Completion[] = []; + + // 1. Exact command matches + const exactMatches = this.commandRegistry.findCommandsByPrefix(partial); + completions.push(...exactMatches.map(cmd => ({ + value: cmd.name, + description: cmd.description, + type: 'command', + confidence: 1.0 + }))); + + // 2. Learning-based suggestions + const learnedSuggestions = await this.learningService.suggestCommands( + partial, + context + ); + completions.push(...learnedSuggestions); + + // 3. Context-aware suggestions + const contextualSuggestions = await this.generateContextualSuggestions( + partial, + context + ); + completions.push(...contextualSuggestions); + + // Sort by confidence and relevance + return completions + .sort((a, b) => b.confidence - a.confidence) + .slice(0, 10); // Top 10 suggestions + } + + private async generateContextualSuggestions( + partial: string, + context: CompletionContext + ): Promise { + const suggestions: Completion[] = []; + + // If in git repository, suggest git-related commands + if (context.isGitRepository) { + if (partial.startsWith('git')) { + suggestions.push({ + value: 'git commit', + description: 'Create git commit with generated message', + type: 'workflow', + confidence: 0.8 + }); + } + } + + // If package.json exists, suggest npm commands + if (context.hasPackageJson) { + if (partial.startsWith('npm') || partial.startsWith('swarm')) { + suggestions.push({ + value: 'swarm init', + description: 'Initialize swarm for this project', + type: 'workflow', + confidence: 0.9 + }); + } + } + + return suggestions; + } +} +``` + +## Success Metrics + +### CLI Performance Targets +- [ ] **Command Response**: <200ms average command execution time +- [ ] **File Decomposition**: index.ts (108KB) → <10KB per command module +- [ ] **Interactive UX**: Smart prompts with context awareness +- [ ] **Hook Integration**: Deep lifecycle integration with learning +- [ ] **Workflow Automation**: Intelligent multi-step command orchestration +- [ ] **Auto-completion**: >90% accuracy for command suggestions + +### User Experience Improvements +```typescript +const cliImprovements = { + before: { + commandResponse: '~500ms', + interactivity: 'Basic command parsing', + workflows: 'Manual command chaining', + suggestions: 'Static help text' + }, + + after: { + commandResponse: '<200ms with caching', + interactivity: 'Smart context-aware prompts', + workflows: 'Automated multi-step execution', + suggestions: 'Learning-based intelligent completion' + } +}; +``` + +## Related V3 Skills + +- `v3-core-implementation` - Core domain integration +- `v3-memory-unification` - Memory-backed command caching +- `v3-swarm-coordination` - CLI swarm management integration +- `v3-performance-optimization` - CLI performance monitoring + +## Usage Examples + +### Complete CLI Modernization +```bash +# Full CLI modernization implementation +Task("CLI modernization implementation", + "Implement modular commands, interactive prompts, and intelligent workflows", + "cli-hooks-developer") +``` + +### Interactive Command Enhancement +```bash +# Enhanced interactive commands +Codex-flow swarm init --interactive +Codex-flow learning start --guided +Codex-flow workflow create --from-intent "setup new project" +``` \ No newline at end of file diff --git a/.agents/skills/v3-core-implementation/SKILL.md b/.agents/skills/v3-core-implementation/SKILL.md new file mode 100644 index 0000000..d822836 --- /dev/null +++ b/.agents/skills/v3-core-implementation/SKILL.md @@ -0,0 +1,797 @@ +--- +name: "V3 Core Implementation" +description: "Core module implementation for Codex-flow v3. Implements DDD domains, clean architecture patterns, dependency injection, and modular TypeScript codebase with comprehensive testing." +--- + +# V3 Core Implementation + +## What This Skill Does + +Implements the core TypeScript modules for Codex-flow v3 following Domain-Driven Design principles, clean architecture patterns, and modern TypeScript best practices with comprehensive test coverage. + +## Quick Start + +```bash +# Initialize core implementation +Task("Core foundation", "Set up DDD domain structure and base classes", "core-implementer") + +# Domain implementation (parallel) +Task("Task domain", "Implement task management domain with entities and services", "core-implementer") +Task("Session domain", "Implement session management domain", "core-implementer") +Task("Health domain", "Implement health monitoring domain", "core-implementer") +``` + +## Core Implementation Architecture + +### Domain Structure +``` +src/ +├── core/ +│ ├── kernel/ # Microkernel pattern +│ │ ├── Codex-flow-kernel.ts +│ │ ├── domain-registry.ts +│ │ └── plugin-loader.ts +│ │ +│ ├── domains/ # DDD Bounded Contexts +│ │ ├── task-management/ +│ │ │ ├── entities/ +│ │ │ ├── value-objects/ +│ │ │ ├── services/ +│ │ │ ├── repositories/ +│ │ │ └── events/ +│ │ │ +│ │ ├── session-management/ +│ │ ├── health-monitoring/ +│ │ ├── lifecycle-management/ +│ │ └── event-coordination/ +│ │ +│ ├── shared/ # Shared kernel +│ │ ├── domain/ +│ │ │ ├── entity.ts +│ │ │ ├── value-object.ts +│ │ │ ├── domain-event.ts +│ │ │ └── aggregate-root.ts +│ │ │ +│ │ ├── infrastructure/ +│ │ │ ├── event-bus.ts +│ │ │ ├── dependency-container.ts +│ │ │ └── logger.ts +│ │ │ +│ │ └── types/ +│ │ ├── common.ts +│ │ ├── errors.ts +│ │ └── interfaces.ts +│ │ +│ └── application/ # Application services +│ ├── use-cases/ +│ ├── commands/ +│ ├── queries/ +│ └── handlers/ +``` + +## Base Domain Classes + +### Entity Base Class +```typescript +// src/core/shared/domain/entity.ts +export abstract class Entity { + protected readonly _id: T; + private _domainEvents: DomainEvent[] = []; + + constructor(id: T) { + this._id = id; + } + + get id(): T { + return this._id; + } + + public equals(object?: Entity): boolean { + if (object == null || object == undefined) { + return false; + } + + if (this === object) { + return true; + } + + if (!(object instanceof Entity)) { + return false; + } + + return this._id === object._id; + } + + protected addDomainEvent(domainEvent: DomainEvent): void { + this._domainEvents.push(domainEvent); + } + + public getUncommittedEvents(): DomainEvent[] { + return this._domainEvents; + } + + public markEventsAsCommitted(): void { + this._domainEvents = []; + } +} +``` + +### Value Object Base Class +```typescript +// src/core/shared/domain/value-object.ts +export abstract class ValueObject { + protected readonly props: T; + + constructor(props: T) { + this.props = Object.freeze(props); + } + + public equals(object?: ValueObject): boolean { + if (object == null || object == undefined) { + return false; + } + + if (this === object) { + return true; + } + + return JSON.stringify(this.props) === JSON.stringify(object.props); + } + + get value(): T { + return this.props; + } +} +``` + +### Aggregate Root +```typescript +// src/core/shared/domain/aggregate-root.ts +export abstract class AggregateRoot extends Entity { + private _version: number = 0; + + get version(): number { + return this._version; + } + + protected incrementVersion(): void { + this._version++; + } + + public applyEvent(event: DomainEvent): void { + this.addDomainEvent(event); + this.incrementVersion(); + } +} +``` + +## Task Management Domain Implementation + +### Task Entity +```typescript +// src/core/domains/task-management/entities/task.entity.ts +import { AggregateRoot } from '../../../shared/domain/aggregate-root'; +import { TaskId } from '../value-objects/task-id.vo'; +import { TaskStatus } from '../value-objects/task-status.vo'; +import { Priority } from '../value-objects/priority.vo'; +import { TaskAssignedEvent } from '../events/task-assigned.event'; + +interface TaskProps { + id: TaskId; + description: string; + priority: Priority; + status: TaskStatus; + assignedAgentId?: string; + createdAt: Date; + updatedAt: Date; +} + +export class Task extends AggregateRoot { + private props: TaskProps; + + private constructor(props: TaskProps) { + super(props.id); + this.props = props; + } + + static create(description: string, priority: Priority): Task { + const task = new Task({ + id: TaskId.create(), + description, + priority, + status: TaskStatus.pending(), + createdAt: new Date(), + updatedAt: new Date() + }); + + return task; + } + + static reconstitute(props: TaskProps): Task { + return new Task(props); + } + + public assignTo(agentId: string): void { + if (this.props.status.equals(TaskStatus.completed())) { + throw new Error('Cannot assign completed task'); + } + + this.props.assignedAgentId = agentId; + this.props.status = TaskStatus.assigned(); + this.props.updatedAt = new Date(); + + this.applyEvent(new TaskAssignedEvent( + this.id.value, + agentId, + this.props.priority + )); + } + + public complete(result: TaskResult): void { + if (!this.props.assignedAgentId) { + throw new Error('Cannot complete unassigned task'); + } + + this.props.status = TaskStatus.completed(); + this.props.updatedAt = new Date(); + + this.applyEvent(new TaskCompletedEvent( + this.id.value, + result, + this.calculateDuration() + )); + } + + // Getters + get description(): string { return this.props.description; } + get priority(): Priority { return this.props.priority; } + get status(): TaskStatus { return this.props.status; } + get assignedAgentId(): string | undefined { return this.props.assignedAgentId; } + get createdAt(): Date { return this.props.createdAt; } + get updatedAt(): Date { return this.props.updatedAt; } + + private calculateDuration(): number { + return this.props.updatedAt.getTime() - this.props.createdAt.getTime(); + } +} +``` + +### Task Value Objects +```typescript +// src/core/domains/task-management/value-objects/task-id.vo.ts +export class TaskId extends ValueObject { + private constructor(value: string) { + super({ value }); + } + + static create(): TaskId { + return new TaskId(crypto.randomUUID()); + } + + static fromString(id: string): TaskId { + if (!id || id.length === 0) { + throw new Error('TaskId cannot be empty'); + } + return new TaskId(id); + } + + get value(): string { + return this.props.value; + } +} + +// src/core/domains/task-management/value-objects/task-status.vo.ts +type TaskStatusType = 'pending' | 'assigned' | 'in_progress' | 'completed' | 'failed'; + +export class TaskStatus extends ValueObject { + private constructor(status: TaskStatusType) { + super({ value: status }); + } + + static pending(): TaskStatus { return new TaskStatus('pending'); } + static assigned(): TaskStatus { return new TaskStatus('assigned'); } + static inProgress(): TaskStatus { return new TaskStatus('in_progress'); } + static completed(): TaskStatus { return new TaskStatus('completed'); } + static failed(): TaskStatus { return new TaskStatus('failed'); } + + get value(): TaskStatusType { + return this.props.value; + } + + public isPending(): boolean { return this.value === 'pending'; } + public isAssigned(): boolean { return this.value === 'assigned'; } + public isInProgress(): boolean { return this.value === 'in_progress'; } + public isCompleted(): boolean { return this.value === 'completed'; } + public isFailed(): boolean { return this.value === 'failed'; } +} + +// src/core/domains/task-management/value-objects/priority.vo.ts +type PriorityLevel = 'low' | 'medium' | 'high' | 'critical'; + +export class Priority extends ValueObject { + private constructor(level: PriorityLevel) { + super({ value: level }); + } + + static low(): Priority { return new Priority('low'); } + static medium(): Priority { return new Priority('medium'); } + static high(): Priority { return new Priority('high'); } + static critical(): Priority { return new Priority('critical'); } + + get value(): PriorityLevel { + return this.props.value; + } + + public getNumericValue(): number { + const priorities = { low: 1, medium: 2, high: 3, critical: 4 }; + return priorities[this.value]; + } +} +``` + +## Domain Services + +### Task Scheduling Service +```typescript +// src/core/domains/task-management/services/task-scheduling.service.ts +import { Injectable } from '../../../shared/infrastructure/dependency-container'; +import { Task } from '../entities/task.entity'; +import { Priority } from '../value-objects/priority.vo'; + +@Injectable() +export class TaskSchedulingService { + public prioritizeTasks(tasks: Task[]): Task[] { + return tasks.sort((a, b) => + b.priority.getNumericValue() - a.priority.getNumericValue() + ); + } + + public canSchedule(task: Task, agentCapacity: number): boolean { + if (agentCapacity <= 0) return false; + + // Critical tasks always schedulable + if (task.priority.equals(Priority.critical())) return true; + + // Other logic based on capacity + return true; + } + + public calculateEstimatedDuration(task: Task): number { + // Simple heuristic - would use ML in real implementation + const baseTime = 300000; // 5 minutes + const priorityMultiplier = { + low: 0.5, + medium: 1.0, + high: 1.5, + critical: 2.0 + }; + + return baseTime * priorityMultiplier[task.priority.value]; + } +} +``` + +## Repository Interfaces & Implementations + +### Task Repository Interface +```typescript +// src/core/domains/task-management/repositories/task.repository.ts +export interface ITaskRepository { + save(task: Task): Promise; + findById(id: TaskId): Promise; + findByAgentId(agentId: string): Promise; + findByStatus(status: TaskStatus): Promise; + findPendingTasks(): Promise; + delete(id: TaskId): Promise; +} +``` + +### SQLite Implementation +```typescript +// src/core/domains/task-management/repositories/sqlite-task.repository.ts +@Injectable() +export class SqliteTaskRepository implements ITaskRepository { + constructor( + @Inject('Database') private db: Database, + @Inject('Logger') private logger: ILogger + ) {} + + async save(task: Task): Promise { + const sql = ` + INSERT OR REPLACE INTO tasks ( + id, description, priority, status, assigned_agent_id, created_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?) + `; + + await this.db.run(sql, [ + task.id.value, + task.description, + task.priority.value, + task.status.value, + task.assignedAgentId, + task.createdAt.toISOString(), + task.updatedAt.toISOString() + ]); + + this.logger.debug(`Task saved: ${task.id.value}`); + } + + async findById(id: TaskId): Promise { + const sql = 'SELECT * FROM tasks WHERE id = ?'; + const row = await this.db.get(sql, [id.value]); + + return row ? this.mapRowToTask(row) : null; + } + + async findPendingTasks(): Promise { + const sql = 'SELECT * FROM tasks WHERE status = ? ORDER BY priority DESC, created_at ASC'; + const rows = await this.db.all(sql, ['pending']); + + return rows.map(row => this.mapRowToTask(row)); + } + + private mapRowToTask(row: any): Task { + return Task.reconstitute({ + id: TaskId.fromString(row.id), + description: row.description, + priority: Priority.fromString(row.priority), + status: TaskStatus.fromString(row.status), + assignedAgentId: row.assigned_agent_id, + createdAt: new Date(row.created_at), + updatedAt: new Date(row.updated_at) + }); + } +} +``` + +## Application Layer + +### Use Case Implementation +```typescript +// src/core/application/use-cases/assign-task.use-case.ts +@Injectable() +export class AssignTaskUseCase { + constructor( + @Inject('TaskRepository') private taskRepository: ITaskRepository, + @Inject('AgentRepository') private agentRepository: IAgentRepository, + @Inject('DomainEventBus') private eventBus: DomainEventBus, + @Inject('Logger') private logger: ILogger + ) {} + + async execute(command: AssignTaskCommand): Promise { + try { + // 1. Validate command + await this.validateCommand(command); + + // 2. Load aggregates + const task = await this.taskRepository.findById(command.taskId); + if (!task) { + throw new TaskNotFoundError(command.taskId); + } + + const agent = await this.agentRepository.findById(command.agentId); + if (!agent) { + throw new AgentNotFoundError(command.agentId); + } + + // 3. Business logic + if (!agent.canAcceptTask(task)) { + throw new AgentCannotAcceptTaskError(command.agentId, command.taskId); + } + + task.assignTo(command.agentId); + agent.acceptTask(task.id); + + // 4. Persist changes + await Promise.all([ + this.taskRepository.save(task), + this.agentRepository.save(agent) + ]); + + // 5. Publish domain events + const events = [ + ...task.getUncommittedEvents(), + ...agent.getUncommittedEvents() + ]; + + for (const event of events) { + await this.eventBus.publish(event); + } + + task.markEventsAsCommitted(); + agent.markEventsAsCommitted(); + + // 6. Return result + this.logger.info(`Task ${command.taskId.value} assigned to agent ${command.agentId}`); + + return AssignTaskResult.success({ + taskId: task.id, + agentId: command.agentId, + assignedAt: new Date() + }); + + } catch (error) { + this.logger.error(`Failed to assign task ${command.taskId.value}:`, error); + return AssignTaskResult.failure(error); + } + } + + private async validateCommand(command: AssignTaskCommand): Promise { + if (!command.taskId) { + throw new ValidationError('Task ID is required'); + } + if (!command.agentId) { + throw new ValidationError('Agent ID is required'); + } + } +} +``` + +## Dependency Injection Setup + +### Container Configuration +```typescript +// src/core/shared/infrastructure/dependency-container.ts +import { Container } from 'inversify'; +import { TYPES } from './types'; + +export class DependencyContainer { + private container: Container; + + constructor() { + this.container = new Container(); + this.setupBindings(); + } + + private setupBindings(): void { + // Repositories + this.container.bind(TYPES.TaskRepository) + .to(SqliteTaskRepository) + .inSingletonScope(); + + this.container.bind(TYPES.AgentRepository) + .to(SqliteAgentRepository) + .inSingletonScope(); + + // Services + this.container.bind(TYPES.TaskSchedulingService) + .to(TaskSchedulingService) + .inSingletonScope(); + + // Use Cases + this.container.bind(TYPES.AssignTaskUseCase) + .to(AssignTaskUseCase) + .inSingletonScope(); + + // Infrastructure + this.container.bind(TYPES.Logger) + .to(ConsoleLogger) + .inSingletonScope(); + + this.container.bind(TYPES.DomainEventBus) + .to(InMemoryDomainEventBus) + .inSingletonScope(); + } + + get(serviceIdentifier: symbol): T { + return this.container.get(serviceIdentifier); + } + + bind(serviceIdentifier: symbol): BindingToSyntax { + return this.container.bind(serviceIdentifier); + } +} +``` + +## Modern TypeScript Configuration + +### Strict TypeScript Setup +```json +// tsconfig.json +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022"], + "module": "NodeNext", + "moduleResolution": "NodeNext", + "declaration": true, + "outDir": "./dist", + "strict": true, + "exactOptionalPropertyTypes": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "noUncheckedIndexedAccess": true, + "noImplicitOverride": true, + "experimentalDecorators": true, + "emitDecoratorMetadata": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "baseUrl": ".", + "paths": { + "@/*": ["src/*"], + "@core/*": ["src/core/*"], + "@shared/*": ["src/core/shared/*"], + "@domains/*": ["src/core/domains/*"] + } + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"] +} +``` + +## Testing Implementation + +### Domain Unit Tests +```typescript +// src/core/domains/task-management/__tests__/entities/task.entity.test.ts +describe('Task Entity', () => { + let task: Task; + + beforeEach(() => { + task = Task.create('Test task', Priority.medium()); + }); + + describe('creation', () => { + it('should create task with pending status', () => { + expect(task.status.isPending()).toBe(true); + expect(task.description).toBe('Test task'); + expect(task.priority.equals(Priority.medium())).toBe(true); + }); + + it('should generate unique ID', () => { + const task1 = Task.create('Task 1', Priority.low()); + const task2 = Task.create('Task 2', Priority.low()); + + expect(task1.id.equals(task2.id)).toBe(false); + }); + }); + + describe('assignment', () => { + it('should assign to agent and change status', () => { + const agentId = 'agent-123'; + + task.assignTo(agentId); + + expect(task.assignedAgentId).toBe(agentId); + expect(task.status.isAssigned()).toBe(true); + }); + + it('should emit TaskAssignedEvent when assigned', () => { + const agentId = 'agent-123'; + + task.assignTo(agentId); + + const events = task.getUncommittedEvents(); + expect(events).toHaveLength(1); + expect(events[0]).toBeInstanceOf(TaskAssignedEvent); + }); + + it('should not allow assignment of completed task', () => { + task.assignTo('agent-123'); + task.complete(TaskResult.success('done')); + + expect(() => task.assignTo('agent-456')) + .toThrow('Cannot assign completed task'); + }); + }); +}); +``` + +### Integration Tests +```typescript +// src/core/domains/task-management/__tests__/integration/task-repository.integration.test.ts +describe('TaskRepository Integration', () => { + let repository: SqliteTaskRepository; + let db: Database; + + beforeEach(async () => { + db = new Database(':memory:'); + await setupTasksTable(db); + repository = new SqliteTaskRepository(db, new ConsoleLogger()); + }); + + afterEach(async () => { + await db.close(); + }); + + it('should save and retrieve task', async () => { + const task = Task.create('Test task', Priority.high()); + + await repository.save(task); + const retrieved = await repository.findById(task.id); + + expect(retrieved).toBeDefined(); + expect(retrieved!.id.equals(task.id)).toBe(true); + expect(retrieved!.description).toBe('Test task'); + expect(retrieved!.priority.equals(Priority.high())).toBe(true); + }); + + it('should find pending tasks ordered by priority', async () => { + const lowTask = Task.create('Low priority', Priority.low()); + const highTask = Task.create('High priority', Priority.high()); + + await repository.save(lowTask); + await repository.save(highTask); + + const pending = await repository.findPendingTasks(); + + expect(pending).toHaveLength(2); + expect(pending[0].id.equals(highTask.id)).toBe(true); // High priority first + expect(pending[1].id.equals(lowTask.id)).toBe(true); + }); +}); +``` + +## Performance Optimizations + +### Entity Caching +```typescript +// src/core/shared/infrastructure/entity-cache.ts +@Injectable() +export class EntityCache> { + private cache = new Map(); + private readonly ttl: number = 300000; // 5 minutes + + set(id: string, entity: T): void { + this.cache.set(id, { entity, timestamp: Date.now() }); + } + + get(id: string): T | null { + const cached = this.cache.get(id); + if (!cached) return null; + + // Check TTL + if (Date.now() - cached.timestamp > this.ttl) { + this.cache.delete(id); + return null; + } + + return cached.entity; + } + + invalidate(id: string): void { + this.cache.delete(id); + } + + clear(): void { + this.cache.clear(); + } +} +``` + +## Success Metrics + +- [ ] **Domain Isolation**: 100% clean dependency boundaries +- [ ] **Test Coverage**: >90% unit test coverage for domain logic +- [ ] **Type Safety**: Strict TypeScript compilation with zero any types +- [ ] **Performance**: <50ms average use case execution time +- [ ] **Memory Efficiency**: <100MB heap usage for core domains +- [ ] **Plugin Architecture**: Modular domain loading capability + +## Related V3 Skills + +- `v3-ddd-architecture` - DDD architectural design +- `v3-mcp-optimization` - MCP server integration +- `v3-memory-unification` - AgentDB repository integration +- `v3-swarm-coordination` - Swarm domain implementation + +## Usage Examples + +### Complete Core Implementation +```bash +# Full core module implementation +Task("Core implementation", + "Implement all core domains with DDD patterns and comprehensive testing", + "core-implementer") +``` + +### Domain-Specific Implementation +```bash +# Single domain implementation +Task("Task domain implementation", + "Implement task management domain with entities, services, and repositories", + "core-implementer") +``` \ No newline at end of file diff --git a/.agents/skills/v3-ddd-architecture/SKILL.md b/.agents/skills/v3-ddd-architecture/SKILL.md new file mode 100644 index 0000000..e068667 --- /dev/null +++ b/.agents/skills/v3-ddd-architecture/SKILL.md @@ -0,0 +1,442 @@ +--- +name: "V3 DDD Architecture" +description: "Domain-Driven Design architecture for Codex-flow v3. Implements modular, bounded context architecture with clean separation of concerns and microkernel pattern." +--- + +# V3 DDD Architecture + +## What This Skill Does + +Designs and implements Domain-Driven Design (DDD) architecture for Codex-flow v3, decomposing god objects into bounded contexts, implementing clean architecture patterns, and enabling modular, testable code structure. + +## Quick Start + +```bash +# Initialize DDD architecture analysis +Task("Architecture analysis", "Analyze current architecture and design DDD boundaries", "core-architect") + +# Domain modeling (parallel) +Task("Domain decomposition", "Break down orchestrator god object into domains", "core-architect") +Task("Context mapping", "Map bounded contexts and relationships", "core-architect") +Task("Interface design", "Design clean domain interfaces", "core-architect") +``` + +## DDD Implementation Strategy + +### Current Architecture Analysis +``` +├── PROBLEMATIC: core/orchestrator.ts (1,440 lines - GOD OBJECT) +│ ├── Task management responsibilities +│ ├── Session management responsibilities +│ ├── Health monitoring responsibilities +│ ├── Lifecycle management responsibilities +│ └── Event coordination responsibilities +│ +└── TARGET: Modular DDD Architecture + ├── core/domains/ + │ ├── task-management/ + │ ├── session-management/ + │ ├── health-monitoring/ + │ ├── lifecycle-management/ + │ └── event-coordination/ + └── core/shared/ + ├── interfaces/ + ├── value-objects/ + └── domain-events/ +``` + +### Domain Boundaries + +#### 1. Task Management Domain +```typescript +// core/domains/task-management/ +interface TaskManagementDomain { + // Entities + Task: TaskEntity; + TaskQueue: TaskQueueEntity; + + // Value Objects + TaskId: TaskIdVO; + TaskStatus: TaskStatusVO; + Priority: PriorityVO; + + // Services + TaskScheduler: TaskSchedulingService; + TaskValidator: TaskValidationService; + + // Repository + TaskRepository: ITaskRepository; +} +``` + +#### 2. Session Management Domain +```typescript +// core/domains/session-management/ +interface SessionManagementDomain { + // Entities + Session: SessionEntity; + SessionState: SessionStateEntity; + + // Value Objects + SessionId: SessionIdVO; + SessionStatus: SessionStatusVO; + + // Services + SessionLifecycle: SessionLifecycleService; + SessionPersistence: SessionPersistenceService; + + // Repository + SessionRepository: ISessionRepository; +} +``` + +#### 3. Health Monitoring Domain +```typescript +// core/domains/health-monitoring/ +interface HealthMonitoringDomain { + // Entities + HealthCheck: HealthCheckEntity; + Metric: MetricEntity; + + // Value Objects + HealthStatus: HealthStatusVO; + Threshold: ThresholdVO; + + // Services + HealthCollector: HealthCollectionService; + AlertManager: AlertManagementService; + + // Repository + MetricsRepository: IMetricsRepository; +} +``` + +## Microkernel Architecture Pattern + +### Core Kernel +```typescript +// core/kernel/Codex-flow-kernel.ts +export class ClaudeFlowKernel { + private domains: Map = new Map(); + private eventBus: DomainEventBus; + private dependencyContainer: Container; + + async initialize(): Promise { + // Load core domains + await this.loadDomain('task-management', new TaskManagementDomain()); + await this.loadDomain('session-management', new SessionManagementDomain()); + await this.loadDomain('health-monitoring', new HealthMonitoringDomain()); + + // Wire up domain events + this.setupDomainEventHandlers(); + } + + async loadDomain(name: string, domain: Domain): Promise { + await domain.initialize(this.dependencyContainer); + this.domains.set(name, domain); + } + + getDomain(name: string): T { + const domain = this.domains.get(name); + if (!domain) { + throw new DomainNotLoadedError(name); + } + return domain as T; + } +} +``` + +### Plugin Architecture +```typescript +// core/plugins/ +interface DomainPlugin { + name: string; + version: string; + dependencies: string[]; + + initialize(kernel: ClaudeFlowKernel): Promise; + shutdown(): Promise; +} + +// Example: Swarm Coordination Plugin +export class SwarmCoordinationPlugin implements DomainPlugin { + name = 'swarm-coordination'; + version = '3.0.0'; + dependencies = ['task-management', 'session-management']; + + async initialize(kernel: ClaudeFlowKernel): Promise { + const taskDomain = kernel.getDomain('task-management'); + const sessionDomain = kernel.getDomain('session-management'); + + // Register swarm coordination services + this.swarmCoordinator = new UnifiedSwarmCoordinator(taskDomain, sessionDomain); + kernel.registerService('swarm-coordinator', this.swarmCoordinator); + } +} +``` + +## Domain Events & Integration + +### Event-Driven Communication +```typescript +// core/shared/domain-events/ +abstract class DomainEvent { + public readonly eventId: string; + public readonly aggregateId: string; + public readonly occurredOn: Date; + public readonly eventVersion: number; + + constructor(aggregateId: string) { + this.eventId = crypto.randomUUID(); + this.aggregateId = aggregateId; + this.occurredOn = new Date(); + this.eventVersion = 1; + } +} + +// Task domain events +export class TaskAssignedEvent extends DomainEvent { + constructor( + taskId: string, + public readonly agentId: string, + public readonly priority: Priority + ) { + super(taskId); + } +} + +export class TaskCompletedEvent extends DomainEvent { + constructor( + taskId: string, + public readonly result: TaskResult, + public readonly duration: number + ) { + super(taskId); + } +} + +// Event handlers +@EventHandler(TaskCompletedEvent) +export class TaskCompletedHandler { + constructor( + private metricsRepository: IMetricsRepository, + private sessionService: SessionLifecycleService + ) {} + + async handle(event: TaskCompletedEvent): Promise { + // Update metrics + await this.metricsRepository.recordTaskCompletion( + event.aggregateId, + event.duration + ); + + // Update session state + await this.sessionService.markTaskCompleted( + event.aggregateId, + event.result + ); + } +} +``` + +## Clean Architecture Layers + +```typescript +// Architecture layers +┌─────────────────────────────────────────┐ +│ Presentation │ ← CLI, API, UI +├─────────────────────────────────────────┤ +│ Application │ ← Use Cases, Commands +├─────────────────────────────────────────┤ +│ Domain │ ← Entities, Services, Events +├─────────────────────────────────────────┤ +│ Infrastructure │ ← DB, MCP, External APIs +└─────────────────────────────────────────┘ + +// Dependency direction: Outside → Inside +// Domain layer has NO external dependencies +``` + +### Application Layer (Use Cases) +```typescript +// core/application/use-cases/ +export class AssignTaskUseCase { + constructor( + private taskRepository: ITaskRepository, + private agentRepository: IAgentRepository, + private eventBus: DomainEventBus + ) {} + + async execute(command: AssignTaskCommand): Promise { + // 1. Validate command + await this.validateCommand(command); + + // 2. Load aggregates + const task = await this.taskRepository.findById(command.taskId); + const agent = await this.agentRepository.findById(command.agentId); + + // 3. Business logic (in domain) + task.assignTo(agent); + + // 4. Persist changes + await this.taskRepository.save(task); + + // 5. Publish domain events + task.getUncommittedEvents().forEach(event => + this.eventBus.publish(event) + ); + + // 6. Return result + return TaskResult.success(task); + } +} +``` + +## Module Configuration + +### Bounded Context Modules +```typescript +// core/domains/task-management/module.ts +export const taskManagementModule = { + name: 'task-management', + + entities: [ + TaskEntity, + TaskQueueEntity + ], + + valueObjects: [ + TaskIdVO, + TaskStatusVO, + PriorityVO + ], + + services: [ + TaskSchedulingService, + TaskValidationService + ], + + repositories: [ + { provide: ITaskRepository, useClass: SqliteTaskRepository } + ], + + eventHandlers: [ + TaskAssignedHandler, + TaskCompletedHandler + ] +}; +``` + +## Migration Strategy + +### Phase 1: Extract Domain Services +```typescript +// Extract services from orchestrator.ts +const extractionPlan = { + week1: [ + 'TaskManager → task-management domain', + 'SessionManager → session-management domain' + ], + week2: [ + 'HealthMonitor → health-monitoring domain', + 'LifecycleManager → lifecycle-management domain' + ], + week3: [ + 'EventCoordinator → event-coordination domain', + 'Wire up domain events' + ] +}; +``` + +### Phase 2: Implement Clean Interfaces +```typescript +// Clean separation with dependency injection +export class TaskController { + constructor( + @Inject('AssignTaskUseCase') private assignTask: AssignTaskUseCase, + @Inject('CompleteTaskUseCase') private completeTask: CompleteTaskUseCase + ) {} + + async assign(request: AssignTaskRequest): Promise { + const command = AssignTaskCommand.fromRequest(request); + const result = await this.assignTask.execute(command); + return TaskResponse.fromResult(result); + } +} +``` + +### Phase 3: Plugin System +```typescript +// Enable plugin-based extensions +const pluginSystem = { + core: ['task-management', 'session-management', 'health-monitoring'], + optional: ['swarm-coordination', 'learning-integration', 'performance-monitoring'] +}; +``` + +## Testing Strategy + +### Domain Testing (London School TDD) +```typescript +// Pure domain logic testing +describe('Task Entity', () => { + let task: TaskEntity; + let mockAgent: jest.Mocked; + + beforeEach(() => { + task = new TaskEntity(TaskId.create(), 'Test task'); + mockAgent = createMock(); + }); + + it('should assign to agent when valid', () => { + mockAgent.canAcceptTask.mockReturnValue(true); + + task.assignTo(mockAgent); + + expect(task.assignedAgent).toBe(mockAgent); + expect(task.status.value).toBe('assigned'); + }); + + it('should emit TaskAssignedEvent when assigned', () => { + mockAgent.canAcceptTask.mockReturnValue(true); + + task.assignTo(mockAgent); + + const events = task.getUncommittedEvents(); + expect(events).toHaveLength(1); + expect(events[0]).toBeInstanceOf(TaskAssignedEvent); + }); +}); +``` + +## Success Metrics + +- [ ] **God Object Elimination**: orchestrator.ts (1,440 lines) → 5 focused domains (<300 lines each) +- [ ] **Bounded Context Isolation**: 100% domain independence +- [ ] **Plugin Architecture**: Core + optional modules loading +- [ ] **Clean Architecture**: Dependency inversion maintained +- [ ] **Event-Driven Communication**: Loose coupling between domains +- [ ] **Test Coverage**: >90% domain logic coverage + +## Related V3 Skills + +- `v3-core-implementation` - Implementation of DDD domains +- `v3-memory-unification` - AgentDB integration within bounded contexts +- `v3-swarm-coordination` - Swarm coordination as domain plugin +- `v3-performance-optimization` - Performance optimization across domains + +## Usage Examples + +### Complete Domain Extraction +```bash +# Full DDD architecture implementation +Task("DDD architecture implementation", + "Extract orchestrator into DDD domains with clean architecture", + "core-architect") +``` + +### Plugin Development +```bash +# Create domain plugin +npm run create:plugin -- --name swarm-coordination --template domain +``` \ No newline at end of file diff --git a/.agents/skills/v3-integration-deep/SKILL.md b/.agents/skills/v3-integration-deep/SKILL.md new file mode 100644 index 0000000..ff62427 --- /dev/null +++ b/.agents/skills/v3-integration-deep/SKILL.md @@ -0,0 +1,241 @@ +--- +name: "V3 Deep Integration" +description: "Deep agentic-flow@alpha integration implementing ADR-001. Eliminates 10,000+ duplicate lines by building Codex-flow as specialized extension rather than parallel implementation." +--- + +# V3 Deep Integration + +## What This Skill Does + +Transforms Codex-flow from parallel implementation to specialized extension of agentic-flow@alpha, eliminating massive code duplication while achieving performance improvements and feature parity. + +## Quick Start + +```bash +# Initialize deep integration +Task("Integration architecture", "Design agentic-flow@alpha adapter layer", "v3-integration-architect") + +# Feature integration (parallel) +Task("SONA integration", "Integrate 5 SONA learning modes", "v3-integration-architect") +Task("Flash Attention", "Implement 2.49x-7.47x speedup", "v3-integration-architect") +Task("AgentDB coordination", "Setup 150x-12,500x search", "v3-integration-architect") +``` + +## Code Deduplication Strategy + +### Current Overlap → Integration +``` +┌─────────────────────────────────────────┐ +│ Codex-flow agentic-flow │ +├─────────────────────────────────────────┤ +│ SwarmCoordinator → Swarm System │ 80% overlap (eliminate) +│ AgentManager → Agent Lifecycle │ 70% overlap (eliminate) +│ TaskScheduler → Task Execution │ 60% overlap (eliminate) +│ SessionManager → Session Mgmt │ 50% overlap (eliminate) +└─────────────────────────────────────────┘ + +TARGET: <5,000 lines (vs 15,000+ currently) +``` + +## agentic-flow@alpha Feature Integration + +### SONA Learning Modes +```typescript +class SONAIntegration { + async initializeMode(mode: SONAMode): Promise { + switch(mode) { + case 'real-time': // ~0.05ms adaptation + case 'balanced': // general purpose + case 'research': // deep exploration + case 'edge': // resource-constrained + case 'batch': // high-throughput + } + await this.agenticFlow.sona.setMode(mode); + } +} +``` + +### Flash Attention Integration +```typescript +class FlashAttentionIntegration { + async optimizeAttention(): Promise { + return this.agenticFlow.attention.flashAttention({ + speedupTarget: '2.49x-7.47x', + memoryReduction: '50-75%', + mechanisms: ['multi-head', 'linear', 'local', 'global'] + }); + } +} +``` + +### AgentDB Coordination +```typescript +class AgentDBIntegration { + async setupCrossAgentMemory(): Promise { + await this.agentdb.enableCrossAgentSharing({ + indexType: 'HNSW', + speedupTarget: '150x-12500x', + dimensions: 1536 + }); + } +} +``` + +### MCP Tools Integration +```typescript +class MCPToolsIntegration { + async integrateBuiltinTools(): Promise { + // Leverage 213 pre-built tools + const tools = await this.agenticFlow.mcp.getAvailableTools(); + await this.registerClaudeFlowSpecificTools(tools); + + // Use 19 hook types + const hookTypes = await this.agenticFlow.hooks.getTypes(); + await this.configureClaudeFlowHooks(hookTypes); + } +} +``` + +## Migration Implementation + +### Phase 1: Adapter Layer +```typescript +import { Agent as AgenticFlowAgent } from 'agentic-flow@alpha'; + +export class ClaudeFlowAgent extends AgenticFlowAgent { + async handleClaudeFlowTask(task: ClaudeTask): Promise { + return this.executeWithSONA(task); + } + + // Backward compatibility + async legacyCompatibilityLayer(oldAPI: any): Promise { + return this.adaptToNewAPI(oldAPI); + } +} +``` + +### Phase 2: System Migration +```typescript +class SystemMigration { + async migrateSwarmCoordination(): Promise { + // Replace SwarmCoordinator (800+ lines) with agentic-flow Swarm + const swarmConfig = await this.extractSwarmConfig(); + await this.agenticFlow.swarm.initialize(swarmConfig); + } + + async migrateAgentManagement(): Promise { + // Replace AgentManager (1,736+ lines) with agentic-flow lifecycle + const agents = await this.extractActiveAgents(); + for (const agent of agents) { + await this.agenticFlow.agent.create(agent); + } + } + + async migrateTaskExecution(): Promise { + // Replace TaskScheduler with agentic-flow task graph + const tasks = await this.extractTasks(); + await this.agenticFlow.task.executeGraph(this.buildTaskGraph(tasks)); + } +} +``` + +### Phase 3: Cleanup +```typescript +class CodeCleanup { + async removeDeprecatedCode(): Promise { + // Remove massive duplicate implementations + await this.removeFile('src/core/SwarmCoordinator.ts'); // 800+ lines + await this.removeFile('src/agents/AgentManager.ts'); // 1,736+ lines + await this.removeFile('src/task/TaskScheduler.ts'); // 500+ lines + + // Total reduction: 10,000+ → <5,000 lines + } +} +``` + +## RL Algorithm Integration + +```typescript +class RLIntegration { + algorithms = [ + 'PPO', 'DQN', 'A2C', 'MCTS', 'Q-Learning', + 'SARSA', 'Actor-Critic', 'Decision-Transformer' + ]; + + async optimizeAgentBehavior(): Promise { + for (const algorithm of this.algorithms) { + await this.agenticFlow.rl.train(algorithm, { + episodes: 1000, + rewardFunction: this.claudeFlowRewardFunction + }); + } + } +} +``` + +## Performance Integration + +### Flash Attention Targets +```typescript +const attentionBenchmark = { + baseline: 'current attention mechanism', + target: '2.49x-7.47x improvement', + memoryReduction: '50-75%', + implementation: 'agentic-flow@alpha Flash Attention' +}; +``` + +### AgentDB Search Performance +```typescript +const searchBenchmark = { + baseline: 'linear search in current systems', + target: '150x-12,500x via HNSW indexing', + implementation: 'agentic-flow@alpha AgentDB' +}; +``` + +## Backward Compatibility + +### Gradual Migration +```typescript +class BackwardCompatibility { + // Phase 1: Dual operation + async enableDualOperation(): Promise { + this.oldSystem.continue(); + this.newSystem.initialize(); + this.syncState(this.oldSystem, this.newSystem); + } + + // Phase 2: Feature-by-feature migration + async migrateGradually(): Promise { + const features = this.getAllFeatures(); + for (const feature of features) { + await this.migrateFeature(feature); + await this.validateFeatureParity(feature); + } + } + + // Phase 3: Complete transition + async completeTransition(): Promise { + await this.validateFullParity(); + await this.deprecateOldSystem(); + } +} +``` + +## Success Metrics + +- **Code Reduction**: <5,000 lines orchestration (vs 15,000+) +- **Performance**: 2.49x-7.47x Flash Attention speedup +- **Search**: 150x-12,500x AgentDB improvement +- **Memory**: 50-75% usage reduction +- **Feature Parity**: 100% v2 functionality maintained +- **SONA**: <0.05ms adaptation time +- **Integration**: All 213 MCP tools + 19 hook types available + +## Related V3 Skills + +- `v3-memory-unification` - Memory system integration +- `v3-performance-optimization` - Performance target validation +- `v3-swarm-coordination` - Swarm system migration +- `v3-security-overhaul` - Secure integration patterns \ No newline at end of file diff --git a/.agents/skills/v3-mcp-optimization/SKILL.md b/.agents/skills/v3-mcp-optimization/SKILL.md new file mode 100644 index 0000000..eaa47de --- /dev/null +++ b/.agents/skills/v3-mcp-optimization/SKILL.md @@ -0,0 +1,777 @@ +--- +name: "V3 MCP Optimization" +description: "MCP server optimization and transport layer enhancement for Codex-flow v3. Implements connection pooling, load balancing, tool registry optimization, and performance monitoring for sub-100ms response times." +--- + +# V3 MCP Optimization + +## What This Skill Does + +Optimizes Codex-flow v3 MCP (Model Context Protocol) server implementation with advanced transport layer optimizations, connection pooling, load balancing, and comprehensive performance monitoring to achieve sub-100ms response times. + +## Quick Start + +```bash +# Initialize MCP optimization analysis +Task("MCP architecture", "Analyze current MCP server performance and bottlenecks", "mcp-specialist") + +# Optimization implementation (parallel) +Task("Connection pooling", "Implement MCP connection pooling and reuse", "mcp-specialist") +Task("Load balancing", "Add dynamic load balancing for MCP tools", "mcp-specialist") +Task("Transport optimization", "Optimize transport layer performance", "mcp-specialist") +``` + +## MCP Performance Architecture + +### Current State Analysis +``` +Current MCP Issues: +├── Cold Start Latency: ~1.8s MCP server init +├── Connection Overhead: New connection per request +├── Tool Registry: Linear search O(n) for 213+ tools +├── Transport Layer: No connection reuse +└── Memory Usage: No cleanup of idle connections + +Target Performance: +├── Startup Time: <400ms (4.5x improvement) +├── Tool Lookup: <5ms (O(1) hash table) +├── Connection Reuse: 90%+ connection pool hits +├── Response Time: <100ms p95 +└── Memory Efficiency: 50% reduction +``` + +### MCP Server Architecture +```typescript +// src/core/mcp/mcp-server.ts +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; + +interface OptimizedMCPConfig { + // Connection pooling + maxConnections: number; + idleTimeoutMs: number; + connectionReuseEnabled: boolean; + + // Tool registry + toolCacheEnabled: boolean; + toolIndexType: 'hash' | 'trie'; + + // Performance + requestTimeoutMs: number; + batchingEnabled: boolean; + compressionEnabled: boolean; + + // Monitoring + metricsEnabled: boolean; + healthCheckIntervalMs: number; +} + +export class OptimizedMCPServer { + private server: Server; + private connectionPool: ConnectionPool; + private toolRegistry: FastToolRegistry; + private loadBalancer: MCPLoadBalancer; + private metrics: MCPMetrics; + + constructor(config: OptimizedMCPConfig) { + this.server = new Server({ + name: 'Codex-flow-v3', + version: '3.0.0' + }, { + capabilities: { + tools: { listChanged: true }, + resources: { subscribe: true, listChanged: true }, + prompts: { listChanged: true } + } + }); + + this.connectionPool = new ConnectionPool(config); + this.toolRegistry = new FastToolRegistry(config.toolIndexType); + this.loadBalancer = new MCPLoadBalancer(); + this.metrics = new MCPMetrics(config.metricsEnabled); + } + + async start(): Promise { + // Pre-warm connection pool + await this.connectionPool.preWarm(); + + // Pre-build tool index + await this.toolRegistry.buildIndex(); + + // Setup request handlers with optimizations + this.setupOptimizedHandlers(); + + // Start health monitoring + this.startHealthMonitoring(); + + // Start server + const transport = new StdioServerTransport(); + await this.server.connect(transport); + + this.metrics.recordStartup(); + } +} +``` + +## Connection Pool Implementation + +### Advanced Connection Pooling +```typescript +// src/core/mcp/connection-pool.ts +interface PooledConnection { + id: string; + connection: MCPConnection; + lastUsed: number; + usageCount: number; + isHealthy: boolean; +} + +export class ConnectionPool { + private pool: Map = new Map(); + private readonly config: ConnectionPoolConfig; + private healthChecker: HealthChecker; + + constructor(config: ConnectionPoolConfig) { + this.config = { + maxConnections: 50, + minConnections: 5, + idleTimeoutMs: 300000, // 5 minutes + maxUsageCount: 1000, + healthCheckIntervalMs: 30000, + ...config + }; + + this.healthChecker = new HealthChecker(this.config.healthCheckIntervalMs); + } + + async getConnection(endpoint: string): Promise { + const start = performance.now(); + + // Try to get from pool first + const pooled = this.findAvailableConnection(endpoint); + if (pooled) { + pooled.lastUsed = Date.now(); + pooled.usageCount++; + + this.recordMetric('pool_hit', performance.now() - start); + return pooled.connection; + } + + // Check pool capacity + if (this.pool.size >= this.config.maxConnections) { + await this.evictLeastUsedConnection(); + } + + // Create new connection + const connection = await this.createConnection(endpoint); + const pooledConn: PooledConnection = { + id: this.generateConnectionId(), + connection, + lastUsed: Date.now(), + usageCount: 1, + isHealthy: true + }; + + this.pool.set(pooledConn.id, pooledConn); + this.recordMetric('pool_miss', performance.now() - start); + + return connection; + } + + async releaseConnection(connection: MCPConnection): Promise { + // Mark connection as available for reuse + const pooled = this.findConnectionById(connection.id); + if (pooled) { + // Check if connection should be retired + if (pooled.usageCount >= this.config.maxUsageCount) { + await this.removeConnection(pooled.id); + } + } + } + + async preWarm(): Promise { + const connections: Promise[] = []; + + for (let i = 0; i < this.config.minConnections; i++) { + connections.push(this.createConnection('default')); + } + + await Promise.all(connections); + } + + private async evictLeastUsedConnection(): Promise { + let oldestConn: PooledConnection | null = null; + let oldestTime = Date.now(); + + for (const conn of this.pool.values()) { + if (conn.lastUsed < oldestTime) { + oldestTime = conn.lastUsed; + oldestConn = conn; + } + } + + if (oldestConn) { + await this.removeConnection(oldestConn.id); + } + } + + private findAvailableConnection(endpoint: string): PooledConnection | null { + for (const conn of this.pool.values()) { + if (conn.isHealthy && + conn.connection.endpoint === endpoint && + Date.now() - conn.lastUsed < this.config.idleTimeoutMs) { + return conn; + } + } + return null; + } +} +``` + +## Fast Tool Registry + +### O(1) Tool Lookup Implementation +```typescript +// src/core/mcp/fast-tool-registry.ts +interface ToolIndexEntry { + name: string; + handler: ToolHandler; + metadata: ToolMetadata; + usageCount: number; + avgLatencyMs: number; +} + +export class FastToolRegistry { + private toolIndex: Map = new Map(); + private categoryIndex: Map = new Map(); + private fuzzyMatcher: FuzzyMatcher; + private cache: LRUCache; + + constructor(indexType: 'hash' | 'trie' = 'hash') { + this.fuzzyMatcher = new FuzzyMatcher(); + this.cache = new LRUCache(1000); // Cache 1000 most used tools + } + + async buildIndex(): Promise { + const start = performance.now(); + + // Load all available tools + const tools = await this.loadAllTools(); + + // Build hash index for O(1) lookup + for (const tool of tools) { + const entry: ToolIndexEntry = { + name: tool.name, + handler: tool.handler, + metadata: tool.metadata, + usageCount: 0, + avgLatencyMs: 0 + }; + + this.toolIndex.set(tool.name, entry); + + // Build category index + const category = tool.metadata.category || 'general'; + if (!this.categoryIndex.has(category)) { + this.categoryIndex.set(category, []); + } + this.categoryIndex.get(category)!.push(tool.name); + } + + // Build fuzzy search index + await this.fuzzyMatcher.buildIndex(tools.map(t => t.name)); + + console.log(`Tool index built in ${(performance.now() - start).toFixed(2)}ms for ${tools.length} tools`); + } + + findTool(name: string): ToolIndexEntry | null { + // Try cache first + const cached = this.cache.get(name); + if (cached) return cached; + + // Try exact match + const exact = this.toolIndex.get(name); + if (exact) { + this.cache.set(name, exact); + return exact; + } + + // Try fuzzy match + const fuzzyMatches = this.fuzzyMatcher.search(name, 1); + if (fuzzyMatches.length > 0) { + const match = this.toolIndex.get(fuzzyMatches[0]); + if (match) { + this.cache.set(name, match); + return match; + } + } + + return null; + } + + findToolsByCategory(category: string): ToolIndexEntry[] { + const toolNames = this.categoryIndex.get(category) || []; + return toolNames + .map(name => this.toolIndex.get(name)) + .filter(entry => entry !== undefined) as ToolIndexEntry[]; + } + + getMostUsedTools(limit: number = 10): ToolIndexEntry[] { + return Array.from(this.toolIndex.values()) + .sort((a, b) => b.usageCount - a.usageCount) + .slice(0, limit); + } + + recordToolUsage(toolName: string, latencyMs: number): void { + const entry = this.toolIndex.get(toolName); + if (entry) { + entry.usageCount++; + // Moving average for latency + entry.avgLatencyMs = (entry.avgLatencyMs + latencyMs) / 2; + } + } +} +``` + +## Load Balancing & Request Distribution + +### Intelligent Load Balancer +```typescript +// src/core/mcp/load-balancer.ts +interface ServerInstance { + id: string; + endpoint: string; + load: number; + responseTime: number; + isHealthy: boolean; + maxConnections: number; + currentConnections: number; +} + +export class MCPLoadBalancer { + private servers: Map = new Map(); + private routingStrategy: RoutingStrategy = 'least-connections'; + + addServer(server: ServerInstance): void { + this.servers.set(server.id, server); + } + + selectServer(toolCategory?: string): ServerInstance | null { + const healthyServers = Array.from(this.servers.values()) + .filter(server => server.isHealthy); + + if (healthyServers.length === 0) return null; + + switch (this.routingStrategy) { + case 'round-robin': + return this.roundRobinSelection(healthyServers); + + case 'least-connections': + return this.leastConnectionsSelection(healthyServers); + + case 'response-time': + return this.responseTimeSelection(healthyServers); + + case 'weighted': + return this.weightedSelection(healthyServers, toolCategory); + + default: + return healthyServers[0]; + } + } + + private leastConnectionsSelection(servers: ServerInstance[]): ServerInstance { + return servers.reduce((least, current) => + current.currentConnections < least.currentConnections ? current : least + ); + } + + private responseTimeSelection(servers: ServerInstance[]): ServerInstance { + return servers.reduce((fastest, current) => + current.responseTime < fastest.responseTime ? current : fastest + ); + } + + private weightedSelection(servers: ServerInstance[], category?: string): ServerInstance { + // Prefer servers with lower load and better response time + const scored = servers.map(server => ({ + server, + score: this.calculateServerScore(server, category) + })); + + scored.sort((a, b) => b.score - a.score); + return scored[0].server; + } + + private calculateServerScore(server: ServerInstance, category?: string): number { + const loadFactor = 1 - (server.currentConnections / server.maxConnections); + const responseFactor = 1 / (server.responseTime + 1); + const categoryBonus = this.getCategoryBonus(server, category); + + return loadFactor * 0.4 + responseFactor * 0.4 + categoryBonus * 0.2; + } + + updateServerMetrics(serverId: string, metrics: Partial): void { + const server = this.servers.get(serverId); + if (server) { + Object.assign(server, metrics); + } + } +} +``` + +## Transport Layer Optimization + +### High-Performance Transport +```typescript +// src/core/mcp/optimized-transport.ts +export class OptimizedTransport { + private compression: boolean = true; + private batching: boolean = true; + private batchBuffer: MCPMessage[] = []; + private batchTimeout: NodeJS.Timeout | null = null; + + constructor(private config: TransportConfig) {} + + async send(message: MCPMessage): Promise { + if (this.batching && this.canBatch(message)) { + this.addToBatch(message); + return; + } + + await this.sendImmediate(message); + } + + private async sendImmediate(message: MCPMessage): Promise { + const start = performance.now(); + + // Compress if enabled + const payload = this.compression + ? await this.compress(message) + : message; + + // Send through transport + await this.transport.send(payload); + + // Record metrics + this.recordLatency(performance.now() - start); + } + + private addToBatch(message: MCPMessage): void { + this.batchBuffer.push(message); + + // Start batch timeout if not already running + if (!this.batchTimeout) { + this.batchTimeout = setTimeout( + () => this.flushBatch(), + this.config.batchTimeoutMs || 10 + ); + } + + // Flush if batch is full + if (this.batchBuffer.length >= this.config.maxBatchSize) { + this.flushBatch(); + } + } + + private async flushBatch(): Promise { + if (this.batchBuffer.length === 0) return; + + const batch = this.batchBuffer.splice(0); + this.batchTimeout = null; + + // Send as single batched message + await this.sendImmediate({ + type: 'batch', + messages: batch + }); + } + + private canBatch(message: MCPMessage): boolean { + // Don't batch urgent messages or responses + return message.type !== 'response' && + message.priority !== 'high' && + message.type !== 'error'; + } + + private async compress(data: any): Promise { + // Use fast compression for smaller messages + return gzipSync(JSON.stringify(data)); + } +} +``` + +## Performance Monitoring + +### Real-time MCP Metrics +```typescript +// src/core/mcp/metrics.ts +interface MCPMetrics { + requestCount: number; + errorCount: number; + avgResponseTime: number; + p95ResponseTime: number; + connectionPoolHits: number; + connectionPoolMisses: number; + toolLookupTime: number; + startupTime: number; +} + +export class MCPMetricsCollector { + private metrics: MCPMetrics; + private responseTimeBuffer: number[] = []; + private readonly bufferSize = 1000; + + constructor() { + this.metrics = this.createInitialMetrics(); + } + + recordRequest(latencyMs: number): void { + this.metrics.requestCount++; + this.updateResponseTimes(latencyMs); + } + + recordError(): void { + this.metrics.errorCount++; + } + + recordConnectionPoolHit(): void { + this.metrics.connectionPoolHits++; + } + + recordConnectionPoolMiss(): void { + this.metrics.connectionPoolMisses++; + } + + recordToolLookup(latencyMs: number): void { + this.metrics.toolLookupTime = this.updateMovingAverage( + this.metrics.toolLookupTime, + latencyMs + ); + } + + recordStartup(latencyMs: number): void { + this.metrics.startupTime = latencyMs; + } + + getMetrics(): MCPMetrics { + return { ...this.metrics }; + } + + getHealthStatus(): HealthStatus { + const errorRate = this.metrics.errorCount / this.metrics.requestCount; + const poolHitRate = this.metrics.connectionPoolHits / + (this.metrics.connectionPoolHits + this.metrics.connectionPoolMisses); + + return { + status: this.determineHealthStatus(errorRate, poolHitRate), + errorRate, + poolHitRate, + avgResponseTime: this.metrics.avgResponseTime, + p95ResponseTime: this.metrics.p95ResponseTime + }; + } + + private updateResponseTimes(latency: number): void { + this.responseTimeBuffer.push(latency); + + if (this.responseTimeBuffer.length > this.bufferSize) { + this.responseTimeBuffer.shift(); + } + + this.metrics.avgResponseTime = this.calculateAverage(this.responseTimeBuffer); + this.metrics.p95ResponseTime = this.calculatePercentile(this.responseTimeBuffer, 95); + } + + private calculatePercentile(arr: number[], percentile: number): number { + const sorted = arr.slice().sort((a, b) => a - b); + const index = Math.ceil((percentile / 100) * sorted.length) - 1; + return sorted[index] || 0; + } + + private determineHealthStatus(errorRate: number, poolHitRate: number): 'healthy' | 'warning' | 'critical' { + if (errorRate > 0.1 || poolHitRate < 0.5) return 'critical'; + if (errorRate > 0.05 || poolHitRate < 0.7) return 'warning'; + return 'healthy'; + } +} +``` + +## Tool Registry Optimization + +### Pre-compiled Tool Index +```typescript +// src/core/mcp/tool-precompiler.ts +export class ToolPrecompiler { + async precompileTools(): Promise { + const tools = await this.loadAllTools(); + + // Create optimized lookup structures + const nameIndex = new Map(); + const categoryIndex = new Map(); + const fuzzyIndex = new Map(); + + for (const tool of tools) { + // Exact name index + nameIndex.set(tool.name, tool); + + // Category index + const category = tool.metadata.category || 'general'; + if (!categoryIndex.has(category)) { + categoryIndex.set(category, []); + } + categoryIndex.get(category)!.push(tool); + + // Pre-compute fuzzy variations + const variations = this.generateFuzzyVariations(tool.name); + for (const variation of variations) { + if (!fuzzyIndex.has(variation)) { + fuzzyIndex.set(variation, []); + } + fuzzyIndex.get(variation)!.push(tool.name); + } + } + + return { + nameIndex, + categoryIndex, + fuzzyIndex, + totalTools: tools.length, + compiledAt: new Date() + }; + } + + private generateFuzzyVariations(name: string): string[] { + const variations: string[] = []; + + // Common typos and abbreviations + variations.push(name.toLowerCase()); + variations.push(name.replace(/[-_]/g, '')); + variations.push(name.replace(/[aeiou]/gi, '')); // Consonants only + + // Add more fuzzy matching logic as needed + + return variations; + } +} +``` + +## Advanced Caching Strategy + +### Multi-Level Caching +```typescript +// src/core/mcp/multi-level-cache.ts +export class MultiLevelCache { + private l1Cache: Map = new Map(); // In-memory, fastest + private l2Cache: LRUCache; // LRU cache, larger capacity + private l3Cache: DiskCache; // Persistent disk cache + + constructor(config: CacheConfig) { + this.l2Cache = new LRUCache({ + max: config.l2MaxEntries || 10000, + ttl: config.l2TTL || 300000 // 5 minutes + }); + + this.l3Cache = new DiskCache(config.l3Path || './.cache/mcp'); + } + + async get(key: string): Promise { + // Try L1 cache first (fastest) + if (this.l1Cache.has(key)) { + return this.l1Cache.get(key); + } + + // Try L2 cache + const l2Value = this.l2Cache.get(key); + if (l2Value) { + // Promote to L1 + this.l1Cache.set(key, l2Value); + return l2Value; + } + + // Try L3 cache (disk) + const l3Value = await this.l3Cache.get(key); + if (l3Value) { + // Promote to L2 and L1 + this.l2Cache.set(key, l3Value); + this.l1Cache.set(key, l3Value); + return l3Value; + } + + return null; + } + + async set(key: string, value: any, options?: CacheOptions): Promise { + // Set in all levels + this.l1Cache.set(key, value); + this.l2Cache.set(key, value); + + if (options?.persistent) { + await this.l3Cache.set(key, value); + } + + // Manage L1 cache size + if (this.l1Cache.size > 1000) { + const firstKey = this.l1Cache.keys().next().value; + this.l1Cache.delete(firstKey); + } + } +} +``` + +## Success Metrics + +### Performance Targets +- [ ] **Startup Time**: <400ms MCP server initialization (4.5x improvement) +- [ ] **Response Time**: <100ms p95 for tool execution +- [ ] **Tool Lookup**: <5ms average lookup time +- [ ] **Connection Pool**: >90% hit rate +- [ ] **Memory Usage**: 50% reduction in idle memory +- [ ] **Error Rate**: <1% failed requests +- [ ] **Throughput**: >1000 requests/second + +### Monitoring Dashboards +```typescript +const mcpDashboard = { + metrics: [ + 'Request latency (p50, p95, p99)', + 'Error rate by tool category', + 'Connection pool utilization', + 'Tool lookup performance', + 'Memory usage trends', + 'Cache hit rates (L1, L2, L3)' + ], + + alerts: [ + 'Response time >200ms for 5 minutes', + 'Error rate >5% for 1 minute', + 'Pool hit rate <70% for 10 minutes', + 'Memory usage >500MB for 5 minutes' + ] +}; +``` + +## Related V3 Skills + +- `v3-core-implementation` - Core domain integration with MCP +- `v3-performance-optimization` - Overall performance optimization +- `v3-swarm-coordination` - MCP integration with swarm coordination +- `v3-memory-unification` - Memory sharing via MCP tools + +## Usage Examples + +### Complete MCP Optimization +```bash +# Full MCP server optimization +Task("MCP optimization implementation", + "Implement all MCP performance optimizations with monitoring", + "mcp-specialist") +``` + +### Specific Optimization +```bash +# Connection pool optimization +Task("MCP connection pooling", + "Implement advanced connection pooling with health monitoring", + "mcp-specialist") +``` \ No newline at end of file diff --git a/.agents/skills/v3-memory-unification/SKILL.md b/.agents/skills/v3-memory-unification/SKILL.md new file mode 100644 index 0000000..279dc63 --- /dev/null +++ b/.agents/skills/v3-memory-unification/SKILL.md @@ -0,0 +1,174 @@ +--- +name: "V3 Memory Unification" +description: "Unify 6+ memory systems into AgentDB with HNSW indexing for 150x-12,500x search improvements. Implements ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend)." +--- + +# V3 Memory Unification + +## What This Skill Does + +Consolidates disparate memory systems into unified AgentDB backend with HNSW vector search, achieving 150x-12,500x search performance improvements while maintaining backward compatibility. + +## Quick Start + +```bash +# Initialize memory unification +Task("Memory architecture", "Design AgentDB unification strategy", "v3-memory-specialist") + +# AgentDB integration +Task("AgentDB setup", "Configure HNSW indexing and vector search", "v3-memory-specialist") + +# Data migration +Task("Memory migration", "Migrate SQLite/Markdown to AgentDB", "v3-memory-specialist") +``` + +## Systems to Unify + +### Legacy Systems → AgentDB +``` +┌─────────────────────────────────────────┐ +│ • MemoryManager (basic operations) │ +│ • DistributedMemorySystem (clustering) │ +│ • SwarmMemory (agent-specific) │ +│ • AdvancedMemoryManager (features) │ +│ • SQLiteBackend (structured) │ +│ • MarkdownBackend (file-based) │ +│ • HybridBackend (combination) │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 🚀 AgentDB with HNSW │ +│ • 150x-12,500x faster search │ +│ • Unified query interface │ +│ • Cross-agent memory sharing │ +│ • SONA learning integration │ +└─────────────────────────────────────────┘ +``` + +## Implementation Architecture + +### Unified Memory Service +```typescript +class UnifiedMemoryService implements IMemoryBackend { + constructor( + private agentdb: AgentDBAdapter, + private indexer: HNSWIndexer, + private migrator: DataMigrator + ) {} + + async store(entry: MemoryEntry): Promise { + await this.agentdb.store(entry); + await this.indexer.index(entry); + } + + async query(query: MemoryQuery): Promise { + if (query.semantic) { + return this.indexer.search(query); // 150x-12,500x faster + } + return this.agentdb.query(query); + } +} +``` + +### HNSW Vector Search +```typescript +class HNSWIndexer { + constructor(dimensions: number = 1536) { + this.index = new HNSWIndex({ + dimensions, + efConstruction: 200, + M: 16, + speedupTarget: '150x-12500x' + }); + } + + async search(query: MemoryQuery): Promise { + const embedding = await this.embedContent(query.content); + const results = this.index.search(embedding, query.limit || 10); + return this.retrieveEntries(results); + } +} +``` + +## Migration Strategy + +### Phase 1: Foundation +```typescript +// AgentDB adapter setup +const agentdb = new AgentDBAdapter({ + dimensions: 1536, + indexType: 'HNSW', + speedupTarget: '150x-12500x' +}); +``` + +### Phase 2: Data Migration +```typescript +// SQLite → AgentDB +const migrateFromSQLite = async () => { + const entries = await sqlite.getAll(); + for (const entry of entries) { + const embedding = await generateEmbedding(entry.content); + await agentdb.store({ ...entry, embedding }); + } +}; + +// Markdown → AgentDB +const migrateFromMarkdown = async () => { + const files = await glob('**/*.md'); + for (const file of files) { + const content = await fs.readFile(file, 'utf-8'); + await agentdb.store({ + id: generateId(), + content, + embedding: await generateEmbedding(content), + metadata: { originalFile: file } + }); + } +}; +``` + +## SONA Integration + +### Learning Pattern Storage +```typescript +class SONAMemoryIntegration { + async storePattern(pattern: LearningPattern): Promise { + await this.memory.store({ + id: pattern.id, + content: pattern.data, + metadata: { + sonaMode: pattern.mode, + reward: pattern.reward, + adaptationTime: pattern.adaptationTime + }, + embedding: await this.generateEmbedding(pattern.data) + }); + } + + async retrieveSimilarPatterns(query: string): Promise { + return this.memory.query({ + type: 'semantic', + content: query, + filters: { type: 'learning_pattern' } + }); + } +} +``` + +## Performance Targets + +- **Search Speed**: 150x-12,500x improvement via HNSW +- **Memory Usage**: 50-75% reduction through optimization +- **Query Latency**: <100ms for 1M+ entries +- **Cross-Agent Sharing**: Real-time memory synchronization +- **SONA Integration**: <0.05ms adaptation time + +## Success Metrics + +- [ ] All 7 legacy memory systems migrated to AgentDB +- [ ] 150x-12,500x search performance validated +- [ ] 50-75% memory usage reduction achieved +- [ ] Backward compatibility maintained +- [ ] SONA learning patterns integrated +- [ ] Cross-agent memory sharing operational \ No newline at end of file diff --git a/.agents/skills/v3-performance-optimization/SKILL.md b/.agents/skills/v3-performance-optimization/SKILL.md new file mode 100644 index 0000000..9041bec --- /dev/null +++ b/.agents/skills/v3-performance-optimization/SKILL.md @@ -0,0 +1,390 @@ +--- +name: "V3 Performance Optimization" +description: "Achieve aggressive v3 performance targets: 2.49x-7.47x Flash Attention speedup, 150x-12,500x search improvements, 50-75% memory reduction. Comprehensive benchmarking and optimization suite." +--- + +# V3 Performance Optimization + +## What This Skill Does + +Validates and optimizes Codex-flow v3 to achieve industry-leading performance through Flash Attention, AgentDB HNSW indexing, and comprehensive system optimization with continuous benchmarking. + +## Quick Start + +```bash +# Initialize performance optimization +Task("Performance baseline", "Establish v2 performance benchmarks", "v3-performance-engineer") + +# Target validation (parallel) +Task("Flash Attention", "Validate 2.49x-7.47x speedup target", "v3-performance-engineer") +Task("Search optimization", "Validate 150x-12,500x search improvement", "v3-performance-engineer") +Task("Memory optimization", "Achieve 50-75% memory reduction", "v3-performance-engineer") +``` + +## Performance Target Matrix + +### Flash Attention Revolution +``` +┌─────────────────────────────────────────┐ +│ FLASH ATTENTION │ +├─────────────────────────────────────────┤ +│ Baseline: Standard attention │ +│ Target: 2.49x - 7.47x speedup │ +│ Memory: 50-75% reduction │ +│ Latency: Sub-millisecond processing │ +└─────────────────────────────────────────┘ +``` + +### Search Performance Revolution +``` +┌─────────────────────────────────────────┐ +│ SEARCH OPTIMIZATION │ +├─────────────────────────────────────────┤ +│ Current: O(n) linear search │ +│ Target: 150x - 12,500x improvement │ +│ Method: HNSW indexing │ +│ Latency: <100ms for 1M+ entries │ +└─────────────────────────────────────────┘ +``` + +## Comprehensive Benchmark Suite + +### Startup Performance +```typescript +class StartupBenchmarks { + async benchmarkColdStart(): Promise { + const startTime = performance.now(); + + await this.initializeCLI(); + await this.initializeMCPServer(); + await this.spawnTestAgent(); + + const totalTime = performance.now() - startTime; + + return { + total: totalTime, + target: 500, // ms + achieved: totalTime < 500 + }; + } +} +``` + +### Memory Operation Benchmarks +```typescript +class MemoryBenchmarks { + async benchmarkVectorSearch(): Promise { + const queries = this.generateTestQueries(10000); + + // Baseline: Current linear search + const baselineTime = await this.timeOperation(() => + this.currentMemory.searchAll(queries) + ); + + // Target: HNSW search + const hnswTime = await this.timeOperation(() => + this.agentDBMemory.hnswSearchAll(queries) + ); + + const improvement = baselineTime / hnswTime; + + return { + baseline: baselineTime, + hnsw: hnswTime, + improvement, + targetRange: [150, 12500], + achieved: improvement >= 150 + }; + } + + async benchmarkMemoryUsage(): Promise { + const baseline = process.memoryUsage().heapUsed; + + await this.loadTestDataset(); + const withData = process.memoryUsage().heapUsed; + + await this.enableOptimization(); + const optimized = process.memoryUsage().heapUsed; + + const reduction = (withData - optimized) / withData; + + return { + baseline, + withData, + optimized, + reductionPercent: reduction * 100, + targetReduction: [50, 75], + achieved: reduction >= 0.5 + }; + } +} +``` + +### Swarm Coordination Benchmarks +```typescript +class SwarmBenchmarks { + async benchmark15AgentCoordination(): Promise { + const agents = await this.spawn15Agents(); + + // Coordination latency + const coordinationTime = await this.timeOperation(() => + this.coordinateSwarmTask(agents) + ); + + // Task decomposition + const decompositionTime = await this.timeOperation(() => + this.decomposeComplexTask() + ); + + // Consensus achievement + const consensusTime = await this.timeOperation(() => + this.achieveSwarmConsensus(agents) + ); + + return { + coordination: coordinationTime, + decomposition: decompositionTime, + consensus: consensusTime, + agentCount: 15, + efficiency: this.calculateEfficiency(agents) + }; + } +} +``` + +### Flash Attention Benchmarks +```typescript +class AttentionBenchmarks { + async benchmarkFlashAttention(): Promise { + const sequences = this.generateSequences([512, 1024, 2048, 4096]); + const results = []; + + for (const sequence of sequences) { + // Baseline attention + const baselineResult = await this.benchmarkStandardAttention(sequence); + + // Flash attention + const flashResult = await this.benchmarkFlashAttention(sequence); + + results.push({ + sequenceLength: sequence.length, + speedup: baselineResult.time / flashResult.time, + memoryReduction: (baselineResult.memory - flashResult.memory) / baselineResult.memory, + targetSpeedup: [2.49, 7.47], + achieved: this.checkTarget(flashResult, [2.49, 7.47]) + }); + } + + return { + results, + averageSpeedup: this.calculateAverage(results, 'speedup'), + averageMemoryReduction: this.calculateAverage(results, 'memoryReduction') + }; + } +} +``` + +### SONA Learning Benchmarks +```typescript +class SONABenchmarks { + async benchmarkAdaptationTime(): Promise { + const scenarios = [ + 'pattern_recognition', + 'task_optimization', + 'error_correction', + 'performance_tuning' + ]; + + const results = []; + + for (const scenario of scenarios) { + const startTime = performance.hrtime.bigint(); + await this.sona.adapt(scenario); + const endTime = performance.hrtime.bigint(); + + const adaptationTimeMs = Number(endTime - startTime) / 1000000; + + results.push({ + scenario, + adaptationTime: adaptationTimeMs, + target: 0.05, // ms + achieved: adaptationTimeMs <= 0.05 + }); + } + + return { + scenarios: results, + averageTime: results.reduce((sum, r) => sum + r.adaptationTime, 0) / results.length, + successRate: results.filter(r => r.achieved).length / results.length + }; + } +} +``` + +## Performance Monitoring Dashboard + +### Real-time Metrics +```typescript +class PerformanceMonitor { + async collectMetrics(): Promise { + return { + timestamp: Date.now(), + flashAttention: await this.measureFlashAttention(), + searchPerformance: await this.measureSearchSpeed(), + memoryUsage: await this.measureMemoryEfficiency(), + startupTime: await this.measureStartupLatency(), + sonaAdaptation: await this.measureSONASpeed(), + swarmCoordination: await this.measureSwarmEfficiency() + }; + } + + async generateReport(): Promise { + const snapshot = await this.collectMetrics(); + + return { + summary: this.generateSummary(snapshot), + achievements: this.checkTargetAchievements(snapshot), + trends: this.analyzeTrends(), + recommendations: this.generateOptimizations(), + regressions: await this.detectRegressions() + }; + } +} +``` + +### Continuous Regression Detection +```typescript +class PerformanceRegression { + async detectRegressions(): Promise { + const current = await this.runFullBenchmark(); + const baseline = await this.getBaseline(); + + const regressions = []; + + for (const [metric, currentValue] of Object.entries(current)) { + const baselineValue = baseline[metric]; + const change = (currentValue - baselineValue) / baselineValue; + + if (change < -0.05) { // 5% regression threshold + regressions.push({ + metric, + baseline: baselineValue, + current: currentValue, + regressionPercent: change * 100, + severity: this.classifyRegression(change) + }); + } + } + + return { + hasRegressions: regressions.length > 0, + regressions, + recommendations: this.generateRegressionFixes(regressions) + }; + } +} +``` + +## Optimization Strategies + +### Memory Optimization +```typescript +class MemoryOptimization { + async optimizeMemoryUsage(): Promise { + // Implement memory pooling + await this.setupMemoryPools(); + + // Enable garbage collection tuning + await this.optimizeGarbageCollection(); + + // Implement object reuse patterns + await this.setupObjectPools(); + + // Enable memory compression + await this.enableMemoryCompression(); + + return this.validateMemoryReduction(); + } +} +``` + +### CPU Optimization +```typescript +class CPUOptimization { + async optimizeCPUUsage(): Promise { + // Implement worker thread pools + await this.setupWorkerThreads(); + + // Enable CPU-specific optimizations + await this.enableSIMDInstructions(); + + // Implement task batching + await this.optimizeTaskBatching(); + + return this.validateCPUImprovement(); + } +} +``` + +## Target Validation Framework + +### Performance Gates +```typescript +class PerformanceGates { + async validateAllTargets(): Promise { + const results = await Promise.all([ + this.validateFlashAttention(), // 2.49x-7.47x + this.validateSearchPerformance(), // 150x-12,500x + this.validateMemoryReduction(), // 50-75% + this.validateStartupTime(), // <500ms + this.validateSONAAdaptation() // <0.05ms + ]); + + return { + allTargetsAchieved: results.every(r => r.achieved), + results, + overallScore: this.calculateOverallScore(results), + recommendations: this.generateRecommendations(results) + }; + } +} +``` + +## Success Metrics + +### Primary Targets +- [ ] **Flash Attention**: 2.49x-7.47x speedup validated +- [ ] **Search Performance**: 150x-12,500x improvement confirmed +- [ ] **Memory Reduction**: 50-75% usage optimization achieved +- [ ] **Startup Time**: <500ms cold start consistently +- [ ] **SONA Adaptation**: <0.05ms learning response time +- [ ] **15-Agent Coordination**: Efficient parallel execution + +### Continuous Monitoring +- [ ] **Performance Dashboard**: Real-time metrics collection +- [ ] **Regression Testing**: Automated performance validation +- [ ] **Trend Analysis**: Performance evolution tracking +- [ ] **Alert System**: Immediate regression notification + +## Related V3 Skills + +- `v3-integration-deep` - Performance integration with agentic-flow +- `v3-memory-unification` - Memory performance optimization +- `v3-swarm-coordination` - Swarm performance coordination +- `v3-security-overhaul` - Secure performance patterns + +## Usage Examples + +### Complete Performance Validation +```bash +# Full performance suite +npm run benchmark:v3 + +# Specific target validation +npm run benchmark:flash-attention +npm run benchmark:agentdb-search +npm run benchmark:memory-optimization + +# Continuous monitoring +npm run monitor:performance +``` \ No newline at end of file diff --git a/.agents/skills/v3-security-overhaul/SKILL.md b/.agents/skills/v3-security-overhaul/SKILL.md new file mode 100644 index 0000000..3fd2cc5 --- /dev/null +++ b/.agents/skills/v3-security-overhaul/SKILL.md @@ -0,0 +1,82 @@ +--- +name: "V3 Security Overhaul" +description: "Complete security architecture overhaul for Codex-flow v3. Addresses critical CVEs (CVE-1, CVE-2, CVE-3) and implements secure-by-default patterns. Use for security-first v3 implementation." +--- + +# V3 Security Overhaul + +## What This Skill Does + +Orchestrates comprehensive security overhaul for Codex-flow v3, addressing critical vulnerabilities and establishing security-first development practices using specialized v3 security agents. + +## Quick Start + +```bash +# Initialize V3 security domain (parallel) +Task("Security architecture", "Design v3 threat model and security boundaries", "v3-security-architect") +Task("CVE remediation", "Fix CVE-1, CVE-2, CVE-3 critical vulnerabilities", "security-auditor") +Task("Security testing", "Implement TDD London School security framework", "test-architect") +``` + +## Critical Security Fixes + +### CVE-1: Vulnerable Dependencies +```bash +npm update @anthropic-ai/Codex@^2.0.31 +npm audit --audit-level high +``` + +### CVE-2: Weak Password Hashing +```typescript +// ❌ Old: SHA-256 with hardcoded salt +const hash = crypto.createHash('sha256').update(password + salt).digest('hex'); + +// ✅ New: bcrypt with 12 rounds +import bcrypt from 'bcrypt'; +const hash = await bcrypt.hash(password, 12); +``` + +### CVE-3: Hardcoded Credentials +```typescript +// ✅ Generate secure random credentials +const apiKey = crypto.randomBytes(32).toString('hex'); +``` + +## Security Patterns + +### Input Validation (Zod) +```typescript +import { z } from 'zod'; + +const TaskSchema = z.object({ + taskId: z.string().uuid(), + content: z.string().max(10000), + agentType: z.enum(['security', 'core', 'integration']) +}); +``` + +### Path Sanitization +```typescript +function securePath(userPath: string, allowedPrefix: string): string { + const resolved = path.resolve(allowedPrefix, userPath); + if (!resolved.startsWith(path.resolve(allowedPrefix))) { + throw new SecurityError('Path traversal detected'); + } + return resolved; +} +``` + +### Safe Command Execution +```typescript +import { execFile } from 'child_process'; + +// ✅ Safe: No shell interpretation +const { stdout } = await execFile('git', [userInput], { shell: false }); +``` + +## Success Metrics + +- **Security Score**: 90/100 (npm audit + custom scans) +- **CVE Resolution**: 100% of critical vulnerabilities fixed +- **Test Coverage**: >95% security-critical code +- **Implementation**: All secure patterns documented and tested \ No newline at end of file diff --git a/.agents/skills/v3-swarm-coordination/SKILL.md b/.agents/skills/v3-swarm-coordination/SKILL.md new file mode 100644 index 0000000..f3db009 --- /dev/null +++ b/.agents/skills/v3-swarm-coordination/SKILL.md @@ -0,0 +1,340 @@ +--- +name: "V3 Swarm Coordination" +description: "15-agent hierarchical mesh coordination for v3 implementation. Orchestrates parallel execution across security, core, and integration domains following 10 ADRs with 14-week timeline." +--- + +# V3 Swarm Coordination + +## What This Skill Does + +Orchestrates the complete 15-agent hierarchical mesh swarm for Codex-flow v3 implementation, coordinating parallel execution across domains while maintaining dependencies and timeline adherence. + +## Quick Start + +```bash +# Initialize 15-agent v3 swarm +Task("Swarm initialization", "Initialize hierarchical mesh for v3 implementation", "v3-queen-coordinator") + +# Security domain (Phase 1 - Critical priority) +Task("Security architecture", "Design v3 threat model and security boundaries", "v3-security-architect") +Task("CVE remediation", "Fix CVE-1, CVE-2, CVE-3 vulnerabilities", "security-auditor") +Task("Security testing", "Implement TDD security framework", "test-architect") + +# Core domain (Phase 2 - Parallel execution) +Task("Memory unification", "Implement AgentDB 150x improvement", "v3-memory-specialist") +Task("Integration architecture", "Deep agentic-flow@alpha integration", "v3-integration-architect") +Task("Performance validation", "Validate 2.49x-7.47x targets", "v3-performance-engineer") +``` + +## 15-Agent Swarm Architecture + +### Hierarchical Mesh Topology +``` + 👑 QUEEN COORDINATOR + (Agent #1) + │ + ┌────────────────────┼────────────────────┐ + │ │ │ + 🛡️ SECURITY 🧠 CORE 🔗 INTEGRATION + (Agents #2-4) (Agents #5-9) (Agents #10-12) + │ │ │ + └────────────────────┼────────────────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ + 🧪 QUALITY ⚡ PERFORMANCE 🚀 DEPLOYMENT + (Agent #13) (Agent #14) (Agent #15) +``` + +### Agent Roster +| ID | Agent | Domain | Phase | Responsibility | +|----|-------|--------|-------|----------------| +| 1 | Queen Coordinator | Orchestration | All | GitHub issues, dependencies, timeline | +| 2 | Security Architect | Security | Foundation | Threat modeling, CVE planning | +| 3 | Security Implementer | Security | Foundation | CVE fixes, secure patterns | +| 4 | Security Tester | Security | Foundation | TDD security testing | +| 5 | Core Architect | Core | Systems | DDD architecture, coordination | +| 6 | Core Implementer | Core | Systems | Core module implementation | +| 7 | Memory Specialist | Core | Systems | AgentDB unification | +| 8 | Swarm Specialist | Core | Systems | Unified coordination engine | +| 9 | MCP Specialist | Core | Systems | MCP server optimization | +| 10 | Integration Architect | Integration | Integration | agentic-flow@alpha deep integration | +| 11 | CLI/Hooks Developer | Integration | Integration | CLI modernization | +| 12 | Neural/Learning Dev | Integration | Integration | SONA integration | +| 13 | TDD Test Engineer | Quality | All | London School TDD | +| 14 | Performance Engineer | Performance | Optimization | Benchmarking validation | +| 15 | Release Engineer | Deployment | Release | CI/CD and v3.0.0 release | + +## Implementation Phases + +### Phase 1: Foundation (Week 1-2) +**Active Agents**: #1, #2-4, #5-6 +```typescript +const phase1 = async () => { + // Parallel security and architecture foundation + await Promise.all([ + // Security domain (critical priority) + Task("Security architecture", "Complete threat model and security boundaries", "v3-security-architect"), + Task("CVE-1 fix", "Update vulnerable dependencies", "security-implementer"), + Task("CVE-2 fix", "Replace weak password hashing", "security-implementer"), + Task("CVE-3 fix", "Remove hardcoded credentials", "security-implementer"), + Task("Security testing", "TDD London School security framework", "test-architect"), + + // Core architecture foundation + Task("DDD architecture", "Design domain boundaries and structure", "core-architect"), + Task("Type modernization", "Update type system for v3", "core-implementer") + ]); +}; +``` + +### Phase 2: Core Systems (Week 3-6) +**Active Agents**: #1, #5-9, #13 +```typescript +const phase2 = async () => { + // Parallel core system implementation + await Promise.all([ + Task("Memory unification", "Implement AgentDB with 150x-12,500x improvement", "v3-memory-specialist"), + Task("Swarm coordination", "Merge 4 coordination systems into unified engine", "swarm-specialist"), + Task("MCP optimization", "Optimize MCP server performance", "mcp-specialist"), + Task("Core implementation", "Implement DDD modular architecture", "core-implementer"), + Task("TDD core tests", "Comprehensive test coverage for core systems", "test-architect") + ]); +}; +``` + +### Phase 3: Integration (Week 7-10) +**Active Agents**: #1, #10-12, #13-14 +```typescript +const phase3 = async () => { + // Parallel integration and optimization + await Promise.all([ + Task("agentic-flow integration", "Eliminate 10,000+ duplicate lines", "v3-integration-architect"), + Task("CLI modernization", "Enhance CLI with hooks system", "cli-hooks-developer"), + Task("SONA integration", "Implement <0.05ms learning adaptation", "neural-learning-developer"), + Task("Performance benchmarking", "Validate 2.49x-7.47x targets", "v3-performance-engineer"), + Task("Integration testing", "End-to-end system validation", "test-architect") + ]); +}; +``` + +### Phase 4: Release (Week 11-14) +**Active Agents**: All 15 +```typescript +const phase4 = async () => { + // Full swarm final optimization + await Promise.all([ + Task("Performance optimization", "Final optimization pass", "v3-performance-engineer"), + Task("Release preparation", "CI/CD pipeline and v3.0.0 release", "release-engineer"), + Task("Final testing", "Complete test coverage validation", "test-architect"), + + // All agents: Final polish and optimization + ...agents.map(agent => + Task("Final polish", `Agent ${agent.id} final optimization`, agent.name) + ) + ]); +}; +``` + +## Coordination Patterns + +### Dependency Management +```typescript +class DependencyCoordination { + private dependencies = new Map([ + // Security first (no dependencies) + [2, []], [3, [2]], [4, [2, 3]], + + // Core depends on security foundation + [5, [2]], [6, [5]], [7, [5]], [8, [5, 7]], [9, [5]], + + // Integration depends on core systems + [10, [5, 7, 8]], [11, [5, 10]], [12, [7, 10]], + + // Quality and performance cross-cutting + [13, [2, 5]], [14, [5, 7, 8, 10]], [15, [13, 14]] + ]); + + async coordinateExecution(): Promise { + const completed = new Set(); + + while (completed.size < 15) { + const ready = this.getReadyAgents(completed); + + if (ready.length === 0) { + throw new Error('Deadlock detected in dependency chain'); + } + + // Execute ready agents in parallel + await Promise.all(ready.map(agentId => this.executeAgent(agentId))); + + ready.forEach(id => completed.add(id)); + } + } +} +``` + +### GitHub Integration +```typescript +class GitHubCoordination { + async initializeV3Milestone(): Promise { + await gh.createMilestone({ + title: 'Codex-Flow v3.0.0 Implementation', + description: '15-agent swarm implementation of 10 ADRs', + dueDate: this.calculate14WeekDeadline() + }); + } + + async createEpicIssues(): Promise { + const epics = [ + { title: 'Security Overhaul (CVE-1,2,3)', agents: [2, 3, 4] }, + { title: 'Memory Unification (AgentDB)', agents: [7] }, + { title: 'agentic-flow Integration', agents: [10] }, + { title: 'Performance Optimization', agents: [14] }, + { title: 'DDD Architecture', agents: [5, 6] } + ]; + + for (const epic of epics) { + await gh.createIssue({ + title: epic.title, + labels: ['epic', 'v3', ...epic.agents.map(id => `agent-${id}`)], + assignees: epic.agents.map(id => this.getAgentGithubUser(id)) + }); + } + } + + async trackProgress(): Promise { + // Hourly progress updates from each agent + setInterval(async () => { + for (const agent of this.agents) { + await this.postAgentProgress(agent); + } + }, 3600000); // 1 hour + } +} +``` + +### Communication Bus +```typescript +class SwarmCommunication { + private bus = new QuicSwarmBus({ + maxAgents: 15, + messageTimeout: 30000, + retryAttempts: 3 + }); + + async broadcastToSecurityDomain(message: SwarmMessage): Promise { + await this.bus.broadcast(message, { + targetAgents: [2, 3, 4], + priority: 'critical' + }); + } + + async coordinateCoreSystems(message: SwarmMessage): Promise { + await this.bus.broadcast(message, { + targetAgents: [5, 6, 7, 8, 9], + priority: 'high' + }); + } + + async notifyIntegrationTeam(message: SwarmMessage): Promise { + await this.bus.broadcast(message, { + targetAgents: [10, 11, 12], + priority: 'medium' + }); + } +} +``` + +## Performance Coordination + +### Parallel Efficiency Monitoring +```typescript +class EfficiencyMonitor { + async measureParallelEfficiency(): Promise { + const agentUtilization = await this.measureAgentUtilization(); + const coordinationOverhead = await this.measureCoordinationCost(); + + return { + totalEfficiency: agentUtilization.average, + target: 0.85, // >85% utilization + achieved: agentUtilization.average > 0.85, + bottlenecks: this.identifyBottlenecks(agentUtilization), + recommendations: this.generateOptimizations() + }; + } +} +``` + +### Load Balancing +```typescript +class SwarmLoadBalancer { + async balanceWorkload(): Promise { + const workloads = await this.analyzeAgentWorkloads(); + + for (const [agentId, load] of workloads.entries()) { + if (load > this.getCapacityThreshold(agentId)) { + await this.redistributeWork(agentId); + } + } + } + + async redistributeWork(overloadedAgent: number): Promise { + const availableAgents = this.getAvailableAgents(); + const tasks = await this.getAgentTasks(overloadedAgent); + + // Redistribute tasks to available agents + for (const task of tasks) { + const bestAgent = this.selectOptimalAgent(task, availableAgents); + await this.reassignTask(task, bestAgent); + } + } +} +``` + +## Success Metrics + +### Swarm Coordination +- [ ] **Parallel Efficiency**: >85% agent utilization time +- [ ] **Dependency Resolution**: Zero deadlocks or blocking issues +- [ ] **Communication Latency**: <100ms inter-agent messaging +- [ ] **Timeline Adherence**: 14-week delivery maintained +- [ ] **GitHub Integration**: <4h automated issue response + +### Implementation Targets +- [ ] **ADR Coverage**: All 10 ADRs implemented successfully +- [ ] **Performance**: 2.49x-7.47x Flash Attention achieved +- [ ] **Search**: 150x-12,500x AgentDB improvement validated +- [ ] **Code Reduction**: <5,000 lines (vs 15,000+) +- [ ] **Security**: 90/100 security score achieved + +## Related V3 Skills + +- `v3-security-overhaul` - Security domain coordination +- `v3-memory-unification` - Memory system coordination +- `v3-integration-deep` - Integration domain coordination +- `v3-performance-optimization` - Performance domain coordination + +## Usage Examples + +### Initialize Complete V3 Swarm +```bash +# Queen Coordinator initializes full swarm +Task("V3 swarm initialization", + "Initialize 15-agent hierarchical mesh for complete v3 implementation", + "v3-queen-coordinator") +``` + +### Phase-based Execution +```bash +# Phase 1: Security-first foundation +npm run v3:phase1:security + +# Phase 2: Core systems parallel +npm run v3:phase2:core-systems + +# Phase 3: Integration and optimization +npm run v3:phase3:integration + +# Phase 4: Release preparation +npm run v3:phase4:release +``` \ No newline at end of file diff --git a/.agents/skills/verification-quality/SKILL.md b/.agents/skills/verification-quality/SKILL.md new file mode 100644 index 0000000..bc9d5af --- /dev/null +++ b/.agents/skills/verification-quality/SKILL.md @@ -0,0 +1,649 @@ +--- +name: "Verification & Quality Assurance" +description: "Comprehensive truth scoring, code quality verification, and automatic rollback system with 0.95 accuracy threshold for ensuring high-quality agent outputs and codebase reliability." +version: "2.0.0" +category: "quality-assurance" +tags: ["verification", "truth-scoring", "quality", "rollback", "metrics", "ci-cd"] +--- + +# Verification & Quality Assurance Skill + +## What This Skill Does + +This skill provides a comprehensive verification and quality assurance system that ensures code quality and correctness through: + +- **Truth Scoring**: Real-time reliability metrics (0.0-1.0 scale) for code, agents, and tasks +- **Verification Checks**: Automated code correctness, security, and best practices validation +- **Automatic Rollback**: Instant reversion of changes that fail verification (default threshold: 0.95) +- **Quality Metrics**: Statistical analysis with trends, confidence intervals, and improvement tracking +- **CI/CD Integration**: Export capabilities for continuous integration pipelines +- **Real-time Monitoring**: Live dashboards and watch modes for ongoing verification + +## Prerequisites + +- Codex Flow installed (`npx Codex-flow@alpha`) +- Git repository (for rollback features) +- Node.js 18+ (for dashboard features) + +## Quick Start + +```bash +# View current truth scores +npx Codex-flow@alpha truth + +# Run verification check +npx Codex-flow@alpha verify check + +# Verify specific file with custom threshold +npx Codex-flow@alpha verify check --file src/app.js --threshold 0.98 + +# Rollback last failed verification +npx Codex-flow@alpha verify rollback --last-good +``` + +--- + +## Complete Guide + +### Truth Scoring System + +#### View Truth Metrics + +Display comprehensive quality and reliability metrics for your codebase and agent tasks. + +**Basic Usage:** +```bash +# View current truth scores (default: table format) +npx Codex-flow@alpha truth + +# View scores for specific time period +npx Codex-flow@alpha truth --period 7d + +# View scores for specific agent +npx Codex-flow@alpha truth --agent coder --period 24h + +# Find files/tasks below threshold +npx Codex-flow@alpha truth --threshold 0.8 +``` + +**Output Formats:** +```bash +# Table format (default) +npx Codex-flow@alpha truth --format table + +# JSON for programmatic access +npx Codex-flow@alpha truth --format json + +# CSV for spreadsheet analysis +npx Codex-flow@alpha truth --format csv + +# HTML report with visualizations +npx Codex-flow@alpha truth --format html --export report.html +``` + +**Real-time Monitoring:** +```bash +# Watch mode with live updates +npx Codex-flow@alpha truth --watch + +# Export metrics automatically +npx Codex-flow@alpha truth --export .Codex-flow/metrics/truth-$(date +%Y%m%d).json +``` + +#### Truth Score Dashboard + +Example dashboard output: +``` +📊 Truth Metrics Dashboard +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Overall Truth Score: 0.947 ✅ +Trend: ↗️ +2.3% (7d) + +Top Performers: + verification-agent 0.982 ⭐ + code-analyzer 0.971 ⭐ + test-generator 0.958 ✅ + +Needs Attention: + refactor-agent 0.821 ⚠️ + docs-generator 0.794 ⚠️ + +Recent Tasks: + task-456 0.991 ✅ "Implement auth" + task-455 0.967 ✅ "Add tests" + task-454 0.743 ❌ "Refactor API" +``` + +#### Metrics Explained + +**Truth Scores (0.0-1.0):** +- `1.0-0.95`: Excellent ⭐ (production-ready) +- `0.94-0.85`: Good ✅ (acceptable quality) +- `0.84-0.75`: Warning ⚠️ (needs attention) +- `<0.75`: Critical ❌ (requires immediate action) + +**Trend Indicators:** +- ↗️ Improving (positive trend) +- → Stable (consistent performance) +- ↘️ Declining (quality regression detected) + +**Statistics:** +- **Mean Score**: Average truth score across all measurements +- **Median Score**: Middle value (less affected by outliers) +- **Standard Deviation**: Consistency of scores (lower = more consistent) +- **Confidence Interval**: Statistical reliability of measurements + +### Verification Checks + +#### Run Verification + +Execute comprehensive verification checks on code, tasks, or agent outputs. + +**File Verification:** +```bash +# Verify single file +npx Codex-flow@alpha verify check --file src/app.js + +# Verify directory recursively +npx Codex-flow@alpha verify check --directory src/ + +# Verify with auto-fix enabled +npx Codex-flow@alpha verify check --file src/utils.js --auto-fix + +# Verify current working directory +npx Codex-flow@alpha verify check +``` + +**Task Verification:** +```bash +# Verify specific task output +npx Codex-flow@alpha verify check --task task-123 + +# Verify with custom threshold +npx Codex-flow@alpha verify check --task task-456 --threshold 0.99 + +# Verbose output for debugging +npx Codex-flow@alpha verify check --task task-789 --verbose +``` + +**Batch Verification:** +```bash +# Verify multiple files in parallel +npx Codex-flow@alpha verify batch --files "*.js" --parallel + +# Verify with pattern matching +npx Codex-flow@alpha verify batch --pattern "src/**/*.ts" + +# Integration test suite +npx Codex-flow@alpha verify integration --test-suite full +``` + +#### Verification Criteria + +The verification system evaluates: + +1. **Code Correctness** + - Syntax validation + - Type checking (TypeScript) + - Logic flow analysis + - Error handling completeness + +2. **Best Practices** + - Code style adherence + - SOLID principles + - Design patterns usage + - Modularity and reusability + +3. **Security** + - Vulnerability scanning + - Secret detection + - Input validation + - Authentication/authorization checks + +4. **Performance** + - Algorithmic complexity + - Memory usage patterns + - Database query optimization + - Bundle size impact + +5. **Documentation** + - JSDoc/TypeDoc completeness + - README accuracy + - API documentation + - Code comments quality + +#### JSON Output for CI/CD + +```bash +# Get structured JSON output +npx Codex-flow@alpha verify check --json > verification.json + +# Example JSON structure: +{ + "overallScore": 0.947, + "passed": true, + "threshold": 0.95, + "checks": [ + { + "name": "code-correctness", + "score": 0.98, + "passed": true + }, + { + "name": "security", + "score": 0.91, + "passed": false, + "issues": [...] + } + ] +} +``` + +### Automatic Rollback + +#### Rollback Failed Changes + +Automatically revert changes that fail verification checks. + +**Basic Rollback:** +```bash +# Rollback to last known good state +npx Codex-flow@alpha verify rollback --last-good + +# Rollback to specific commit +npx Codex-flow@alpha verify rollback --to-commit abc123 + +# Interactive rollback with preview +npx Codex-flow@alpha verify rollback --interactive +``` + +**Smart Rollback:** +```bash +# Rollback only failed files (preserve good changes) +npx Codex-flow@alpha verify rollback --selective + +# Rollback with automatic backup +npx Codex-flow@alpha verify rollback --backup-first + +# Dry-run mode (preview without executing) +npx Codex-flow@alpha verify rollback --dry-run +``` + +**Rollback Performance:** +- Git-based rollback: <1 second +- Selective file rollback: <500ms +- Backup creation: Automatic before rollback + +### Verification Reports + +#### Generate Reports + +Create detailed verification reports with metrics and visualizations. + +**Report Formats:** +```bash +# JSON report +npx Codex-flow@alpha verify report --format json + +# HTML report with charts +npx Codex-flow@alpha verify report --export metrics.html --format html + +# CSV for data analysis +npx Codex-flow@alpha verify report --format csv --export metrics.csv + +# Markdown summary +npx Codex-flow@alpha verify report --format markdown +``` + +**Time-based Reports:** +```bash +# Last 24 hours +npx Codex-flow@alpha verify report --period 24h + +# Last 7 days +npx Codex-flow@alpha verify report --period 7d + +# Last 30 days with trends +npx Codex-flow@alpha verify report --period 30d --include-trends + +# Custom date range +npx Codex-flow@alpha verify report --from 2025-01-01 --to 2025-01-31 +``` + +**Report Content:** +- Overall truth scores +- Per-agent performance metrics +- Task completion quality +- Verification pass/fail rates +- Rollback frequency +- Quality improvement trends +- Statistical confidence intervals + +### Interactive Dashboard + +#### Launch Dashboard + +Run interactive web-based verification dashboard with real-time updates. + +```bash +# Launch dashboard on default port (3000) +npx Codex-flow@alpha verify dashboard + +# Custom port +npx Codex-flow@alpha verify dashboard --port 8080 + +# Export dashboard data +npx Codex-flow@alpha verify dashboard --export + +# Dashboard with auto-refresh +npx Codex-flow@alpha verify dashboard --refresh 5s +``` + +**Dashboard Features:** +- Real-time truth score updates (WebSocket) +- Interactive charts and graphs +- Agent performance comparison +- Task history timeline +- Rollback history viewer +- Export to PDF/HTML +- Filter by time period/agent/score + +### Configuration + +#### Default Configuration + +Set verification preferences in `.Codex-flow/config.json`: + +```json +{ + "verification": { + "threshold": 0.95, + "autoRollback": true, + "gitIntegration": true, + "hooks": { + "preCommit": true, + "preTask": true, + "postEdit": true + }, + "checks": { + "codeCorrectness": true, + "security": true, + "performance": true, + "documentation": true, + "bestPractices": true + } + }, + "truth": { + "defaultFormat": "table", + "defaultPeriod": "24h", + "warningThreshold": 0.85, + "criticalThreshold": 0.75, + "autoExport": { + "enabled": true, + "path": ".Codex-flow/metrics/truth-daily.json" + } + } +} +``` + +#### Threshold Configuration + +**Adjust verification strictness:** +```bash +# Strict mode (99% accuracy required) +npx Codex-flow@alpha verify check --threshold 0.99 + +# Lenient mode (90% acceptable) +npx Codex-flow@alpha verify check --threshold 0.90 + +# Set default threshold +npx Codex-flow@alpha config set verification.threshold 0.98 +``` + +**Per-environment thresholds:** +```json +{ + "verification": { + "thresholds": { + "production": 0.99, + "staging": 0.95, + "development": 0.90 + } + } +} +``` + +### Integration Examples + +#### CI/CD Integration + +**GitHub Actions:** +```yaml +name: Quality Verification + +on: [push, pull_request] + +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install Dependencies + run: npm install + + - name: Run Verification + run: | + npx Codex-flow@alpha verify check --json > verification.json + + - name: Check Truth Score + run: | + score=$(jq '.overallScore' verification.json) + if (( $(echo "$score < 0.95" | bc -l) )); then + echo "Truth score too low: $score" + exit 1 + fi + + - name: Upload Report + uses: actions/upload-artifact@v3 + with: + name: verification-report + path: verification.json +``` + +**GitLab CI:** +```yaml +verify: + stage: test + script: + - npx Codex-flow@alpha verify check --threshold 0.95 --json > verification.json + - | + score=$(jq '.overallScore' verification.json) + if [ $(echo "$score < 0.95" | bc) -eq 1 ]; then + echo "Verification failed with score: $score" + exit 1 + fi + artifacts: + paths: + - verification.json + reports: + junit: verification.json +``` + +#### Swarm Integration + +Run verification automatically during swarm operations: + +```bash +# Swarm with verification enabled +npx Codex-flow@alpha swarm --verify --threshold 0.98 + +# Hive Mind with auto-rollback +npx Codex-flow@alpha hive-mind --verify --rollback-on-fail + +# Training pipeline with verification +npx Codex-flow@alpha train --verify --threshold 0.99 +``` + +#### Pair Programming Integration + +Enable real-time verification during collaborative development: + +```bash +# Pair with verification +npx Codex-flow@alpha pair --verify --real-time + +# Pair with custom threshold +npx Codex-flow@alpha pair --verify --threshold 0.97 --auto-fix +``` + +### Advanced Workflows + +#### Continuous Verification + +Monitor codebase continuously during development: + +```bash +# Watch directory for changes +npx Codex-flow@alpha verify watch --directory src/ + +# Watch with auto-fix +npx Codex-flow@alpha verify watch --directory src/ --auto-fix + +# Watch with notifications +npx Codex-flow@alpha verify watch --notify --threshold 0.95 +``` + +#### Monitoring Integration + +Send metrics to external monitoring systems: + +```bash +# Export to Prometheus +npx Codex-flow@alpha truth --format json | \ + curl -X POST https://pushgateway.example.com/metrics/job/Codex-flow \ + -d @- + +# Send to DataDog +npx Codex-flow@alpha verify report --format json | \ + curl -X POST "https://api.datadoghq.com/api/v1/series?api_key=${DD_API_KEY}" \ + -H "Content-Type: application/json" \ + -d @- + +# Custom webhook +npx Codex-flow@alpha truth --format json | \ + curl -X POST https://metrics.example.com/api/truth \ + -H "Content-Type: application/json" \ + -d @- +``` + +#### Pre-commit Hooks + +Automatically verify before commits: + +```bash +# Install pre-commit hook +npx Codex-flow@alpha verify install-hook --pre-commit + +# .git/hooks/pre-commit example: +#!/bin/bash +npx Codex-flow@alpha verify check --threshold 0.95 --json > /tmp/verify.json + +score=$(jq '.overallScore' /tmp/verify.json) +if (( $(echo "$score < 0.95" | bc -l) )); then + echo "❌ Verification failed with score: $score" + echo "Run 'npx Codex-flow@alpha verify check --verbose' for details" + exit 1 +fi + +echo "✅ Verification passed with score: $score" +``` + +### Performance Metrics + +**Verification Speed:** +- Single file check: <100ms +- Directory scan: <500ms (per 100 files) +- Full codebase analysis: <5s (typical project) +- Truth score calculation: <50ms + +**Rollback Speed:** +- Git-based rollback: <1s +- Selective file rollback: <500ms +- Backup creation: <2s + +**Dashboard Performance:** +- Initial load: <1s +- Real-time updates: <100ms latency (WebSocket) +- Chart rendering: 60 FPS + +### Troubleshooting + +#### Common Issues + +**Low Truth Scores:** +```bash +# Get detailed breakdown +npx Codex-flow@alpha truth --verbose --threshold 0.0 + +# Check specific criteria +npx Codex-flow@alpha verify check --verbose + +# View agent-specific issues +npx Codex-flow@alpha truth --agent --format json +``` + +**Rollback Failures:** +```bash +# Check git status +git status + +# View rollback history +npx Codex-flow@alpha verify rollback --history + +# Manual rollback +git reset --hard HEAD~1 +``` + +**Verification Timeouts:** +```bash +# Increase timeout +npx Codex-flow@alpha verify check --timeout 60s + +# Verify in batches +npx Codex-flow@alpha verify batch --batch-size 10 +``` + +### Exit Codes + +Verification commands return standard exit codes: + +- `0`: Verification passed (score ≥ threshold) +- `1`: Verification failed (score < threshold) +- `2`: Error during verification (invalid input, system error) + +### Related Commands + +- `npx Codex-flow@alpha pair` - Collaborative development with verification +- `npx Codex-flow@alpha train` - Training with verification feedback +- `npx Codex-flow@alpha swarm` - Multi-agent coordination with quality checks +- `npx Codex-flow@alpha report` - Generate comprehensive project reports + +### Best Practices + +1. **Set Appropriate Thresholds**: Use 0.99 for critical code, 0.95 for standard, 0.90 for experimental +2. **Enable Auto-rollback**: Prevent bad code from persisting +3. **Monitor Trends**: Track improvement over time, not just current scores +4. **Integrate with CI/CD**: Make verification part of your pipeline +5. **Use Watch Mode**: Get immediate feedback during development +6. **Export Metrics**: Track quality metrics in your monitoring system +7. **Review Rollbacks**: Understand why changes were rejected +8. **Train Agents**: Use verification feedback to improve agent performance + +### Additional Resources + +- Truth Scoring Algorithm: See `/docs/truth-scoring.md` +- Verification Criteria: See `/docs/verification-criteria.md` +- Integration Examples: See `/examples/verification/` +- API Reference: See `/docs/api/verification.md` diff --git a/internal/logic/common/newUserEligibility.go b/internal/logic/common/newUserEligibility.go new file mode 100644 index 0000000..bb371d4 --- /dev/null +++ b/internal/logic/common/newUserEligibility.go @@ -0,0 +1,188 @@ +package common + +import ( + "context" + "sort" + "time" + + modelOrder "github.com/perfect-panel/server/internal/model/order" + modelUser "github.com/perfect-panel/server/internal/model/user" + "github.com/perfect-panel/server/pkg/xerr" + "github.com/pkg/errors" + "gorm.io/gorm" +) + +const ( + NewUserEligibilitySourceDeviceCreatedAt = "device_created_at" + NewUserEligibilitySourceUserCreatedAtFallback = "user_created_at_fallback" + NewUserEligibilityJoinSourceBindEmail = "bind_email_with_verification" + NewUserEligibilityWindow = 24 * time.Hour +) + +type NewUserEligibilityContext struct { + ScopeUserIDs []int64 + EligibilityStartAt time.Time + Source string +} + +func (c *NewUserEligibilityContext) IsNewUserAt(now time.Time) bool { + if c == nil || c.EligibilityStartAt.IsZero() { + return false + } + return now.Sub(c.EligibilityStartAt) <= NewUserEligibilityWindow +} + +type newUserEligibilityRelation struct { + FamilyID int64 `gorm:"column:family_id"` + Role uint8 `gorm:"column:role"` + JoinSource string `gorm:"column:join_source"` + OwnerUserID int64 `gorm:"column:owner_user_id"` +} + +func ResolveNewUserEligibility(ctx context.Context, db *gorm.DB, currentUserID int64) (*NewUserEligibilityContext, error) { + if currentUserID <= 0 { + return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidParams), "current user id is empty") + } + + scopeUserIDs, err := resolveNewUserEligibilityScope(ctx, db, currentUserID) + if err != nil { + return nil, err + } + + startAt, source, err := resolveNewUserEligibilityStartAt(ctx, db, scopeUserIDs) + if err != nil { + return nil, err + } + + return &NewUserEligibilityContext{ + ScopeUserIDs: scopeUserIDs, + EligibilityStartAt: startAt, + Source: source, + }, nil +} + +func CountScopedSubscribePurchaseOrders( + ctx context.Context, + db *gorm.DB, + scopeUserIDs []int64, + subscribeID int64, + statuses []int64, + excludeOrderNo string, +) (int64, error) { + if len(scopeUserIDs) == 0 { + return 0, nil + } + + var count int64 + query := db.WithContext(ctx). + Model(&modelOrder.Order{}). + Where("user_id IN ? AND subscribe_id = ? AND type = 1", scopeUserIDs, subscribeID) + if len(statuses) > 0 { + query = query.Where("status IN ?", statuses) + } + if excludeOrderNo != "" { + query = query.Where("order_no != ?", excludeOrderNo) + } + if err := query.Count(&count).Error; err != nil { + return 0, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "count scoped subscribe purchase orders failed") + } + + return count, nil +} + +func resolveNewUserEligibilityScope(ctx context.Context, db *gorm.DB, currentUserID int64) ([]int64, error) { + defaultScope := []int64{currentUserID} + + var relation newUserEligibilityRelation + err := db.WithContext(ctx). + Table("user_family_member AS ufm"). + Select("ufm.family_id, ufm.role, ufm.join_source, uf.owner_user_id"). + Joins("JOIN user_family AS uf ON uf.id = ufm.family_id AND uf.deleted_at IS NULL AND uf.status = ?", modelUser.FamilyStatusActive). + Where("ufm.user_id = ? AND ufm.deleted_at IS NULL AND ufm.status = ?", currentUserID, modelUser.FamilyMemberActive). + Limit(1). + Take(&relation).Error + if err != nil { + if errors.Is(err, gorm.ErrRecordNotFound) { + return defaultScope, nil + } + return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query new user eligibility family relation failed") + } + + if relation.Role != modelUser.FamilyRoleOwner && relation.JoinSource != NewUserEligibilityJoinSourceBindEmail { + return defaultScope, nil + } + + var scopedUserIDs []int64 + if err = db.WithContext(ctx). + Table("user_family_member AS ufm"). + Select("ufm.user_id"). + Joins("JOIN user_family AS uf ON uf.id = ufm.family_id AND uf.deleted_at IS NULL AND uf.status = ?", modelUser.FamilyStatusActive). + Where( + "ufm.family_id = ? AND ufm.deleted_at IS NULL AND ufm.status = ? AND (ufm.role = ? OR ufm.join_source = ?)", + relation.FamilyID, + modelUser.FamilyMemberActive, + modelUser.FamilyRoleOwner, + NewUserEligibilityJoinSourceBindEmail, + ). + Pluck("ufm.user_id", &scopedUserIDs).Error; err != nil { + return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query new user eligibility scope failed") + } + + scopedUserIDs = append(scopedUserIDs, currentUserID) + return uniqueSortedInt64(scopedUserIDs), nil +} + +func resolveNewUserEligibilityStartAt(ctx context.Context, db *gorm.DB, scopeUserIDs []int64) (time.Time, string, error) { + var earliestDevice modelUser.Device + err := db.WithContext(ctx). + Model(&modelUser.Device{}). + Where("user_id IN ?", scopeUserIDs). + Order("created_at ASC"). + Limit(1). + Take(&earliestDevice).Error + switch { + case err == nil && !earliestDevice.CreatedAt.IsZero(): + return earliestDevice.CreatedAt, NewUserEligibilitySourceDeviceCreatedAt, nil + case err != nil && !errors.Is(err, gorm.ErrRecordNotFound): + return time.Time{}, "", errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query new user eligibility device start failed") + } + + var earliestUser modelUser.User + err = db.WithContext(ctx). + Model(&modelUser.User{}). + Where("id IN ?", scopeUserIDs). + Order("created_at ASC"). + Limit(1). + Take(&earliestUser).Error + if err != nil { + return time.Time{}, "", errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query new user eligibility fallback start failed") + } + if earliestUser.CreatedAt.IsZero() { + return time.Time{}, "", errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "new user eligibility start time not found") + } + + return earliestUser.CreatedAt, NewUserEligibilitySourceUserCreatedAtFallback, nil +} + +func uniqueSortedInt64(values []int64) []int64 { + if len(values) == 0 { + return nil + } + + seen := make(map[int64]struct{}, len(values)) + result := make([]int64, 0, len(values)) + for _, value := range values { + if value == 0 { + continue + } + if _, ok := seen[value]; ok { + continue + } + seen[value] = struct{}{} + result = append(result, value) + } + sort.Slice(result, func(i, j int) bool { + return result[i] < result[j] + }) + return result +} diff --git a/internal/logic/public/order/newUserDiscountEligibility.go b/internal/logic/public/order/newUserDiscountEligibility.go new file mode 100644 index 0000000..2d08da2 --- /dev/null +++ b/internal/logic/public/order/newUserDiscountEligibility.go @@ -0,0 +1,63 @@ +package order + +import ( + "context" + "encoding/json" + "time" + + commonLogic "github.com/perfect-panel/server/internal/logic/common" + "github.com/perfect-panel/server/internal/types" + "gorm.io/gorm" +) + +type newUserDiscountEligibility struct { + Eligibility *commonLogic.NewUserEligibilityContext + Discounts []types.SubscribeDiscount + NewUserOnly bool + WithinWindow bool + EligibleForDiscount bool +} + +func resolveNewUserDiscountEligibility( + ctx context.Context, + db *gorm.DB, + currentUserID int64, + subscribeID int64, + quantity int64, + discountJSON string, +) (*newUserDiscountEligibility, error) { + state := &newUserDiscountEligibility{} + if discountJSON == "" { + return state, nil + } + + _ = json.Unmarshal([]byte(discountJSON), &state.Discounts) + state.NewUserOnly = isNewUserOnlyForQuantity(state.Discounts, quantity) + + eligibility, err := commonLogic.ResolveNewUserEligibility(ctx, db, currentUserID) + if err != nil { + return nil, err + } + state.Eligibility = eligibility + state.WithinWindow = eligibility.IsNewUserAt(time.Now()) + state.EligibleForDiscount = state.WithinWindow + + if state.EligibleForDiscount && state.NewUserOnly { + historyCount, countErr := commonLogic.CountScopedSubscribePurchaseOrders( + ctx, + db, + eligibility.ScopeUserIDs, + subscribeID, + []int64{2, 5}, + "", + ) + if countErr != nil { + return nil, countErr + } + if historyCount >= 1 { + state.EligibleForDiscount = false + } + } + + return state, nil +} diff --git a/internal/logic/public/order/preCreateOrderLogic.go b/internal/logic/public/order/preCreateOrderLogic.go index f903e7c..fc07fb0 100644 --- a/internal/logic/public/order/preCreateOrderLogic.go +++ b/internal/logic/public/order/preCreateOrderLogic.go @@ -2,9 +2,7 @@ package order import ( "context" - "encoding/json" "math" - "time" commonLogic "github.com/perfect-panel/server/internal/logic/common" "github.com/perfect-panel/server/internal/model/order" @@ -105,47 +103,21 @@ func (l *PreCreateOrderLogic) PreCreateOrder(req *types.PurchaseOrderRequest) (r } } - // check new user only restriction (tier-level only) - // Only block users who registered more than 24h ago; users within 24h who already purchased - // are allowed to preview (they just won't receive the new-user discount). - var newUserOnly bool - if !isSingleModeRenewal && sub.Discount != "" { - var dis []types.SubscribeDiscount - _ = json.Unmarshal([]byte(sub.Discount), &dis) - newUserOnly = isNewUserOnlyForQuantity(dis, req.Quantity) + newUserDiscount, err := resolveNewUserDiscountEligibility(l.ctx, l.svcCtx.DB, u.Id, targetSubscribeID, req.Quantity, sub.Discount) + if err != nil { + l.Errorw("[PreCreateOrder] Database query error resolving new user eligibility", + logger.Field("error", err.Error()), + logger.Field("user_id", u.Id), + ) + return nil, err } - if newUserOnly { - if time.Since(u.CreatedAt) > 24*time.Hour { - return nil, errors.Wrapf(xerr.NewErrCode(xerr.SubscribeNewUserOnly), "not a new user") - } + if !isSingleModeRenewal && newUserDiscount.NewUserOnly && !newUserDiscount.WithinWindow { + return nil, errors.Wrapf(xerr.NewErrCode(xerr.SubscribeNewUserOnly), "not a new user") } var discount float64 = 1 - isNewUserForDiscount := time.Since(u.CreatedAt) <= 24*time.Hour - if isNewUserForDiscount && sub.Discount != "" { - // If the matched tier is new_user_only, check whether the user has already purchased this plan. - // If so, they are not eligible for the new-user discount (but the order is still allowed). - var dis []types.SubscribeDiscount - _ = json.Unmarshal([]byte(sub.Discount), &dis) - if isNewUserOnlyForQuantity(dis, req.Quantity) { - var historyCount int64 - if e := l.svcCtx.DB.Model(&order.Order{}). - Where("user_id = ? AND subscribe_id = ? AND type = 1 AND status IN ?", - u.Id, targetSubscribeID, []int64{2, 5}). - Count(&historyCount).Error; e != nil { - l.Errorw("[PreCreateOrder] Database query error checking new user discount eligibility", - logger.Field("error", e.Error()), logger.Field("user_id", u.Id)) - return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "check new user discount history error: %v", e.Error()) - } - if historyCount >= 1 { - isNewUserForDiscount = false - } - } - } - if sub.Discount != "" { - var dis []types.SubscribeDiscount - _ = json.Unmarshal([]byte(sub.Discount), &dis) - discount = getDiscount(dis, req.Quantity, isNewUserForDiscount) + if len(newUserDiscount.Discounts) > 0 { + discount = getDiscount(newUserDiscount.Discounts, req.Quantity, newUserDiscount.EligibleForDiscount) } price := sub.UnitPrice * req.Quantity diff --git a/internal/logic/public/order/purchaseLogic.go b/internal/logic/public/order/purchaseLogic.go index fa11ec8..6224e29 100644 --- a/internal/logic/public/order/purchaseLogic.go +++ b/internal/logic/public/order/purchaseLogic.go @@ -153,32 +153,18 @@ func (l *PurchaseLogic) Purchase(req *types.PurchaseOrderRequest) (resp *types.P return nil, errors.Wrapf(xerr.NewErrCode(xerr.SubscribeOutOfStock), "subscribe out of stock") } - var discount float64 = 1 - isNewUserForDiscount := time.Since(u.CreatedAt) <= 24*time.Hour - if isNewUserForDiscount && sub.Discount != "" { - // If the matched tier is new_user_only, check whether the user has already purchased this plan. - // If so, they are not eligible for the new-user discount (but the order is still allowed). - var dis []types.SubscribeDiscount - _ = json.Unmarshal([]byte(sub.Discount), &dis) - if isNewUserOnlyForQuantity(dis, req.Quantity) { - var historyCount int64 - if e := l.svcCtx.DB.Model(&order.Order{}). - Where("user_id = ? AND subscribe_id = ? AND type = 1 AND status IN ?", - u.Id, targetSubscribeID, []int{2, 5}). - Count(&historyCount).Error; e != nil { - l.Errorw("[Purchase] Database query error checking new user discount eligibility", - logger.Field("error", e.Error()), logger.Field("user_id", u.Id)) - return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "check new user discount history error: %v", e.Error()) - } - if historyCount >= 1 { - isNewUserForDiscount = false - } - } + newUserDiscount, err := resolveNewUserDiscountEligibility(l.ctx, l.svcCtx.DB, u.Id, targetSubscribeID, req.Quantity, sub.Discount) + if err != nil { + l.Errorw("[Purchase] Database query error resolving new user eligibility", + logger.Field("error", err.Error()), + logger.Field("user_id", u.Id), + ) + return nil, err } - if sub.Discount != "" { - var dis []types.SubscribeDiscount - _ = json.Unmarshal([]byte(sub.Discount), &dis) - discount = getDiscount(dis, req.Quantity, isNewUserForDiscount) + + var discount float64 = 1 + if len(newUserDiscount.Discounts) > 0 { + discount = getDiscount(newUserDiscount.Discounts, req.Quantity, newUserDiscount.EligibleForDiscount) } price := sub.UnitPrice * req.Quantity // discount amount @@ -272,23 +258,23 @@ func (l *PurchaseLogic) Purchase(req *types.PurchaseOrderRequest) (resp *types.P UserId: u.Id, SubscriptionUserId: entitlement.EffectiveUserID, ParentId: parentOrderID, - OrderNo: tool.GenerateTradeNo(), - Type: orderType, - Quantity: req.Quantity, - Price: price, - Amount: amount, - Discount: discountAmount, - GiftAmount: deductionAmount, - Coupon: req.Coupon, - CouponDiscount: coupon, - PaymentId: payment.Id, - Method: canonicalOrderMethod(payment.Platform), - FeeAmount: feeAmount, - Status: 1, - IsNew: isNew, - SubscribeId: targetSubscribeID, - SubscribeToken: subscribeToken, - AppAccountToken: uuid.New().String(), + OrderNo: tool.GenerateTradeNo(), + Type: orderType, + Quantity: req.Quantity, + Price: price, + Amount: amount, + Discount: discountAmount, + GiftAmount: deductionAmount, + Coupon: req.Coupon, + CouponDiscount: coupon, + PaymentId: payment.Id, + Method: canonicalOrderMethod(payment.Platform), + FeeAmount: feeAmount, + Status: 1, + IsNew: isNew, + SubscribeId: targetSubscribeID, + SubscribeToken: subscribeToken, + AppAccountToken: uuid.New().String(), } if isSingleModeRenewal { l.Infow("[Purchase] single mode purchase order created as renewal", @@ -320,20 +306,21 @@ func (l *PurchaseLogic) Purchase(req *types.PurchaseOrderRequest) (resp *types.P } } - // check new user only restriction inside transaction to prevent race condition (tier-level only) - // Only block users who registered more than 24h ago; users within 24h who already purchased - // are allowed to place another order (they just won't receive the new-user discount). - if orderInfo.Type == 1 { - var txNewUserOnly bool - if sub.Discount != "" { - var dis []types.SubscribeDiscount - _ = json.Unmarshal([]byte(sub.Discount), &dis) - txNewUserOnly = isNewUserOnlyForQuantity(dis, orderInfo.Quantity) + // Re-check new-user-only restriction inside the transaction to prevent race conditions. + if orderInfo.Type == 1 && newUserDiscount.NewUserOnly { + txNewUserDiscount, txErr := resolveNewUserDiscountEligibility( + l.ctx, + db, + u.Id, + targetSubscribeID, + orderInfo.Quantity, + sub.Discount, + ) + if txErr != nil { + return txErr } - if txNewUserOnly { - if time.Since(u.CreatedAt) > 24*time.Hour { - return errors.Wrapf(xerr.NewErrCode(xerr.SubscribeNewUserOnly), "not a new user") - } + if !txNewUserDiscount.WithinWindow { + return errors.Wrapf(xerr.NewErrCode(xerr.SubscribeNewUserOnly), "not a new user") } } diff --git a/queue/logic/order/activateOrderLogic.go b/queue/logic/order/activateOrderLogic.go index b1bfe78..45a41cc 100644 --- a/queue/logic/order/activateOrderLogic.go +++ b/queue/logic/order/activateOrderLogic.go @@ -17,12 +17,12 @@ import ( "github.com/google/uuid" "github.com/hibiken/asynq" "github.com/perfect-panel/server/internal/model/order" - internaltypes "github.com/perfect-panel/server/internal/types" "github.com/perfect-panel/server/internal/model/redemption" "github.com/perfect-panel/server/internal/model/subscribe" "github.com/perfect-panel/server/internal/model/user" "github.com/perfect-panel/server/internal/svc" "github.com/perfect-panel/server/internal/types" + internaltypes "github.com/perfect-panel/server/internal/types" "github.com/perfect-panel/server/pkg/tool" "github.com/perfect-panel/server/pkg/uuidx" queueTypes "github.com/perfect-panel/server/queue/types" @@ -223,27 +223,8 @@ func (l *ActivateOrderLogic) NewPurchase(ctx context.Context, orderInfo *order.O return err } - // check new user only restriction at activation to prevent concurrent bypass - if orderInfo.Type == OrderTypeSubscribe && sub.Discount != "" { - var dis []internaltypes.SubscribeDiscount - if jsonErr := json.Unmarshal([]byte(sub.Discount), &dis); jsonErr == nil { - newUserOnly := isNewUserOnlyForQuantity(dis, orderInfo.Quantity) - if newUserOnly { - if time.Since(userInfo.CreatedAt) > 24*time.Hour { - return fmt.Errorf("new user only: user %d is not a new user", userInfo.Id) - } - var historyCount int64 - if e := l.svc.DB.Model(&order.Order{}). - Where("user_id = ? AND subscribe_id = ? AND type = 1 AND status = ? AND order_no != ?", - orderInfo.UserId, orderInfo.SubscribeId, OrderStatusFinished, orderInfo.OrderNo). - Count(&historyCount).Error; e != nil { - return fmt.Errorf("new user only: check history error: %w", e) - } - if historyCount >= 1 { - return fmt.Errorf("new user only: user %d already activated subscribe %d", userInfo.Id, orderInfo.SubscribeId) - } - } - } + if err = validateNewUserOnlyEligibilityAtActivation(ctx, l.svc.DB, orderInfo, sub); err != nil { + return err } var userSub *user.Subscribe diff --git a/queue/logic/order/newUserEligibility.go b/queue/logic/order/newUserEligibility.go new file mode 100644 index 0000000..066ef3c --- /dev/null +++ b/queue/logic/order/newUserEligibility.go @@ -0,0 +1,58 @@ +package orderLogic + +import ( + "context" + "encoding/json" + "fmt" + "time" + + commonLogic "github.com/perfect-panel/server/internal/logic/common" + "github.com/perfect-panel/server/internal/model/order" + "github.com/perfect-panel/server/internal/model/subscribe" + internaltypes "github.com/perfect-panel/server/internal/types" + "gorm.io/gorm" +) + +func validateNewUserOnlyEligibilityAtActivation( + ctx context.Context, + db *gorm.DB, + orderInfo *order.Order, + sub *subscribe.Subscribe, +) error { + if orderInfo == nil || sub == nil || orderInfo.Type != OrderTypeSubscribe || sub.Discount == "" { + return nil + } + + var discounts []internaltypes.SubscribeDiscount + if err := json.Unmarshal([]byte(sub.Discount), &discounts); err != nil { + return nil + } + if !isNewUserOnlyForQuantity(discounts, orderInfo.Quantity) { + return nil + } + + eligibility, err := commonLogic.ResolveNewUserEligibility(ctx, db, orderInfo.UserId) + if err != nil { + return err + } + if !eligibility.IsNewUserAt(time.Now()) { + return fmt.Errorf("new user only: user %d is not a new user", orderInfo.UserId) + } + + historyCount, err := commonLogic.CountScopedSubscribePurchaseOrders( + ctx, + db, + eligibility.ScopeUserIDs, + orderInfo.SubscribeId, + []int64{OrderStatusFinished}, + orderInfo.OrderNo, + ) + if err != nil { + return fmt.Errorf("new user only: check history error: %w", err) + } + if historyCount >= 1 { + return fmt.Errorf("new user only: user %d already activated subscribe %d", orderInfo.UserId, orderInfo.SubscribeId) + } + + return nil +}