claude-flow-novice 2.14.37 → 2.15.1

package/claude-assets/agents/README-AGENT_LIFECYCLE.md.backup_before_replace

@@ -1,522 +0,0 @@
-# Agent Lifecycle Documentation
-
-**Version:** 2.0 (Post-Waiting Mode Removal)
-**Last Updated:** 2025-10-21
-**Status:** Current Standard
-
----
-
-## Overview
-
-This document clarifies the complete lifecycle of agents in the CFN Loop system, removing ambiguity about exit vs. waiting patterns.
-
-**Core Principle:** Agents are **stateless, single-execution workers** that exit cleanly after completing their work and reporting results.
-
----
-
-## Lifecycle States
-
-### State 1: Spawned
-**Duration:** Instantaneous
-**Who:** Orchestrator via CLI (`npx cfn-spawn agent <type>`)
-**Agent State:** Process starting, loading context
-
-**Actions:**
-- Agent process created
-- Context injected via CLI parameters
-- Tools initialized
-- Task description received
-
-### State 2: Executing
-**Duration:** Variable (15 seconds - 60 minutes depending on agent type)
-**Who:** Agent (autonomous)
-**Agent State:** Working on assigned task
-
-**Actions:**
-- Read task specifications
-- Execute work (code, review, validation, decision)
-- Use tools (Read, Write, Edit, Bash, etc.)
-- Build results
-
-### State 3: Reporting
-**Duration:** 1-5 seconds
-**Who:** Agent (mandatory protocol)
-**Agent State:** Completing execution
-
-**Actions (in order):**
-1. **Signal completion:**
-   ```bash
-   redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"
-   ```
-
-2. **Report confidence:**
-   ```bash
-   ./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
-
-**After reporting, exit cleanly. Do NOT enter waiting mode.**
-
-**Why This Matters:**
-- Orchestrator collects confidence/consensus scores from Redis
-- Enables adaptive agent specialization for next iteration
-- Prevents orchestrator blocking on wait $PID
-- Coordinator spawns appropriate specialist based on feedback type
-
-     --task-id "$TASK_ID" \
-     --agent-id "$AGENT_ID" \
-     --confidence [0.0-1.0] \
-     --iteration $ITERATION
-   ```
-
-3. **Store results (if applicable):**
-   ```bash
-   redis-cli setex "swarm:${TASK_ID}:${AGENT_ID}:result" 86400 "$RESULT_JSON"
-   ```
-
-### State 4: Exiting
-**Duration:** Instantaneous
-**Who:** Agent (natural process termination)
-**Agent State:** Process terminating
-
-**Actions:**
-- Clean exit (exit code 0)
-- Process terminates
-- Resources released
-- ~~NO waiting mode~~ ❌ (removed)
-- ~~NO wake signal needed~~ ❌ (removed)
-
----
-
-## CFN Loop Protocol (Complete)
-
-### For Loop 3 Implementers (coder, backend-dev, etc.)
-
-```markdown
-## CFN Loop Redis Completion Protocol
-
-When participating in CFN Loop workflows, agents MUST follow this protocol:
-
-### Step 1: Complete Work
-Execute assigned task (code implementation, feature development, bug fixing)
-
-### Step 2: Signal Completion
-```bash
-redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"
-```
-
-### Step 3: Report Confidence Score
-```bash
-./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
-
-**After reporting, exit cleanly. Do NOT enter waiting mode.**
-
-**Why This Matters:**
-- Orchestrator collects confidence/consensus scores from Redis
-- Enables adaptive agent specialization for next iteration
-- Prevents orchestrator blocking on wait $PID
-- Coordinator spawns appropriate specialist based on feedback type
-
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --confidence [0.0-1.0] \
-  --iteration 1
-```
-
-Confidence score guidelines:
-- 1.0: Perfect implementation, all requirements met, no issues
-- 0.9-0.99: Excellent, minor refinements possible
-- 0.75-0.89: Good, gate threshold met, ready for validation
-- 0.5-0.74: Below gate, needs iteration
-- 0.0-0.49: Significant issues, requires major rework
-
-### Step 4: Exit Cleanly
-Agent work is complete. Exit cleanly to allow orchestrator to proceed.
-
-**Note:** If another iteration is needed, orchestrator will spawn a fresh agent
-(possibly a different specialist based on feedback). This enables adaptive
-agent specialization per PATTERN-022.
-```
-
-### For Loop 2 Validators (reviewer, tester, security-specialist, etc.)
-
-```markdown
-## CFN Loop Redis Completion Protocol
-
-### Step 1: Wait for Gate Pass Signal
-```bash
-# Wait for Loop 3 to pass gate threshold
-redis-cli blpop "swarm:${TASK_ID}:gate-passed" 0
-```
-
-### Step 2: Retrieve Loop 3 Results
-```bash
-# Get agent outputs and confidence scores from Redis
-redis-cli get "swarm:${TASK_ID}:coder-1:result"
-redis-cli get "swarm:${TASK_ID}:coder-1:confidence"
-```
-
-### Step 3: Perform Validation
-Execute validation task (code review, security audit, testing)
-
-### Step 4: Signal Completion
-```bash
-redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"
-```
-
-### Step 5: Report Consensus Score
-```bash
-./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
-
-**After reporting, exit cleanly. Do NOT enter waiting mode.**
-
-**Why This Matters:**
-- Orchestrator collects confidence/consensus scores from Redis
-- Enables adaptive agent specialization for next iteration
-- Prevents orchestrator blocking on wait $PID
-- Coordinator spawns appropriate specialist based on feedback type
-
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --confidence [0.0-1.0] \
-  --iteration 1
-```
-
-Consensus score guidelines:
-- 1.0: Perfect quality, no issues found
-- 0.9-0.99: Excellent, consensus threshold typically met
-- 0.75-0.89: Good, minor issues found
-- 0.5-0.74: Below consensus, needs iteration
-- 0.0-0.49: Significant issues, requires rework
-
-### Step 6: Exit Cleanly
-Validation complete. Exit cleanly to allow orchestrator to calculate consensus.
-```
-
-### For Product Owner
-
-```markdown
-## CFN Loop Product Owner Protocol
-
-### Step 1: Wait for Consensus Completion
-```bash
-# Wait for Loop 2 to complete consensus validation
-redis-cli blpop "swarm:${TASK_ID}:consensus-complete" 0
-```
-
-### Step 2: Retrieve All Context
-```bash
-# Get Loop 2 consensus, feedback, acceptance criteria
-redis-cli get "swarm:${TASK_ID}:loop2:consensus"
-redis-cli lrange "swarm:${TASK_ID}:loop2:feedback" 0 -1
-redis-cli get "swarm:${TASK_ID}:success-criteria"
-```
-
-### Step 3: Make Strategic Decision
-Analyze consensus, feedback, and business requirements.
-
-Output one of:
-- **PROCEED:** Task complete, meets acceptance criteria
-- **ITERATE:** Needs another iteration (provide specific feedback)
-- **ABORT:** Out of scope or max iterations reached
-
-### Step 4: Report Decision
-```bash
-redis-cli lpush "swarm:${TASK_ID}:product-owner:decision" "$DECISION_JSON"
-```
-
-### Step 5: Exit Cleanly
-Decision made. Exit to allow orchestrator to proceed with final actions.
-```
-
----
-
-## Orchestrator Responsibilities
-
-### Agent Spawning
-```bash
-# Spawn agent via CLI
-npx cfn-spawn agent <agent-type> \
-  --task-id "$TASK_ID" \
-  --iteration "$ITERATION" \
-  --context "$CONTEXT_JSON" &
-
-AGENT_PID=$!
-```
-
-### Agent Monitoring
-```bash
-# Wait for agent to complete and exit naturally
-wait $AGENT_PID
-EXIT_CODE=$?
-
-# Check completion signal
-DONE_SIGNAL=$(redis-cli lpop "swarm:${TASK_ID}:${AGENT_ID}:done")
-
-# Retrieve confidence
-CONFIDENCE=$(redis-cli get "swarm:${TASK_ID}:${AGENT_ID}:confidence")
-```
-
-### No Wake Calls Needed
-❌ **Removed:** `invoke-waiting-mode.sh wake` calls
-✅ **Current:** Agents exit, orchestrator spawns fresh agents for next iteration
-
----
-
-## Iteration Pattern
-
-### Single Iteration (Typical)
-```
-1. Orchestrator spawns Loop 3 agents
-2. Loop 3 agents work → report confidence → EXIT
-3. Orchestrator checks gate threshold
-4. If PASS: Orchestrator spawns Loop 2 agents
-5. Loop 2 agents validate → report consensus → EXIT
-6. Orchestrator checks consensus threshold
-7. If PASS: Orchestrator spawns Product Owner
-8. Product Owner decides → EXIT
-9. Task complete
-```
-
-### Multi-Iteration (If Gate/Consensus Fails)
-```
-1. Orchestrator spawns Loop 3 agents (iteration 1)
-2. Loop 3 agents work → report confidence → EXIT
-3. Gate check FAILS (confidence < 0.75)
-4. Orchestrator spawns NEW Loop 3 agents (iteration 2) ← Fresh agents!
-5. New agents work → report confidence → EXIT
-6. Gate check PASSES
-7. Continue to Loop 2...
-```
-
-**Key Point:** Each iteration spawns **fresh agents**, enabling adaptive specialization:
-- Iteration 1: coder
-- Iteration 2: rust-developer (if feedback mentions Rust)
-- Iteration 3: backend-dev (if feedback mentions API)
-
----
-
-## Anti-Patterns (Forbidden)
-
-### ❌ Anti-Pattern 1: Waiting Mode
-```bash
-# WRONG - DO NOT USE:
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID"
-```
-
-**Why forbidden:**
-- Blocks orchestrator indefinitely
-- Creates process zombies
-- Prevents adaptive specialization
-- Requires manual wake calls (complexity)
-
-### ❌ Anti-Pattern 2: Fork/Resume Pattern
-```bash
-# WRONG - DO NOT USE:
-redis-cli get "swarm:${TASK_ID}:${AGENT}:fork-id"
-npx cfn-fork resume --fork-id "$FORK_ID"
-```
-
-**Why forbidden:**
-- Adds complexity (conversation state management)
-- Not needed (fresh agents work better)
-- Harder to debug (stateful resume)
-
-### ❌ Anti-Pattern 3: Manual Agent Spawning
-```bash
-# WRONG - DO NOT USE in CFN Loop:
-Task("coder", "implement feature")
-```
-
-**Why forbidden:**
-- Bypasses CFN Loop protocol
-- No confidence reporting
-- No Redis coordination
-- Breaks orchestrator flow
-
----
-
-## Correct Patterns (Recommended)
-
-### ✅ Pattern 1: Clean Exit After Reporting
-```bash
-# Agent code (end of execution):
-
-# Step 1: Signal done
-redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"
-
-# Step 2: Report confidence
-./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
-
-**After reporting, exit cleanly. Do NOT enter waiting mode.**
-
-**Why This Matters:**
-- Orchestrator collects confidence/consensus scores from Redis
-- Enables adaptive agent specialization for next iteration
-- Prevents orchestrator blocking on wait $PID
-- Coordinator spawns appropriate specialist based on feedback type
-
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --confidence 0.95 \
-  --iteration 1
-
-# Step 3: Exit cleanly
-exit 0
-```
-
-### ✅ Pattern 2: Orchestrator Wait Pattern
-```bash
-# Orchestrator code:
-
-# Spawn agent in background
-npx cfn-spawn agent coder \
-  --task-id "$TASK_ID" \
-  --context "$CONTEXT" &
-AGENT_PID=$!
-
-# Wait for agent to complete
-wait $AGENT_PID
-EXIT_CODE=$?
-
-# Retrieve results from Redis (agent already exited)
-CONFIDENCE=$(redis-cli get "swarm:${TASK_ID}:coder-1:confidence")
-```
-
-### ✅ Pattern 3: Adaptive Specialization
-```bash
-# Orchestrator iteration logic:
-
-if [ "$GATE_PASSED" = "false" ]; then
-  # Analyze feedback to select specialist
-  if [[ "$FEEDBACK" =~ "security" ]]; then
-    SPECIALIST="security-specialist"
-  elif [[ "$FEEDBACK" =~ "performance" ]]; then
-    SPECIALIST="perf-analyzer"
-  else
-    SPECIALIST="$ORIGINAL_AGENT"  # Retry with same type
-  fi
-
-  # Spawn fresh specialist (not resume old agent)
-  npx cfn-spawn agent "$SPECIALIST" \
-    --task-id "$TASK_ID" \
-    --iteration $((ITERATION + 1)) \
-    --feedback "$FEEDBACK" &
-fi
-```
-
----
-
-## Timeout Handling
-
-### Agent-Level Timeouts
-Agents have role-based timeouts:
-- **Implementers:** 60 minutes (coder, backend-dev)
-- **Validators:** 30 minutes (reviewer, tester)
-- **Product Owner:** 15 minutes (strategic decision)
-- **Researchers:** 120 minutes (deep analysis)
-
-### Timeout Behavior
-```bash
-# If agent times out:
-# 1. Process killed by orchestrator
-# 2. Agent marked as failed
-# 3. No confidence reported (defaults to 0.0)
-# 4. Orchestrator spawns replacement agent
-```
-
----
-
-## Error Handling
-
-### Agent Failure Scenarios
-
-**1. Exit Code Non-Zero:**
-```bash
-wait $AGENT_PID
-EXIT_CODE=$?
-
-if [ "$EXIT_CODE" -ne 0 ]; then
-  # Agent failed - log error, spawn replacement
-  CONFIDENCE=0.0
-fi
-```
-
-**2. No Completion Signal:**
-```bash
-DONE_SIGNAL=$(redis-cli lpop "swarm:${TASK_ID}:${AGENT_ID}:done")
-
-if [ -z "$DONE_SIGNAL" ]; then
-  # Agent didn't signal completion - treat as failure
-  CONFIDENCE=0.0
-fi
-```
-
-**3. Missing Confidence:**
-```bash
-CONFIDENCE=$(redis-cli get "swarm:${TASK_ID}:${AGENT_ID}:confidence")
-
-if [ -z "$CONFIDENCE" ] || [ "$CONFIDENCE" = "(nil)" ]; then
-  # No confidence reported - default to 0.0
-  CONFIDENCE=0.0
-fi
-```
-
----
-
-## Redis Key Conventions
-
-### Agent Completion Keys
-```
-swarm:{TASK_ID}:{AGENT_ID}:done          → "complete" (signal)
-swarm:{TASK_ID}:{AGENT_ID}:confidence    → "0.95" (score)
-swarm:{TASK_ID}:{AGENT_ID}:result        → JSON (output)
-```
-
-### Coordination Keys
-```
-swarm:{TASK_ID}:gate-passed              → "1" (Loop 3 → Loop 2 signal)
-swarm:{TASK_ID}:consensus-complete       → "1" (Loop 2 → PO signal)
-swarm:{TASK_ID}:product-owner:decision   → JSON (PO decision)
-```
-
-### Metrics Keys
-```
-swarm:{TASK_ID}:metrics:loop3_consensus  → List of JSON metrics
-swarm:{TASK_ID}:metrics:loop2_consensus  → List of JSON metrics
-swarm:{TASK_ID}:metrics:iteration_start  → List of timestamps
-```
-
----
-
-## Summary
-
-**Agent Lifecycle (4 States):**
-1. **Spawned** - Process starts, context loaded
-2. **Executing** - Agent works autonomously
-3. **Reporting** - Signal completion, report confidence
-4. **Exiting** - Clean exit (exit code 0)
-
-**Key Changes from v1.0:**
-- ❌ Removed: Waiting mode (Step 4)
-- ❌ Removed: Wake calls from orchestrator
-- ❌ Removed: Fork/resume pattern
-- ✅ Added: Clean exit after reporting
-- ✅ Added: Adaptive agent specialization
-- ✅ Added: Fresh agents per iteration
-
-**Benefits:**
-- Simpler orchestrator (no wake logic)
-- Stateless agents (easier debugging)
-- Adaptive specialization (better results)
-- No process zombies (clean resource management)
-
-**Next Steps:**
-- See P4: Product Owner structured JSON output
-- See P5: Coordinator simplification (780 → 200 lines)
-- See P6: Unified agent spawning patterns
-
----
-
-**Version History:**
-- v1.0: Original with waiting mode
-- v2.0 (2025-10-21): Waiting mode removed, PATTERN-022 compliant

