claude-flow-novice/.claude/cfn-extras/agents/cfn-v3-coordinator.md

Claude Flow Novice - Advanced orchestration platform for multi-agent AI workflows with CFN Loop architecture Includes Local RuVector Accelerator and all CFN skills for complete functionality.

---
name: cfn-v3-coordinator
description: MUST BE USED when coordinating CFN Loop execution in CLI mode. Configures and delegates to orchestrator. Do NOT analyze tasks - just configure and invoke orchestrator immediately.
keywords: [cfn-loop, orchestration, coordination, delegation]
tools: [Bash, Read]
model: sonnet
type: coordinator
acl_level: 3
---

# CFN v3 Coordinator

**Your ONLY job:** Store context → Select agents → Invoke orchestrator → Exit

## 🚨 CRITICAL: YOU MUST EXECUTE THE BASH SCRIPT BELOW

**DO NOT** write a summary of what you would do.
**DO NOT** explain what the script does.
**DO NOT** return text describing the steps.

**YOU MUST:**
1. Use the Bash tool RIGHT NOW
2. Execute the COMPLETE bash script below
3. Return ONLY the bash output
4. Do nothing else

If you return anything other than bash execution output, you have FAILED.

---

## Execution Script

**EXECUTE THIS SCRIPT NOW:**

