claude-flow-novice 2.5.2 → 2.8.1

package/.claude/skills/agent-output-processing/SKILL.md

@@ -0,0 +1,359 @@
+# Agent Output Processing Skill (Universal)
+
+**Version:** 1.0.0
+**Status:** Production
+**Purpose:** Guaranteed structured output extraction from any agent type
+
+---
+
+## Overview
+
+**Problem Solved:** Agent templates cannot force tool execution or guarantee output format.
+
+**Solution:** Orchestrator-controlled output processing with robust parsing, validation, and Redis coordination.
+
+**Applicable To:** Any agent requiring structured output (Product Owner, validators, analyzers, decision-makers)
+
+---
+
+## Core Principle
+
+```
+Agent Templates → Focus on analysis/decision-making
+Skills → Handle execution/coordination/formatting
+Orchestrators → Control workflow and Redis state
+```
+
+**Why This Works:**
+- ✅ Agents do what they're good at (analysis)
+- ✅ Skills enforce structure (parsing, validation)
+- ✅ Orchestrators maintain coordination (Redis, timing)
+- ✅ No reliance on agent tool usage compliance
+
+---
+
+## Architecture
+
+### Generic Flow
+
+```
+1. Orchestrator → Spawn agent with structured context
+2. Skill → Capture agent stdout/stderr
+3. Skill → Parse output (pattern matching with fallbacks)
+4. Skill → Validate output (business logic checks)
+5. Skill → Transform to required format (JSON, etc.)
+6. Skill → Push to Redis (coordination state)
+7. Skill → Signal completion
+```
+
+### Skill Components
+
+```
+.claude/skills/agent-output-processing/
+├── SKILL.md                          # This file
+├── execute-with-parsing.sh           # Generic agent wrapper
+├── parse-structured-output.sh        # Multi-pattern parser
+├── validate-output.sh                # Validation framework
+└── patterns/                         # Agent-specific patterns
+    ├── product-owner.json            # PROCEED/ITERATE/ABORT
+    ├── validator.json                # confidence + feedback
+    ├── analyzer.json                 # metrics + recommendations
+    └── decision-maker.json           # choice + reasoning
+```
+
+---
+
+## Usage Patterns
+
+### Pattern 1: Decision Output (Product Owner)
+
+**Output Requirements:** Must extract PROCEED/ITERATE/ABORT
+
+```bash
+RESULT=$(./.claude/skills/agent-output-processing/execute-with-parsing.sh \
+  --agent-type "product-owner" \
+  --pattern-file "patterns/product-owner.json" \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --context "Loop 2 consensus: 0.92" \
+  --redis-key "swarm:${TASK_ID}:${AGENT_ID}:decision")
+
+DECISION=$(echo "$RESULT" | jq -r '.decision')
+```
+
+**Pattern File (patterns/product-owner.json):**
+```json
+{
+  "name": "product-owner-decision",
+  "required_fields": ["decision"],
+  "patterns": [
+    {
+      "field": "decision",
+      "regex": "Decision:\\s*(PROCEED|ITERATE|ABORT)",
+      "extract": "keyword",
+      "fallbacks": [
+        "(PROCEED|ITERATE|ABORT)",
+        "(?i)(proceed|iterate|abort)"
+      ]
+    },
+    {
+      "field": "reasoning",
+      "regex": "Reasoning:\\s*(.+)",
+      "extract": "capture_group"
+    }
+  ],
+  "validation": {
+    "decision": {
+      "type": "enum",
+      "values": ["PROCEED", "ITERATE", "ABORT"]
+    }
+  }
+}
+```
+
+### Pattern 2: Confidence + Feedback (Validators)
+
+**Output Requirements:** Must extract confidence score and feedback list
+
+```bash
+RESULT=$(./.claude/skills/agent-output-processing/execute-with-parsing.sh \
+  --agent-type "reviewer" \
+  --pattern-file "patterns/validator.json" \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --context "Review Loop 3 implementation" \
+  --redis-key "swarm:${TASK_ID}:${AGENT_ID}:result")
+
+CONFIDENCE=$(echo "$RESULT" | jq -r '.confidence')
+FEEDBACK=$(echo "$RESULT" | jq -r '.feedback[]')
+```
+
+**Pattern File (patterns/validator.json):**
+```json
+{
+  "name": "validator-result",
+  "required_fields": ["confidence"],
+  "patterns": [
+    {
+      "field": "confidence",
+      "regex": "Confidence:\\s*([0-9.]+)",
+      "extract": "float",
+      "fallbacks": [
+        "confidence[:\\s]+([0-9.]+)",
+        "score[:\\s]+([0-9.]+)"
+      ]
+    },
+    {
+      "field": "feedback",
+      "regex": "Feedback:\\s*\\n([\\s\\S]+?)(?=\\n\\n|$)",
+      "extract": "multiline_list"
+    }
+  ],
+  "validation": {
+    "confidence": {
+      "type": "float",
+      "min": 0.0,
+      "max": 1.0
+    }
+  }
+}
+```
+
+### Pattern 3: Metrics + Recommendations (Analyzers)
+
+**Output Requirements:** Must extract metrics object and recommendation list
+
+```bash
+RESULT=$(./.claude/skills/agent-output-processing/execute-with-parsing.sh \
+  --agent-type "code-analyzer" \
+  --pattern-file "patterns/analyzer.json" \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --context "Analyze codebase quality" \
+  --redis-key "swarm:${TASK_ID}:${AGENT_ID}:analysis")
+
+COMPLEXITY=$(echo "$RESULT" | jq -r '.metrics.complexity')
+RECOMMENDATIONS=$(echo "$RESULT" | jq -r '.recommendations[]')
+```
+
+---
+
+## Implementation
+
+### execute-with-parsing.sh
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Parse arguments
+AGENT_TYPE=""
+PATTERN_FILE=""
+TASK_ID=""
+AGENT_ID=""
+CONTEXT=""
+REDIS_KEY=""
+TIMEOUT=900
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --agent-type) AGENT_TYPE="$2"; shift 2 ;;
+    --pattern-file) PATTERN_FILE="$2"; shift 2 ;;
+    --task-id) TASK_ID="$2"; shift 2 ;;
+    --agent-id) AGENT_ID="$2"; shift 2 ;;
+    --context) CONTEXT="$2"; shift 2 ;;
+    --redis-key) REDIS_KEY="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    *) echo "Unknown: $1"; exit 1 ;;
+  esac
+done
+
+# Spawn agent and capture output
+AGENT_OUTPUT=$(timeout "$TIMEOUT" npx claude-flow-novice agent "$AGENT_TYPE" \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --context "$CONTEXT" 2>&1 || true)
+
+# Parse structured output using pattern file
+PARSED_OUTPUT=$(./parse-structured-output.sh \
+  --pattern-file "$PATTERN_FILE" \
+  --output "$AGENT_OUTPUT")
+
+# Validate parsed output
+if ! ./validate-output.sh --pattern-file "$PATTERN_FILE" --data "$PARSED_OUTPUT"; then
+  echo "ERROR: Output validation failed" >&2
+  exit 1
+fi
+
+# Push to Redis if key provided
+if [ -n "$REDIS_KEY" ]; then
+  echo "$PARSED_OUTPUT" | redis-cli -x LPUSH "$REDIS_KEY" >/dev/null
+  redis-cli LPUSH "swarm:${TASK_ID}:${AGENT_ID}:done" "complete" >/dev/null
+fi
+
+# Output structured result
+echo "$PARSED_OUTPUT"
+```
+
+---
+
+## Benefits Over Template-Based
+
+| Aspect | Template-Based | Skill-Based (Universal) |
+|--------|----------------|-------------------------|
+| **Execution Guarantee** | ❌ Agent decides | ✅ Skill enforces |
+| **Output Format** | ❌ Inconsistent | ✅ Guaranteed structure |
+| **Parsing Robustness** | ❌ None | ✅ Multi-pattern fallbacks |
+| **Validation** | ❌ Manual | ✅ Automated schema checks |
+| **Redis Coordination** | ❌ Agent-dependent | ✅ Skill-controlled |
+| **Reusability** | ❌ Per-agent templates | ✅ Universal pattern system |
+| **Testability** | ❌ Hard to test | ✅ Unit tests per pattern |
+| **Extensibility** | ❌ Template changes | ✅ Add pattern files |
+
+---
+
+## Agent-Specific Implementations
+
+### Existing: Product Owner Decision
+**Location:** `.claude/skills/product-owner-decision/`
+**Pattern:** PROCEED/ITERATE/ABORT extraction
+**Status:** ✅ Operational (BUG #11 fix)
+
+### Future: Validator Agents
+**Pattern:** Confidence + feedback extraction
+**Use Case:** Loop 2 validators (reviewer, tester, security)
+**Benefit:** Guaranteed confidence scoring
+
+### Future: Analyzer Agents
+**Pattern:** Metrics + recommendations extraction
+**Use Case:** Code quality, performance, security analyzers
+**Benefit:** Structured analysis output
+
+---
+
+## Migration Strategy
+
+### Phase 1: Product Owner (✅ Complete)
+- Created dedicated skill
+- Integrated with orchestrator
+- Solves BUG #11
+
+### Phase 2: Validators (Planned)
+- Extract confidence scores reliably
+- Parse feedback into structured lists
+- Prevent 0.0 confidence issues
+
+### Phase 3: All Decision-Making Agents (Future)
+- Standardize output processing
+- Centralize pattern definitions
+- Enable cross-agent consistency
+
+---
+
+## Testing
+
+### Unit Tests
+```bash
+# Test pattern parsing
+./test-parse-structured-output.sh --pattern-file patterns/product-owner.json
+
+# Test validation logic
+./test-validate-output.sh --pattern-file patterns/validator.json
+```
+
+### Integration Tests
+```bash
+# Test full agent execution with parsing
+./test-execute-with-parsing.sh --agent-type product-owner
+```
+
+---
+
+## Related Skills
+
+- **Product Owner Decision** (`.claude/skills/product-owner-decision/SKILL.md`) - Specific implementation
+- **Redis Coordination** (`.claude/skills/redis-coordination/SKILL.md`) - State management
+- **CFN Loop Validation** (`.claude/skills/cfn-loop-validation/SKILL.md`) - Quality gates
+
+---
+
+## Lessons Learned
+
+### ANTI-PATTERN: Template-Forced Tool Usage
+**What Doesn't Work:** Telling agents "Use Bash tool to execute X"
+
+**Why:** Agents interpret instructions autonomously, treating code blocks as documentation
+
+**Better:** Capture agent output and parse it with robust patterns
+
+### PATTERN: Orchestrator Control
+**Principle:** Coordination belongs in orchestrators/skills, not agent templates
+
+**Rationale:**
+- Agents focus on analysis (what they do well)
+- Skills handle structure (parsing, validation)
+- Orchestrators manage coordination (Redis, timing)
+
+### PATTERN: Multi-Fallback Parsing
+**Principle:** Use multiple pattern matching strategies with increasing leniency
+
+**Example:**
+1. Strict: "Decision: PROCEED" (labeled, exact case)
+2. Moderate: "PROCEED" (standalone keyword)
+3. Lenient: "proceed" (case-insensitive)
+4. Desperate: JSON extraction
+
+---
+
+## Version History
+
+### 1.0.0 (2025-10-20)
+- Initial skill creation
+- Generalized from Product Owner fix
+- Universal pattern-based output processing
+- Validation framework
+- Redis coordination integration
+
+---
+
+**Summary:** This skill provides universal output processing for any agent type, eliminating reliance on template-based tool usage compliance and guaranteeing structured, validated results.

package/.claude/skills/agent-selector/SKILL.md

@@ -0,0 +1,90 @@
+# Agent Selector Skill
+
+**Version:** 1.0.0
+**Purpose:** Select optimal agents for CFN Loop v3 based on task type and requirements
+
+## Overview
+
+Recommends Loop 3 (producers) and Loop 2 (evaluators) agents based on:
+- Task type (from task-classifier)
+- Task description keywords
+- Complexity requirements
+
+## Usage
+
+```bash
+AGENTS=$(./.claude/skills/agent-selector/select-agents.sh \
+  --task-type "software-development" \
+  --description "Implement JWT authentication with refresh tokens")
+
+echo "$AGENTS" | jq '.loop3[]'  # ["backend-dev", "security-specialist"]
+echo "$AGENTS" | jq '.loop2[]'  # ["reviewer", "tester", "security-auditor"]
+```
+
+## Output Format
+
+```json
+{
+  "loop3": ["agent1", "agent2", "agent3"],
+  "loop2": ["validator1", "validator2", "validator3"],
+  "loop4": "product-owner",
+  "reasoning": "Explanation of agent selection"
+}
+```
+
+## Agent Selection Rules
+
+### Software Development
+**Base Loop 3:** backend-dev, coder
+**Add if keywords:**
+- "security", "authentication", "JWT" → security-specialist
+- "database", "SQL", "schema" → database-engineer (if exists)
+- "deploy", "CI/CD", "infrastructure" → devops-engineer
+- "frontend", "React", "UI" → react-frontend-engineer
+
+**Loop 2:** reviewer, tester, security-auditor
+
+### Content Creation
+**Base Loop 3:** copywriter, content-strategist
+**Add if keywords:**
+- "SEO", "search", "keywords" → seo-specialist
+- "technical", "documentation" → technical-writer (if exists)
+
+**Loop 2:** editor, brand-reviewer, compliance-checker
+
+### Research
+**Base Loop 3:** researcher, data-analyst
+**Add if keywords:**
+- "statistics", "data analysis" → statistician (if exists)
+- "domain-specific" → domain-expert
+
+**Loop 2:** fact-checker, methodology-reviewer, statistician
+
+### Design
+**Base Loop 3:** ui-designer, ux-researcher
+**Add if keywords:**
+- "visual", "branding" → visual-designer
+- "accessibility" → accessibility-advocate
+
+**Loop 2:** accessibility-advocate, design-critic, user-tester
+
+### Infrastructure
+**Base Loop 3:** devops-engineer, terraform-engineer
+**Add if keywords:**
+- "Kubernetes", "k8s", "container" → kubernetes-architect
+- "network", "security" → network-engineer (if exists)
+
+**Loop 2:** security-auditor, cost-optimizer, compliance-checker
+
+### Data Engineering
+**Base Loop 3:** data-engineer, pipeline-builder
+**Add if keywords:**
+- "ETL", "transformation" → etl-specialist
+- "streaming", "real-time" → streaming-specialist (if exists)
+
+**Loop 2:** data-quality-validator, schema-reviewer, performance-tester
+
+## Integration
+
+Used by:
+- `.claude/agents/cfn-v3-coordinator.md` - Agent selection

package/.claude/skills/agent-selector/select-agents.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Dynamic Agent Selection with JSON Registry
+
+set -euo pipefail
+
+# Paths
+REGISTRY_PATH=".claude/skills/agent-discovery/agents-registry.json"
+LOG_PATH="/tmp/agent_selection_$(date +%s).log"
+
+# Validate inputs
+if [[ $# -lt 2 ]]; then
+    echo "Usage: $0 --task-type TYPE --description 'task description'" >&2
+    exit 1
+fi
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --task-type) TASK_TYPE="$2"; shift 2 ;;
+        --description) DESCRIPTION="$2"; shift 2 ;;
+        *) echo "Unknown parameter: $1" >&2; exit 1 ;;
+    esac
+done
+
+# Validate registry
+if [[ ! -f "$REGISTRY_PATH" ]]; then
+    echo "Error: Agent registry not found at $REGISTRY_PATH. Run agent discovery first." >&2
+    exit 1
+fi
+
+# Score agents function with simple matching
+score_agents() {
+    local registry_path="$1"
+    local description="$2"
+    local task_type="$3"
+
+    # Simple JQ query for agent matching
+    jq -r --arg desc "$description" --arg task_type "$task_type" '
+        [
+            .agents[]
+            | select(.type == $task_type)
+            | {
+                name: .name,
+                score: (
+                    # Base type match score
+                    10 +
+                    # Keyword matching
+                    (
+                        [.keywords[]]
+                        | map(select(
+                            ($desc | ascii_downcase | contains(. | ascii_downcase))
+                        ))
+                        | length * 3
+                    )
+                )
+            }
+        ]
+        | sort_by(.score)
+        | reverse
+        | .[0:3]
+        | map(.name)
+    ' "$registry_path"
+}
+
+# Score agents
+LOOP3_AGENTS=$(score_agents "$REGISTRY_PATH" "$DESCRIPTION" "specialist")
+LOOP2_AGENTS=$(score_agents "$REGISTRY_PATH" "$DESCRIPTION" "strategic")
+
+# Default fallback
+if [[ -z "$LOOP3_AGENTS" || "$LOOP3_AGENTS" == "[]" ]]; then
+    LOOP3_AGENTS='["product-owner"]'
+fi
+
+if [[ -z "$LOOP2_AGENTS" || "$LOOP2_AGENTS" == "[]" ]]; then
+    LOOP2_AGENTS='["product-owner"]'
+fi
+
+# Log the results
+{
+    echo "Task Description: $DESCRIPTION"
+    echo "Loop 3 Agents: $LOOP3_AGENTS"
+    echo "Loop 2 Agents: $LOOP2_AGENTS"
+} >> "$LOG_PATH"
+
+# Output JSON result with detailed reasoning
+jq -n \
+    --argjson loop3 "$LOOP3_AGENTS" \
+    --argjson loop2 "$LOOP2_AGENTS" \
+    --arg desc "$DESCRIPTION" \
+    '{
+        "loop3": $loop3,
+        "loop2": $loop2,
+        "loop4": "product-owner",
+        "reasoning": "Selected agents by scoring against task description: \($desc)",
+        "log_path": "'"$LOG_PATH"'"
+    }'

package/.claude/skills/agent-spawning/agent-selection-guide.md

@@ -135,7 +135,7 @@ Code Quality Focus → + code-analyzer
 **Complex (6-7 agents):**
 ```bash
 # Enterprise features, multi-component systems