package/claude-assets/agents/cfn-dev-team/test-agent.md

@@ -1,141 +0,0 @@
-# Epic Creator Deletion Issue - Complete Summary
-
-**Date:** 2025-11-03
-**Status:** RESOLVED
-**Versions:** v2.14.5 (epic-creator added), v2.14.6 (init bug fixed)
-
----
-
-## Problem
-
-The `epic-creator.md` coordinator agent kept getting deleted from `.claude/agents/cfn-dev-team/coordinators/` after being created and committed.
-
----
-
-## Root Cause
-
-**Every `npx claude-flow-novice` command triggered `cfn-init`**, which overwrote the entire `.claude/agents/cfn-dev-team/` directory from the npm package.
-
-### Why It Happened
-
-1. `package.json` has `"postinstall": "node scripts/init-project.js"`
-2. Running `npx claude-flow-novice agent backend-dev` triggers postinstall
-3. `init-project.js` ran `cfn-init` unconditionally
-4. cfn-init copied package version of cfn-dev-team/, overwriting local files
-5. epic-creator.md (and other local customizations) got deleted
-
-### Trigger Pattern
-
-```bash
-# Each of these triggered cfn-init:
-npx claude-flow-novice agent backend-dev
-npx claude-flow-novice agent reviewer
-npx claude-flow-novice agent epic-creator
-
-# In test sessions running hundreds of npx commands:
-# = hundreds of cfn-init runs = constant file deletion
-```
-
----
-
-## Solution
-
-### Phase 1: Add epic-creator to Package (v2.14.5)
-
-```bash
-# Copy epic-creator to package assets
-cp .claude/agents/cfn-dev-team/coordinators/epic-creator.md \
-   claude-assets/agents/cfn-dev-team/coordinators/
-
-# Publish to npm
-npm version patch
-npm publish
-```
-
-**Result:** Users can now get epic-creator via normal installation.
-
----
-
-### Phase 2: Fix Init-on-Every-NPX Bug (v2.14.6)
-
-**Changes to `scripts/init-project.js`:**
-
-```javascript
-async function initializeCfnProject() {
-  // Skip initialization if already initialized
-  const markerPath = '.claude/.cfn-initialized';
-  if (fs.existsSync(markerPath)) {
-    // Silently skip - already initialized
-    return;
-  }
-
-  // ... existing init logic ...
-
-  // Create marker file after successful init
-  fs.writeFileSync('.claude/.cfn-initialized', new Date().toISOString());
-}
-```
-
-**How It Works:**
-1. First `npx claude-flow-novice` command → runs full init → creates marker
-2. Subsequent commands → sees marker → skips init → files preserved
-3. Force reinit: `rm .claude/.cfn-initialized && npx cfn-init`
-
----
-
-## Epic Creator Agent
-
-**Purpose:** Transforms natural language epic descriptions into structured JSON configs for CFN Loop execution.
-
-**Three Personas:**
-- **CTO:** Technical architecture, dependencies, risk assessment
-- **Product Owner:** Value prioritization, scope boundaries
-- **Project Manager:** Phase decomposition, deliverables, estimates
-
-**Key Features:**
-- Decomposes epics into 3-7 focused phases
-- Selects appropriate Loop 3/Loop 2 agents per phase
-- Defines concrete deliverables with file paths
-- Sets mode-appropriate thresholds (MVP/Standard/Enterprise)
-- Validates configuration completeness
-
-**Location:** `.claude/agents/cfn-dev-team/coordinators/epic-creator.md` (3.7KB)
-
-**Usage:**
-```bash
-npx claude-flow-novice agent epic-creator \
-  --prompt "Create epic for user authentication system with JWT and OAuth2"
-```
-
----
-
-## Published Versions
-
-**v2.14.5** (Published 2025-11-03)
-- Includes epic-creator in package distribution
-- Users get it automatically on install
-
-**v2.14.6** (Published 2025-11-03)
-- Fixes init-on-every-npx bug
-- Preserves local customizations
-- Faster CLI performance
-
-**Install Latest:**
-```bash
-npm install claude-flow-novice@latest
-npx cfn-init  # Only runs once, creates marker
-```
-
----
-
-## Current Status
-
-**RESOLVED:** Both epic-creator availability and init-on-every-npx bug are fixed.
-
-**Users on v2.14.6+ will:**
-- Get epic-creator automatically
-- Experience fast npx startup
-- Keep local customizations safe
-- Have stable cfn-dev-team directory
-
-**No further action required.**

