claude-flow-novice 2.14.37 → 2.15.1

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/SKILL.md

@@ -0,0 +1,679 @@
+# Web Portal Skill - Monitoring & Visualization Interface
+
+**Version:** 1.0.0
+**Status:** Production Ready
+**Skill Type:** Infrastructure / Monitoring
+**Dependencies:** Redis, packages/web-portal
+
+---
+
+## Overview
+
+The Web Portal Skill provides programmatic access to the claude-flow-novice web portal monitoring and visualization system. This skill enables agents to query real-time metrics, agent status, event streams, and system health without direct web browser access.
+
+### Core Capabilities
+
+- **Lifecycle Management:** Start/stop web portal server with health validation
+- **Metrics Querying:** Retrieve system and agent-level performance metrics
+- **Dashboard Access:** Get comprehensive system status summaries
+- **Agent Monitoring:** Query agent hierarchy, status, and coordination state
+- **Event Streaming:** Access event timeline with filtering and pagination
+- **Graceful Shutdown:** Clean server termination with WebSocket cleanup
+
+---
+
+## Skill Architecture
+
+### Technology Stack
+
+- **Server:** Express.js + Socket.IO (WebSocket coordination)
+- **Client:** Vite + React (development mode)
+- **API:** RESTful endpoints with caching
+- **Coordination:** Redis pub/sub integration
+- **Caching:** 60-second TTL for metrics, 30-second for agents
+
+### API Endpoints
+
+| Endpoint | Method | Purpose | Cache TTL |
+|----------|--------|---------|-----------|
+| `/health` | GET | Health check | None |
+| `/api/metrics` | GET | System metrics | 10s (server) |
+| `/api/agents/hierarchy` | GET | Agent tree | 30s (server) |
+| `/api/agents/:id/status` | GET | Agent details | None |
+| `/api/events` | GET | Event timeline | None |
+| `/api/events/phase/:id` | GET | Phase events | None |
+| `/api/events/agent/:id` | GET | Agent events | None |
+
+---
+
+## Invoke Scripts Reference
+
+### 1. invoke-portal-start.sh
+
+**Purpose:** Start web portal server with health validation
+
+**Usage:**
+```bash
+./.claude/skills/web-portal/invoke-portal-start.sh [--port PORT] [--production]
+```
+
+**Arguments:**
+- `--port PORT` - Server port (default: 3000)
+- `--production` - Build and run in production mode
+
+**Returns:**
+```json
+{
+  "success": true,
+  "serverUrl": "http://localhost:3000",
+  "port": 3000,
+  "pid": 12345,
+  "mode": "development",
+  "health": {
+    "status": "healthy",
+    "redis": true,
+    "uptime": 0,
+    "checks": 5
+  },
+  "endpoints": {
+    "api": "http://localhost:3000/api",
+    "metrics": "http://localhost:3000/api/metrics",
+    "agents": "http://localhost:3000/api/agents",
+    "events": "http://localhost:3000/api/events",
+    "health": "http://localhost:3000/health"
+  }
+}
+```
+
+**Example:**
+```bash
+# Start development server
+./invoke-portal-start.sh
+
+# Start on custom port
+./invoke-portal-start.sh --port 3001
+
+# Production mode
+./invoke-portal-start.sh --production
+```
+
+**Health Check:**
+- Max attempts: 30
+- Interval: 1 second
+- Validates Redis connection
+- Verifies HTTP responses
+
+---
+
+### 2. invoke-portal-metrics.sh
+
+**Purpose:** Query system and agent metrics with caching
+
+**Usage:**
+```bash
+./.claude/skills/web-portal/invoke-portal-metrics.sh [OPTIONS]
+```
+
+**Arguments:**
+- `--agent AGENT_ID` - Filter by agent
+- `--timeframe TIMEFRAME` - Time window (e.g., "5m", "1h")
+- `--view VIEW` - Metric view type
+- `--format json|table` - Output format (default: json)
+- `--port PORT` - Server port (default: 3000)
+
+**Cache Behavior:**
+- TTL: 60 seconds
+- Cache directory: `.artifacts/cache/web-portal/`
+- Cache key includes all filter parameters
+- Automatic cache invalidation after TTL
+
+**Returns:**
+```json
+{
+  "data": {
+    "totalAgents": 15,
+    "activeAgents": 12,
+    "avgConfidence": 0.87,
+    "systemHealth": "healthy",
+    "redis": {
+      "connected": true,
+      "uptime": 3600
+    },
+    "performance": {
+      "cpuUsage": 45.2,
+      "memoryUsage": 1024
+    }
+  }
+}
+```
+
+**Example:**
+```bash
+# Get all metrics (JSON)
+./invoke-portal-metrics.sh
+
+# Filter by agent (table format)
+./invoke-portal-metrics.sh --agent coder-1 --format table
+
+# Specific timeframe
+./invoke-portal-metrics.sh --timeframe 5m --view performance
+```
+
+---
+
+### 3. invoke-portal-dashboard.sh
+
+**Purpose:** Fetch comprehensive dashboard summary
+
+**Usage:**
+```bash
+./.claude/skills/web-portal/invoke-portal-dashboard.sh [--port PORT] [--format json|table]
+```
+
+**Arguments:**
+- `--port PORT` - Server port (default: 3000)
+- `--format json|table` - Output format (default: json)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "dashboard": {
+    "activeAgents": 12,
+    "systemHealth": "healthy",
+    "metrics": {
+      "totalAgents": 15,
+      "avgConfidence": 0.87,
+      "redis": { "connected": true }
+    },
+    "timestamp": "2025-10-19T12:00:00Z"
+  }
+}
+```
+
+**Example:**
+```bash
+# Get dashboard (JSON)
+./invoke-portal-dashboard.sh
+
+# Table format
+./invoke-portal-dashboard.sh --format table
+```
+
+**Table Output:**
+```
+=== Dashboard Summary ===
+Active Agents: 12
+System Health: healthy
+Timestamp: 2025-10-19T12:00:00Z
+
+=== Metrics ===
+totalAgents: 15
+avgConfidence: 0.87
+...
+```
+
+---
+
+### 4. invoke-portal-agents.sh
+
+**Purpose:** Query agent hierarchy and individual agent status
+
+**Usage:**
+```bash
+./.claude/skills/web-portal/invoke-portal-agents.sh [OPTIONS]
+```
+
+**Arguments:**
+- `--status STATUS` - Filter by status (active, idle, error)
+- `--type TYPE` - Filter by agent type (coder, tester, reviewer)
+- `--swarm SWARM_ID` - Filter by swarm ID
+- `--agent-id AGENT_ID` - Get specific agent status
+- `--format json|table` - Output format (default: json)
+- `--port PORT` - Server port (default: 3000)
+
+**Hierarchy Query Returns:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "coder-1",
+      "status": "active",
+      "type": "coder",
+      "swarmId": "swarm-123",
+      "confidence": 0.85,
+      "uptime": 3600
+    }
+  ]
+}
+```
+
+**Agent Status Query Returns:**
+```json
+{
+  "data": {
+    "id": "coder-1",
+    "status": "active",
+    "type": "coder",
+    "confidence": 0.85,
+    "uptime": 3600,
+    "metrics": {
+      "tokensUsed": 15000,
+      "apiCalls": 25,
+      "successRate": 0.96
+    }
+  }
+}
+```
+
+**Example:**
+```bash
+# Get all agents
+./invoke-portal-agents.sh
+
+# Active agents only
+./invoke-portal-agents.sh --status active
+
+# Specific swarm
+./invoke-portal-agents.sh --swarm swarm-123
+
+# Single agent status
+./invoke-portal-agents.sh --agent-id coder-1
+
+# Table format
+./invoke-portal-agents.sh --status active --format table
+```
+
+---
+
+### 5. invoke-portal-events.sh
+
+**Purpose:** Query event timeline with filtering and pagination
+
+**Usage:**
+```bash
+./.claude/skills/web-portal/invoke-portal-events.sh [OPTIONS]
+```
+
+**Arguments:**
+- `--type TYPE` - Filter by event type
+- `--agent AGENT_ID` - Filter by agent
+- `--phase PHASE_ID` - Filter by phase
+- `--since TIMESTAMP` - Events since timestamp
+- `--severity LEVEL` - Filter by severity (info, warning, error, critical)
+- `--limit NUM` - Max events to return (default: 50)
+- `--offset NUM` - Pagination offset (default: 0)
+- `--format json|table` - Output format (default: json)
+- `--port PORT` - Server port (default: 3000)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "timestamp": "2025-10-19T12:00:00Z",
+      "phaseId": "phase-1",
+      "agentId": "coder-1",
+      "eventType": "agent.lifecycle",
+      "payload": { "status": "spawned" },
+      "metadata": { "severity": "info" }
+    }
+  ]
+}
+```
+
+**Example:**
+```bash
+# Get recent events
+./invoke-portal-events.sh --limit 100
+
+# Filter by agent
+./invoke-portal-events.sh --agent coder-1
+
+# Filter by phase
+./invoke-portal-events.sh --phase phase-auth
+
+# Error events only
+./invoke-portal-events.sh --severity error
+
+# Pagination
+./invoke-portal-events.sh --limit 50 --offset 100
+
+# Table format
+./invoke-portal-events.sh --type agent.lifecycle --format table
+```
+
+**Table Output:**
+```
+=== Events Timeline ===
+Total Events: 25
+
+[2025-10-19T12:00:00Z] agent.lifecycle - Agent: coder-1 - Phase: phase-1
+[2025-10-19T12:00:05Z] agent.complete - Agent: coder-1 - Phase: phase-1
+...
+```
+
+---
+
+### 6. invoke-portal-stop.sh
+
+**Purpose:** Gracefully stop web portal server with cleanup
+
+**Usage:**
+```bash
+./.claude/skills/web-portal/invoke-portal-stop.sh [--port PORT] [--force]
+```
+
+**Arguments:**
+- `--port PORT` - Server port (default: 3000)
+- `--force` - Skip graceful shutdown, force kill
+
+**Shutdown Sequence:**
+1. Attempt graceful shutdown via `/api/shutdown` (if implemented)
+2. Wait up to 10 seconds for clean exit
+3. Terminate process via SIGTERM
+4. Force kill with SIGKILL if needed
+5. Kill by port using `lsof`
+6. Cleanup PID file
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": "Web portal server stopped successfully",
+  "port": 3000,
+  "pid": "12345",
+  "method": "graceful"
+}
+```
+
+**Example:**
+```bash
+# Graceful shutdown
+./invoke-portal-stop.sh
+
+# Force shutdown
+./invoke-portal-stop.sh --force
+
+# Custom port
+./invoke-portal-stop.sh --port 3001
+```
+
+---
+
+## WebSocket Integration
+
+### Real-Time Event Streaming
+
+The web portal provides WebSocket support for live updates:
+
+**Connection:**
+```javascript
+const socket = io('http://localhost:3000');
+
+socket.on('agent_update', (data) => {
+  console.log('Agent updated:', data);
+});
+
+socket.on('metrics_update', (data) => {
+  console.log('Metrics updated:', data);
+});
+```
+
+**Event Types:**
+- `agent_update` - Agent status changes
+- `metrics_update` - System metrics refresh
+- `event_stream` - New events published
+- `connection_status` - WebSocket health
+
+### Coordination Pattern
+
+```bash
+# Publish agent lifecycle event (triggers WebSocket broadcast)
+redis-cli publish "web-portal:agents" '{"agent":"coder-1","status":"active"}'
+
+# Publish metrics update
+redis-cli publish "web-portal:metrics" '{"systemHealth":"healthy"}'
+
+# Publish custom event
+redis-cli publish "web-portal:events" '{"type":"deployment","status":"success"}'
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+**Server Not Running:**
+```json
+{
+  "success": false,
+  "error": "Failed to query metrics API at http://localhost:3000/api/metrics"
+}
+```
+
+**Invalid Response:**
+```json
+{
+  "success": false,
+  "error": "Invalid JSON response from metrics API"
+}
+```
+
+**Health Check Timeout:**
+```json
+{
+  "success": false,
+  "error": "Server failed health check after 30 attempts",
+  "port": 3000,
+  "redisConnected": false
+}
+```
+
+### Error Recovery
+
+1. **Check Redis:** Ensure Redis is running (`redis-cli ping`)
+2. **Verify Port:** Check no port conflicts (`lsof -ti:3000`)
+3. **Clean Restart:** Stop server, clear cache, restart
+4. **Check Logs:** Review server output for errors
+
+---
+
+## Performance Considerations
+
+### Caching Strategy
+
+**Client-Side Cache (invoke-portal-metrics.sh):**
+- TTL: 60 seconds
+- Cache directory: `.artifacts/cache/web-portal/`
+- Automatic invalidation
+
+**Server-Side Cache:**
+- Metrics: 10 seconds
+- Agent hierarchy: 30 seconds
+- Agent status: No cache (real-time)
+
+### Best Practices
+
+1. **Use caching for repeated queries** - Metrics script caches automatically
+2. **Filter at API level** - Use query parameters instead of client filtering
+3. **Paginate large results** - Use `--limit` and `--offset` for events
+4. **Batch operations** - Query dashboard once instead of multiple endpoints
+5. **Close WebSocket connections** - Use graceful shutdown to prevent leaks
+
+---
+
+## Integration Examples
+
+### Agent Spawning Integration
+
+```bash
+# Start portal before spawning agents
+./invoke-portal-start.sh
+
+# Spawn agents (they'll appear in portal)
+npx claude-flow-novice swarm "Build API" --max-agents 5
+
+# Monitor agent status
+./invoke-portal-agents.sh --status active --format table
+
+# Check metrics
+./invoke-portal-metrics.sh --format table
+
+# Cleanup
+./invoke-portal-stop.sh
+```
+
+### CFN Loop Monitoring
+
+```bash
+# Start portal
+./invoke-portal-start.sh
+
+# Launch CFN Loop (monitored by portal)
+/cfn-loop "Authentication system" --phase auth
+
+# Monitor Loop 3 agents
+./invoke-portal-agents.sh --swarm cfn-loop-auth
+
+# Track events
+./invoke-portal-events.sh --phase phase-auth --limit 100
+
+# Get consensus metrics
+./invoke-portal-metrics.sh --view consensus
+```
+
+### Continuous Monitoring Script
+
+```bash
+#!/usr/bin/env bash
+# Monitor web portal metrics every 30 seconds
+
+while true; do
+  echo "=== $(date) ==="
+  ./.claude/skills/web-portal/invoke-portal-dashboard.sh --format table
+  echo ""
+  sleep 30
+done
+```
+
+---
+
+## Security Considerations
+
+### Authentication
+
+- Development mode: No authentication required
+- Production mode: JWT authentication enforced
+- API key authentication for programmatic access
+
+### Rate Limiting
+
+- Metrics endpoint: 100 req/min per IP
+- Events endpoint: 1000 req/15min per IP
+- Agent intervention: 10 req/min per IP
+
+### Data Validation
+
+- All query parameters sanitized
+- JSON payloads validated
+- SQL injection prevention (parameterized queries)
+- XSS protection (output encoding)
+
+---
+
+## Troubleshooting
+
+### Server Won't Start
+
+```bash
+# Check port availability
+lsof -ti:3000
+
+# Kill existing process
+lsof -ti:3000 | xargs -r kill -9
+
+# Verify Redis
+redis-cli ping
+
+# Start with verbose logs
+PORT=3000 npm run dev
+```
+
+### Cache Issues
+
+```bash
+# Clear cache
+rm -rf .artifacts/cache/web-portal/
+
+# Bypass cache (direct query)
+curl http://localhost:3000/api/metrics
+```
+
+### WebSocket Connection Failures
+
+```bash
+# Verify server supports WebSocket
+curl -I http://localhost:3000/socket.io/
+
+# Check firewall rules
+# Ensure port 3000 allows WebSocket upgrade
+```
+
+---
+
+## Skill Confidence Scoring
+
+### Self-Assessment Criteria
+
+- **Server Health:** Redis connected, API responsive
+- **Data Accuracy:** Metrics match Redis state
+- **Performance:** Cache hit rate >80%
+- **Error Rate:** <5% failed requests
+- **Uptime:** >99% availability
+
+### Confidence Formula
+
+```
+confidence = (
+  0.3 * health_score +
+  0.3 * data_accuracy +
+  0.2 * cache_efficiency +
+  0.1 * error_rate +
+  0.1 * uptime
+)
+```
+
+**Target:** 0.85 for production readiness
+
+---
+
+## Version History
+
+**1.0.0 (2025-10-19):**
+- Initial release
+- 6 core invoke scripts
+- WebSocket integration
+- Caching support
+- Production-ready documentation
+
+---
+
+## Related Skills
+
+- **Redis Coordination:** `.claude/skills/redis-coordination/SKILL.md`
+- **Agent Spawning:** `.claude/skills/agent-spawning/SKILL.md`
+- **CFN Loop Validation:** `.claude/skills/cfn-loop-validation/SKILL.md`
+
+---
+
+## Maintenance Schedule
+
+- **Weekly:** Cache cleanup, log rotation
+- **Monthly:** Security audit, dependency updates
+- **Quarterly:** Performance benchmarking, optimization
+
+**Next Review:** 2025-11-19