---agents=analyst,system-architect,backend-dev,frontend-dev,security-specialist,tester,reviewer
+--agents=analyst,system-architect,backend-dev,react-frontend-engineer,security-specialist,tester,reviewer
 --agents=system-architect,architect,backend-dev,security-specialist,devops-engineer,production-validator
 ```
 

package/.claude/skills/agent-swap/SKILL.md

@@ -0,0 +1,36 @@
+# Agent Swap Mechanism Skill
+
+## Purpose
+Recommend agent replacement strategies when performance issues are detected in CFN Loops.
+
+## Replacement Rules
+1. Identify lowest-performing agent
+2. Match replacement based on feedback themes
+   - Security feedback → security-specialist
+   - Performance feedback → performance-engineer
+   - Testing feedback → tester
+   - Architecture feedback → architect
+
+## Replacement Strategies
+- Complete agent replacement
+- Adding specialist alongside existing agents
+- Prioritize maintaining existing team composition
+
+## Usage
+```bash
+./recommend-swap.sh \
+  --loop3-agents "backend-dev,coder" \
+  --loop3-confidences "0.82,0.70" \
+  --feedback-themes "security,error-handling"
+```
+
+## Output Details
+- Agent to remove
+- Reasoning for removal
+- Recommended replacement agent
+- Updated agent configuration
+
+## Implementation Considerations
+- Stateless design
+- Minimal side effects
+- Clear, reproducible recommendations

package/.claude/skills/agent-swap/recommend-swap.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --loop3-agents) IFS=',' read -ra AGENTS <<< "$2"; shift 2 ;;
+        --loop3-confidences) IFS=',' read -ra CONFIDENCES <<< "$2"; shift 2 ;;
+        --feedback-themes) IFS=',' read -ra THEMES <<< "$2"; shift 2 ;;
+        *) echo "Unknown parameter: $1"; exit 1 ;;
+    esac
+done
+
+# Agent Swap Rules
+get_specialist_for_theme() {
+    local theme="$1"
+    case "$theme" in
+        *security*) echo "security-specialist" ;;
+        *performance*) echo "performance-engineer" ;;
+        *test*|*coverage*) echo "testing-expert" ;;
+        *architecture*) echo "architecture-consultant" ;;
+        *) echo "generic-specialist" ;;
+    esac
+}
+
+# Find lowest confidence agent
+lowest_confidence_index=0
+lowest_confidence="${CONFIDENCES[0]}"
+
+for i in "${!CONFIDENCES[@]}"; do
+    if (( $(echo "${CONFIDENCES[i]} < $lowest_confidence" | bc -l) )); then
+        lowest_confidence="${CONFIDENCES[i]}"
+        lowest_confidence_index=$i
+    fi
+done
+
+# Recommend replacement specialist
+recommended_specialist=""
+for theme in "${THEMES[@]}"; do
+    specialist=$(get_specialist_for_theme "$theme")
+    if [[ -n "$specialist" ]]; then
+        recommended_specialist="$specialist"
+        break
+    fi
+done
+
+# Generate output
+jq -n \
+    --arg remove_agent "${AGENTS[lowest_confidence_index]}" \
+    --arg add_agent "$recommended_specialist" \
+    --argjson agents "$(printf '%s\n' "${AGENTS[@]}" | jq -R . | jq -s '.')" \
+    --arg lowest_confidence "$lowest_confidence" \
+    --argjson themes "$(printf '%s\n' "${THEMES[@]}" | jq -R . | jq -s '.')" \
+    '{
+        "remove_agent": $remove_agent,
+        "remove_reason": "Lowest confidence (\($lowest_confidence)), contributing to plateau",
+        "add_agent": $add_agent,
+        "add_reason": "Match to feedback themes: \(join(", ", $themes))",
+        "new_loop3_agents": [$agents | map(select(. != $remove_agent)), $add_agent]
+    }'

package/.claude/skills/api-validation/test-endpoints.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# API Endpoint Validation Script
+# Usage: ./test-endpoints.sh <base-url> <endpoint> [request-count]
+
+BASE_URL="${1:-http://localhost:8080}"
+ENDPOINT="$2"
+COUNT="${3:-10}"
+
+if [ -z "$ENDPOINT" ]; then
+  echo "Usage: $0 <base-url> <endpoint> [request-count]"
+  exit 1
+fi
+
+echo "Testing: $BASE_URL$ENDPOINT"
+echo "Requests: $COUNT"
+echo ""
+
+SUCCESS=0
+FAILED=0
+TOTAL_RESPONSE_TIME=0
+
+for i in $(seq 1 "$COUNT"); do
+  START_TIME=$(date +%s.%N)
+  RESPONSE=$(curl -s -w "\n%{http_code}\n%{time_total}" "$BASE_URL$ENDPOINT")
+
+  HTTP_STATUS=$(echo "$RESPONSE" | tail -1)
+  RESPONSE_TIME=$(echo "$RESPONSE" | tail -2 | head -1)
+  BODY=$(echo "$RESPONSE" | head -n -2)
+
+  if [ "$HTTP_STATUS" = "200" ]; then
+    echo "✅ Request $i: 200 OK (Response Time: ${RESPONSE_TIME}s)"
+    ((SUCCESS++))
+  else
+    echo "❌ Request $i: $HTTP_STATUS"
+    echo "   Response: $BODY"
+    ((FAILED++))
+  fi
+
+  TOTAL_RESPONSE_TIME=$(echo "$TOTAL_RESPONSE_TIME + $RESPONSE_TIME" | bc)
+
+  [ $i -lt "$COUNT" ] && sleep 2
+done
+
+AVG_RESPONSE_TIME=$(echo "scale=3; $TOTAL_RESPONSE_TIME / $COUNT" | bc)
+
+echo ""
+echo "Results:"
+echo "- Requests: $COUNT total"
+echo "- Succeeded: $SUCCESS"
+echo "- Failed: $FAILED"
+echo "- Average Response Time: ${AVG_RESPONSE_TIME}s"
+
+# Strict success criteria
+[ $FAILED -eq 0 ] && exit 0 || exit 1