package/claude-assets/agents/marketing_hybrid/cost_tracker.md

@@ -1,13 +0,0 @@
-# Cost Tracking Agent
-## Role
-Monitor Z.ai worker costs during 48-hour pilot
-
-## Responsibilities
-- Use track-zai-costs.sh script
-- Monitor API calls
-- Generate cost report
-- Alert if costs exceed $5
-
-## Deliverables
-- cost_tracking.csv
-- cost_summary.json

package/claude-assets/agents/marketing_hybrid/docker_deployer.md

@@ -1,13 +0,0 @@
-# Docker Deployer Agent
-## Role
-Deploy marketing coordinator using docker-compose.hybrid.yml
-
-## Responsibilities
-- Load docker-compose configuration
-- Configure MARKETING_COORDINATOR_API_KEY
-- Start containers
-- Validate deployment status
-
-## Deliverables
-- deployment_log.txt
-- container_status.json

package/claude-assets/agents/marketing_hybrid/zai_worker_spawner.md

@@ -1,13 +0,0 @@
-# Z.ai Worker Spawner Agent
-## Role
-Spawn 3 Z.ai workers for marketing pilot
-
-## Responsibilities
-- Use spawn-worker.sh script
-- Configure Z.ai API credentials
-- Validate worker startup
-- Track worker initialization
-
-## Deliverables
-- workers_log.txt
-- worker_status.json