claude-flow-novice 2.14.18 → 2.14.19

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

@@ -0,0 +1,394 @@
+# 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
+```bash
+# Create isolated network for MCP communication
+docker network create mcp-network --driver bridge
+
+# Connect containers to MCP network
+docker network connect mcp-network agent-frontend-001
+docker network connect mcp-network playwright-mcp
+```
+
+## 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