claude-flow-novice 2.18.6 → 2.18.8

package/claude-assets/skills/cfn-docker-runtime/lib/spawning/SKILL.md

@@ -1,418 +0,0 @@
-# CFN Docker Agent Spawning Skill
-
-**Purpose:** Spawn agents in isolated Docker containers with skill-based MCP selection, resource management, and authentication.
-
-## Overview
-
-This skill manages the lifecycle of container-based agents, providing isolated execution environments with controlled resource usage, secure MCP access, and comprehensive monitoring capabilities.
-
-## Architecture
-
-```bash
-Agent Spawning Request
-    ↓
-Container Configuration (memory, CPU, volumes)
-    ↓
-Docker Container Creation
-    ↓
-MCP Token Generation & Injection
-    ↓
-Agent Initialization (claude-flow-novice agent-spawn)
-    ↓
-Resource Monitoring & Management
-```
-
-## Core Functions
-
-### 1. Container Configuration
-Generate Docker container specifications based on agent type and requirements:
-
-```bash
-# Configure container for frontend engineer
-cfn-docker-agent-spawn configure \
-  --agent-type react-frontend-engineer \
-  --memory-limit 1g \
-  --cpu-limit 1.0 \
-  --network mcp-network
-```
-
-### 2. Container Creation
-Create and start Docker containers with proper isolation:
-
-```bash
-# Spawn agent container
-cfn-docker-agent-spawn create \
-  --agent-id agent-frontend-001 \
-  --agent-type react-frontend-engineer \
-  --task-id task-authentication \
-  --context "${TASK_CONTEXT}"
-```
-
-### 3. MCP Integration
-Configure secure MCP server access with authentication tokens:
-
-```bash
-# Setup MCP access for container
-cfn-docker-agent-spawn setup-mcp \
-  --container-id agent-frontend-001 \
-  --mcp-servers playwright \
-  --token-file /tmp/mcp-tokens.json
-```
-
-### 4. Resource Management
-Monitor and manage container resources:
-
-```bash
-# Monitor container resources
-cfn-docker-agent-spawn monitor \
-  --container-id agent-frontend-001 \
-  --alert-threshold 90%
-```
-
-## Container Specification
-
-### Standard Configuration
-```yaml
-# Docker container specification
-agent-container:
-  image: claude-flow-novice:agent
-  hostname: agent-{{AGENT_ID}}
-  networks:
-    - mcp-network
-  volumes:
-    - ./.claude:/app/.claude:ro
-    - ./src:/app/src:ro
-    - agent-workspace-{{AGENT_ID}}:/app/workspace
-  environment:
-    - AGENT_ID={{AGENT_ID}}
-    - AGENT_TYPE={{AGENT_TYPE}}
-    - TASK_ID={{TASK_ID}}
-    - REDIS_URL=redis://redis:6379
-    - MCP_TOKENS_FILE=/tmp/mcp-tokens.json
-  resources:
-    memory: {{MEMORY_LIMIT}}
-    cpu: {{CPU_LIMIT}}
-  restart_policy: unless-stopped
-```
-
-### Volume Mounts
-- **Codebase**: Read-only mount for source code and skills
-- **Agent Configuration**: Read-only mount for .claude directory
-- **Workspace**: Writable mount for agent work output
-- **Token Store**: Temporary file for MCP authentication tokens
-
-### Environment Variables
-- `AGENT_ID`: Unique container identifier
-- `AGENT_TYPE`: Agent type for skill-based selection
-- `TASK_ID`: CFN Loop task identifier
-- `REDIS_URL`: Redis connection string
-- `MCP_TOKENS_FILE`: Path to MCP authentication tokens
-
-## Usage Patterns
-
-### Basic Agent Spawning
-```bash
-# Spawn single agent
-cfn-docker-agent-spawn \
-  --agent-type react-frontend-engineer \
-  --task-id "implement-ui" \
-  --memory-limit 1g
-```
-
-### Batch Agent Spawning
-```bash
-# Spawn team of agents
-cfn-docker-agent-spawn batch \
-  --team frontend \
-  --agents 3 \
-  --task-id "ui-development" \
-  --memory-limit 1g \
-  --network mcp-network
-```
-
-### Custom Configuration
-```bash
-# Spawn with custom configuration
-cfn-docker-agent-spawn \
-  --agent-type security-specialist \
-  --custom-config config/security-agent.json \
-  --environment "DEBUG=true,LOG_LEVEL=verbose" \
-  --volume /data/secrets:/app/secrets:ro
-```
-
-## Resource Management
-
-### Memory Limits
-| Agent Type | Default Limit | Maximum Recommended |
-|------------|---------------|---------------------|
-| **Frontend Engineer** | 1GB | 2GB |
-| **Backend Developer** | 768MB | 1.5GB |
-| **Security Specialist** | 1.5GB | 3GB |
-| **DevOps Engineer** | 1GB | 2GB |
-
-### CPU Limits
-- **Standard Agents**: 0.5-1.0 CPU units
-- **Resource-Intensive Agents**: 1.0-2.0 CPU units
-- **Batch Operations**: 0.3-0.5 CPU units per agent
-
-### Network Configuration
-
-**Multi-Worktree Network Isolation:**
-
-For multi-worktree environments, use project-scoped network names:
-
-```bash
-# Set project name from environment (set by run-in-worktree.sh)
-PROJECT_NAME="${COMPOSE_PROJECT_NAME:-cfn-default}"
-
-# Create isolated network for MCP communication (worktree-scoped)
-docker network create "${PROJECT_NAME}_mcp-network" --driver bridge
-
-# Connect containers to MCP network
-docker network connect "${PROJECT_NAME}_mcp-network" agent-frontend-001
-docker network connect "${PROJECT_NAME}_mcp-network" playwright-mcp
-```
-
-**Service Discovery Within Networks:**
-
-Agents within the Docker network can access services by name:
-```bash
-# Use service names (not container names) for connections
-redis-cli -h redis              # Resolves to Redis service
-psql -h postgres                # Resolves to PostgreSQL service
-curl http://orchestrator:3001   # Resolves to orchestrator service
-```
-
-**Why Project-Scoped Networks?**
-- Prevents network name conflicts between worktrees
-- Isolates agent communication per branch
-- Enables simultaneous multi-worktree development
-- Automatically managed by docker-compose with COMPOSE_PROJECT_NAME
-
-## Integration with CFN Docker Skills
-
-### Skill-Based MCP Selection
-```bash
-# Get MCP configuration for agent
-MCP_CONFIG=$(cfn-docker-skill-mcp-selector select --agent-type ${AGENT_TYPE})
-
-# Spawn with MCP configuration
-cfn-docker-agent-spawn \
-  --agent-type ${AGENT_TYPE} \
-  --mcp-config "${MCP_CONFIG}" \
-  --auto-tokens
-```
-
-### Redis Coordination
-```bash
-# Register agent in Redis
-cfn-docker-redis-coordination register \
-  --agent-id ${AGENT_ID} \
-  --container-id ${CONTAINER_ID} \
-  --status "spawning"
-
-# Update agent status
-cfn-docker-redis-coordination update-status \
-  --agent-id ${AGENT_ID} \
-  --status "running"
-```
-
-### Loop Orchestration
-```bash
-# Spawn agents for Loop 3 implementation
-cfn-docker-loop-orchestration spawn-loop3 \
-  --task-context "${TASK_CONTEXT}" \
-  --agent-count 3 \
-  --parallel
-```
-
-## Monitoring and Observability
-
-### Resource Monitoring
-```bash
-# Real-time resource usage
-cfn-docker-agent-spawn stats \
-  --agent-id agent-frontend-001 \
-  --format json
-
-# Historical resource data
-cfn-docker-agent-spawn history \
-  --agent-id agent-frontend-001 \
-  --duration 1h
-```
-
-### Health Checks
-```bash
-# Container health status
-cfn-docker-agent-spawn health \
-  --agent-id agent-frontend-001
-
-# MCP server connectivity
-cfn-docker-agent-spawn check-mcp \
-  --agent-id agent-frontend-001 \
-  --servers playwright,redis
-```
-
-### Logging
-```bash
-# Container logs
-cfn-docker-agent-spawn logs \
-  --agent-id agent-frontend-001 \
-  --tail 100
-
-# Structured logs for monitoring
-cfn-docker-agent-spawn logs \
-  --agent-id agent-frontend-001 \
-  --format json \
-  --output /var/log/agents/${AGENT_ID}.log
-```
-
-## Error Handling
-
-### Container Failure Recovery
-```bash
-# Automatic restart on failure
-cfn-docker-agent-spawn \
-  --agent-type ${AGENT_TYPE} \
-  --restart-policy on-failure \
-  --restart-count 3
-
-# Manual recovery
-cfn-docker-agent-spawn recover \
-  --agent-id agent-frontend-001 \
-  --backup-state
-```
-
-### Resource Exhaustion Handling
-```bash
-# Memory pressure handling
-cfn-docker-agent-spawn \
-  --memory-limit 1g \
-  --memory-swap 1.5g \
-  --oom-kill-disable
-
-# CPU throttling
-cfn-docker-agent-spawn \
-  --cpu-limit 1.0 \
-  --cpu-shares 1024
-```
-
-### Network Isolation Issues
-```bash
-# Network connectivity validation
-cfn-docker-agent-spawn validate-network \
-  --agent-id agent-frontend-001 \
-  --targets redis:6379,playwright-mcp:3000
-
-# Network repair
-cfn-docker-agent-spawn repair-network \
-  --agent-id agent-frontend-001 \
-  --recreate-network
-```
-
-## Performance Optimization
-
-### Startup Optimization
-- **Pre-warmed Images**: Use Docker image layer caching
-- **Parallel Startup**: Spawn multiple containers concurrently
-- **Lazy Loading**: Load MCP servers on-demand
-- **Resource Pre-allocation**: Reserve resources in advance
-
-### Memory Optimization
-- **Selective MCP Loading**: Only load required MCP servers
-- **Workspace Cleanup**: Clean temporary files automatically
-- **Garbage Collection**: Optimize Node.js memory management
-- **Shared Libraries**: Use shared mounts for common dependencies
-
-### Network Optimization
-- **Local Network**: Use Docker bridge networks for MCP communication
-- **Connection Pooling**: Reuse MCP server connections
-- **DNS Caching**: Cache MCP server DNS resolution
-- **Compression**: Compress large data transfers
-
-## Security Considerations
-
-### Container Isolation
-- **Read-only Codebase**: Prevent code modification
-- **Limited Privileges**: Run as non-root user
-- **Resource Limits**: Prevent DoS attacks
-- **Network Segmentation**: Isolate agent networks
-
-### Token Security
-- **Secure Token Storage**: Use tmpfs for token files
-- **Token Expiration**: Automatic token rotation
-- **Access Logging**: Log all token usage
-- **Revocation**: Immediate token invalidation
-
-### File System Security
-- **Restricted Access**: Limit file system access
-- **Workspace Isolation**: Isolate agent workspaces
-- **Temporary Files**: Secure cleanup of temporary files
-- **Audit Logging**: Log all file system operations
-
-## Testing and Validation
-
-### Unit Tests
-- Container creation and configuration
-- Resource limit enforcement
-- Network connectivity validation
-- Token injection and validation
-
-### Integration Tests
-- End-to-end agent spawning workflow
-- MCP server connectivity and authentication
-- Resource monitoring and alerting
-- Error handling and recovery
-
-### Performance Tests
-- Container startup time measurement
-- Resource usage benchmarking
-- Concurrent spawning scalability
-- Network performance validation
-
-## Troubleshooting
-
-### Common Issues
-1. **Container Won't Start**: Check image availability and resource limits
-2. **MCP Connection Failed**: Verify network configuration and token validity
-3. **Memory Issues**: Monitor usage and adjust limits
-4. **Permission Errors**: Check volume mounts and user permissions
-
-### Debug Commands
-```bash
-# Debug container creation
-cfn-docker-agent-spawn debug \
-  --agent-type ${AGENT_TYPE} \
-  --verbose \
-  --dry-run
-
-# Inspect container configuration
-cfn-docker-agent-spawn inspect \
-  --container-id ${CONTAINER_ID} \
-  --format json
-
-# Validate MCP connectivity
-cfn-docker-agent-spawn test-mcp \
-  --container-id ${CONTAINER_ID} \
-  --all-servers
-```
-
-## Best Practices
-
-### Resource Planning
-- **Conservative Limits**: Start with lower memory limits and increase as needed
-- **Monitoring**: Implement comprehensive resource monitoring
-- **Capacity Planning**: Plan for peak usage scenarios
-- **Resource Cleanup**: Clean up unused containers and volumes
-
-### Security Hardening
-- **Minimal Images**: Use minimal Docker images
-- **Regular Updates**: Keep base images updated
-- **Scanning**: Regularly scan images for vulnerabilities
-- **Access Control**: Implement proper access controls
-
-### Operational Excellence
-- **Automation**: Automate container lifecycle management
-- **Observability**: Implement comprehensive monitoring
-- **Documentation**: Maintain detailed configuration documentation
-- **Backup**: Backup critical container configurations