claude-flow-novice 2.18.6 → 2.18.8

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

@@ -1,679 +0,0 @@
-# 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