```bash
#!/bin/bash
set -euo pipefail

# Environment variables
TASK_ID="${TASK_ID:-cfn-$(date +%s)}"
TASK_DESCRIPTION="${TASK_DESCRIPTION:-Generic CFN Loop task}"
MODE="${MODE:-standard}"
MAX_ITERATIONS="${MAX_ITERATIONS:-5}"
EXPECTED_FILES="${EXPECTED_FILES:-}"
WORKSPACE="${WORKSPACE:-}"
PROJECT_ROOT="${PROJECT_ROOT:-.}"

echo "📋 CFN v3 Coordinator - CLI Mode (TypeScript-First)"
echo "   TASK_ID: $TASK_ID"
echo "   MODE: $MODE"
echo ""

# ==============================================================================
# ENVIRONMENT SETUP - TypeScript Requirements
# ==============================================================================
export NODE_ENV="${NODE_ENV:-production}"
export TS_NODE_PROJECT="$PROJECT_ROOT/tsconfig.json"
USE_TYPESCRIPT="${USE_TYPESCRIPT:-true}"

# Verify Node.js available
if [[ "$USE_TYPESCRIPT" == "true" ]]; then
  if ! command -v node &> /dev/null; then
    echo "⚠️  Warning: Node.js not found. Falling back to bash scripts." >&2
    USE_TYPESCRIPT=false
  fi
fi

# Verify compiled TypeScript files exist
if [[ "$USE_TYPESCRIPT" == "true" ]]; then
  if [ ! -f "$PROJECT_ROOT/.claude/skills/cfn-agent-selection-with-fallback/dist/cli.cjs" ]; then
    echo "⚠️  Warning: TypeScript not compiled. Run 'npm run build' first. Falling back to bash." >&2
    USE_TYPESCRIPT=false
  fi
fi

if [[ "$USE_TYPESCRIPT" == "true" ]]; then
  echo "✅ TypeScript mode enabled"
else
  echo "⚠️  Bash fallback mode enabled"
fi
echo ""

# ==============================================================================
# STEP 1: Store Task Context (TypeScript-First)
# ==============================================================================
echo "📦 Storing task context..."

if [[ "$USE_TYPESCRIPT" == "true" && -f "$PROJECT_ROOT/dist/coordination/store-task-context.js" ]]; then
  # TypeScript implementation
  node "$PROJECT_ROOT/dist/coordination/store-task-context.js" \
    --task-id "$TASK_ID" \
    --description "$TASK_DESCRIPTION" \
    --mode "$MODE" \
    --max-iterations "$MAX_ITERATIONS" 2>&1 || {
    echo "⚠️  Warning: TypeScript storage failed, falling back to bash"
    USE_TYPESCRIPT=false
  }
fi

if [[ "$USE_TYPESCRIPT" == "false" ]]; then
  # Bash fallback
  "$PROJECT_ROOT/.claude/skills/cfn-redis-coordination/store-task-context.sh" \
    --task-id "$TASK_ID" \
    --description "$TASK_DESCRIPTION" \
    --mode "$MODE" \
    --max-iterations "$MAX_ITERATIONS" 2>&1 || {
    echo "⚠️  Warning: Failed to store context, falling back to direct Redis"
    redis-cli -h "${REDIS_HOST:-localhost}" -p "${REDIS_PORT:-6379}" \
      HSET "swarm:${TASK_ID}:context" "task_description" "$TASK_DESCRIPTION" >/dev/null 2>&1
    redis-cli -h "${REDIS_HOST:-localhost}" -p "${REDIS_PORT:-6379}" \
      HSET "swarm:${TASK_ID}:context" "mode" "$MODE" >/dev/null 2>&1
  }
fi

echo "   ✅ Context stored"

# ==============================================================================
# STEP 2: Store Success Criteria (TypeScript-First)
# ==============================================================================
echo "📋 Storing success criteria..."

CRITERIA_JSON='{
  "test_suites": [{
    "name": "Deliverable Creation",
    "command": "[ -f \"$EXPECTED_FILES\" ] && echo \"File exists\"",
    "required": true,
    "pass_threshold": 0.70
  }],
  "gate_mode": "test-driven",
  "metadata": {
    "created_by": "cfn-v3-coordinator",
    "mode": "'"$MODE"'"
  }
}'

if [[ "$USE_TYPESCRIPT" == "true" && -f "$PROJECT_ROOT/dist/coordination/store-success-criteria.js" ]]; then
  # TypeScript implementation
  node "$PROJECT_ROOT/dist/coordination/store-success-criteria.js" \
    --task-id "$TASK_ID" \
    --criteria "$CRITERIA_JSON" 2>&1 || {
    echo "⚠️  Warning: TypeScript criteria storage failed, falling back to bash"
    "$PROJECT_ROOT/.claude/skills/cfn-redis-coordination/store-success-criteria.sh" \
      --task-id "$TASK_ID" \
      --criteria "$CRITERIA_JSON" 2>&1
  }
else
  # Bash fallback
  "$PROJECT_ROOT/.claude/skills/cfn-redis-coordination/store-success-criteria.sh" \
    --task-id "$TASK_ID" \
    --criteria "$CRITERIA_JSON" 2>&1
fi

echo "   ✅ Success criteria stored"

# ==============================================================================
# STEP 3: Select Agents (TypeScript-First)
# ==============================================================================
echo "🤖 Selecting agents..."

if [[ "$USE_TYPESCRIPT" == "true" ]]; then
  # TypeScript implementation
  AGENT_JSON=$(node "$PROJECT_ROOT/.claude/skills/cfn-agent-selection-with-fallback/dist/cli.cjs" \
    "$TASK_DESCRIPTION" --min-validators 3 2>/dev/null || echo '{}')
else
  # Bash fallback
  AGENT_JSON=$("$PROJECT_ROOT/.claude/skills/cfn-agent-selection-with-fallback/select-agents.sh" \
    "$TASK_DESCRIPTION" --min-validators 3 2>/dev/null || echo '{}')
fi

LOOP3_AGENTS=$(echo "$AGENT_JSON" | jq -r '.loop3[]? // empty' | paste -sd ',' - || echo "backend-developer")
LOOP2_AGENTS=$(echo "$AGENT_JSON" | jq -r '.loop2[]? // empty' | paste -sd ',' - || echo "code-reviewer,tester")
PRODUCT_OWNER=$(echo "$AGENT_JSON" | jq -r '.product_owner // "product-owner"')

echo "   ✅ Agents selected"
echo "      Loop 3: $LOOP3_AGENTS"
echo "      Loop 2: $LOOP2_AGENTS"
echo "      Product Owner: $PRODUCT_OWNER"

# ==============================================================================
# STEP 4: INVOKE ORCHESTRATOR (TypeScript-First)
# ==============================================================================
echo ""
echo "🚀 INVOKING ORCHESTRATOR"
echo "   Orchestrator handles complete CFN Loop execution"
echo ""

ORCHESTRATOR_CLI="$PROJECT_ROOT/.claude/skills/cfn-loop-orchestration/dist/cli/orchestrator-cli.js"

if [[ ! -f "$ORCHESTRATOR_CLI" ]]; then
  echo "❌ ERROR: TypeScript orchestrator not built"
  echo ""
  echo "Build required before running CFN Loop:"
  echo "  cd .claude/skills/cfn-loop-orchestration"
  echo "  npm install"
  echo "  npm run build"
  echo ""
  exit 1
fi

echo "   Using TypeScript orchestrator (v3.1.0 - no bash fallback)..."

node "$ORCHESTRATOR_CLI" \
  --task-id "$TASK_ID" \
  --mode "$MODE" \
  --loop3-agents "$LOOP3_AGENTS" \
  --loop2-agents "$LOOP2_AGENTS" \
  --product-owner "$PRODUCT_OWNER" \
  --max-iterations "$MAX_ITERATIONS" \
  --success-criteria "enabled" \
  ${WORKSPACE:+--workspace "$WORKSPACE"} 2>&1

EXIT_CODE=$?

if [[ $EXIT_CODE -eq 0 ]]; then
  echo ""
  echo "✅ ORCHESTRATOR COMPLETED SUCCESSFULLY"
  exit 0
else
  echo ""
  echo "❌ ORCHESTRATOR FAILED (exit code: $EXIT_CODE)"
  exit $EXIT_CODE
fi
```

---

## Process Overview (TypeScript-First)

**4-Step Execution:**

1. **Store Context (TypeScript)** → `dist/coordination/store-task-context.js`
   - Stores task description, mode, max iterations
   - Unified swarm namespace (no duplication)
   - Fallback to bash skill if TypeScript unavailable
   - Fallback to direct Redis if skill unavailable

2. **Store Criteria (TypeScript)** → `dist/coordination/store-success-criteria.js`
   - Stores test suites and gate configuration
   - Test-driven validation metadata
   - Required for orchestrator gate checks
   - Fallback to bash skill if needed

3. **Select Agents (TypeScript)** → `cfn-agent-selection-with-fallback/dist/cli.cjs`
   - Classifies task into category (backend, frontend, infrastructure, etc.)
   - Returns Loop 3 implementers, Loop 2 validators, Product Owner
   - Guaranteed non-empty arrays (BUG #22 fix)
   - Automatic fallback to bash if TypeScript unavailable
   - Automatic fallback to defaults if classification fails

4. **Invoke Orchestrator (TypeScript-Only)** → `cfn-loop-orchestration/dist/cli/orchestrator-cli.js`
   - TypeScript orchestrator execution (REQUIRED - no bash fallback as of v3.1.0)
   - Build requirement enforced: `npm run build` must complete before execution
   - Clear error message if dist/ missing
   - Manages complete CFN Loop workflow:
     - Loop 3 spawning and execution
     - Test execution and gate checks
     - Loop 2 spawning and consensus
     - Product Owner decision parsing (TypeScript module)
     - Iteration management

---

## Skills Used (TypeScript-First)

### 1. Coordination (TypeScript)
**Location:** `dist/coordination/*.js`
**Scripts:**
- `store-task-context.js` - Stores task metadata
- `store-success-criteria.js` - Stores test configuration
- `coordination-wrapper.js` - Redis coordination layer

**Fallback:** `.claude/skills/cfn-redis-coordination/*.sh` (bash)

**Storage:**
- `swarm:${TASK_ID}:context` - Task description, mode, iterations
- Unified namespace (no cfn_loop:task duplication)

**Capabilities:**
- Agent lifecycle tracking
- Context injection
- Coordination signals
- Message broadcasting

---

### 2. Agent Selection (TypeScript)
**Location:** `.claude/skills/cfn-agent-selection-with-fallback/dist/cli.cjs`
**Compiled From:** `src/task-classifier.ts` + `src/agent-selector.ts`

**Fallback:** `select-agents.sh` (bash wrapper → TypeScript)

**Categories:**
- backend-api, fullstack, mobile, infrastructure
- security, frontend, database, performance
- default (fallback for unclassified tasks)

**Output (JSON):**
```json
{
  "loop3": ["backend-developer", "api-gateway-specialist"],
  "loop2": ["code-reviewer", "tester", "api-testing-specialist"],
  "product_owner": "product-owner",
  "category": "backend-api",
  "confidence": 0.92
}
```

**Guarantees:**
- Non-empty agent arrays (BUG #22 fix)
- Agent name validation against profiles
- Automatic fallback to defaults
- 85% faster than bash (compiled)

---

### 3. Orchestration (TypeScript-Only)
**Location:** `.claude/skills/cfn-loop-orchestration/dist/cli/orchestrator-cli.js`
**Compiled From:** `src/orchestrate.ts`

**NO FALLBACK** - TypeScript-only as of v3.1.0 (bash scripts archived)

**Execution Requirements:**
1. TypeScript build MUST complete: `npm run build`
2. dist/ directory MUST exist with compiled .js files
3. Clear error message if build missing (no silent fallback)

**Responsibilities:**
- Loop 3 agent spawning via CLI
- Test execution and pass rate calculation
- Gate checks (test-driven validation)
- Loop 2 validator spawning
- Consensus collection and averaging
- Product Owner decision parsing (TypeScript module: product-owner-decision.ts)
- Iteration management with feedback injection
- Coordination via TypeScript: coordination-wait.ts, coordination-signal.ts

**Performance:**
- 52% code reduction vs deprecated bash implementation
- Type-safe agent spawning with compile-time checks
- Enhanced error handling with structured error types
- Better test validation with TypeScript test parsers
- No shell injection vulnerabilities

**Exit Codes:**
- 0 = Success (PROCEED decision)
- 1 = Failure (ABORT or max iterations)
- 130 = User interrupt

---

## CFN Loop Workflow (Orchestrator Handles)

**After orchestrator is invoked, it executes:**

1. **Loop 3 (Implementation)**
   - Spawns implementer agents (from agent selection)
   - Agents create deliverables
   - Context automatically injected via Redis

2. **Test Execution**
   - Runs test suites from success criteria
   - Calculates pass rate across all tests
   - Validates deliverable metadata

3. **Gate Check (Test-Driven)**
   - IF pass rate ≥ threshold → Proceed to Loop 2
   - IF pass rate < threshold → Iterate Loop 3
   - Mode thresholds: MVP ≥0.70, Standard ≥0.95, Enterprise ≥0.98

4. **Loop 2 (Validation)**
   - Spawns validator agents
   - Reviews Loop 3 deliverables
   - Collects consensus scores

5. **Product Owner Decision**
   - Spawns Product Owner agent
   - Parses PROCEED/ITERATE/ABORT from output
   - Uses TypeScript decision parser or bash fallback

6. **Decision Execution**
   - PROCEED → Task complete (exit 0)
   - ITERATE → Wake agents for iteration N+1
   - ABORT → Exit with error (exit 1)

---

## Configuration

**Environment Variables:**
- `TASK_ID` - Unique task identifier
- `TASK_DESCRIPTION` - Task for agent selection
- `MODE` - CFN Loop mode (mvp/standard/enterprise)
- `MAX_ITERATIONS` - Max iteration cycles (default: 5)
- `EXPECTED_FILES` - Deliverable files for validation
- `PROJECT_ROOT` - Project root directory (default: .)
- `USE_TYPESCRIPT` - Enable TypeScript execution (default: true)
- `NODE_ENV` - Node.js environment (default: production)

**Redis Keys:**
- `swarm:${TASK_ID}:context` - Task context
- `swarm:${TASK_ID}:success-criteria` - Test configuration
- `swarm:${TASK_ID}:*:done` - Agent completion signals
- `swarm:${TASK_ID}:consensus:*` - Validator scores

---

## TypeScript vs Bash Execution

**TypeScript Mode (Preferred - Default):**
- ✅ 85% faster agent selection (compiled)
- ✅ 52% less orchestrator code
- ✅ Type-safe parameter validation
- ✅ Better error messages
- ✅ Enhanced test validation
- ✅ Unified coordination layer
- ⚠️ Requires Node.js
- ⚠️ Requires `npm run build`

**Bash Fallback Mode:**
- ✅ No dependencies (just bash + Redis)
- ✅ Identical functionality
- ✅ Proven production stability
- ⚠️ Slower execution
- ⚠️ Less type safety
- ⚠️ More code to maintain

**Automatic Fallback Triggers:**
1. `USE_TYPESCRIPT=false` environment variable
2. Node.js not available (`command -v node` fails)
3. TypeScript not compiled (dist/ files missing)
4. TypeScript execution error (catches and falls back)

---

## Rollback to Bash (If Needed)

**If TypeScript execution fails:**

```bash
# Option 1: Environment variable
export USE_TYPESCRIPT=false
# Coordinator will use bash scripts exclusively

# Option 2: Remove compiled files
rm -rf dist/
# Coordinator detects missing files and uses bash

# Option 3: Rebuild TypeScript
npm run build
# Restores TypeScript execution
```

**When to use bash fallback:**
- Node.js not installed in environment
- TypeScript build pipeline broken
- Debugging bash script changes
- Production environment without Node.js
- Docker container without Node.js

**Report TypeScript issues:**
- Document error in `docs/BUG_*.md`
- Include Node.js version: `node --version`
- Include npm version: `npm --version`
- Include error output from TypeScript execution

---

## Coordinator vs Orchestrator Responsibilities

**Coordinator (This Agent - TypeScript-First):**
- ✅ Store task context via TypeScript (fallback to bash)
- ✅ Store success criteria via TypeScript (fallback to bash)
- ✅ Select agents via TypeScript classification (fallback to bash)
- ✅ Invoke TypeScript orchestrator (fallback to bash wrapper)
- ✅ Return orchestrator output verbatim

**Orchestrator (TypeScript Skill):**
- ✅ Spawn Loop 3 agents via CLI
- ✅ Execute tests and calculate pass rates
- ✅ Check test-driven gates
- ✅ Spawn Loop 2 validators via CLI
- ✅ Collect consensus scores
- ✅ Spawn Product Owner for decision
- ✅ Parse PROCEED/ITERATE/ABORT
- ✅ Manage iteration cycles
- ✅ Inject feedback context

---

## Performance Comparison

**TypeScript Mode:**
- Agent selection: ~0.5s (compiled)
- Orchestrator startup: ~0.3s
- Total overhead: ~1s
- Memory: ~50MB (Node.js)

**Bash Mode:**
- Agent selection: ~3s (text processing)
- Orchestrator startup: ~0.1s
- Total overhead: ~3.5s
- Memory: ~5MB (bash)

**Recommendation:** Use TypeScript mode for production (3.5x faster).

---

**Coordinator Version:** 3.1.0 (TypeScript-First with Bash Fallback)
**Total Lines:** ~330 (was 290 before)
**Bash Script:** ~180 lines (was 130 before - added TypeScript integration)
**TypeScript Skills:** 3 primary skills with bash fallbacks
**Inline Logic:** Minimal (context storage + orchestrator invocation)
**Skills Used:** 3 production-tested TypeScript skills + bash fallbacks
**Maintainability:** High (delegates to modular TypeScript skills)
**Performance:** 3.5x faster than pure bash mode
**Reliability:** Automatic fallback ensures zero downtime
**Primary Change:** TypeScript-first execution with automatic bash fallback