claude-flow-novice 2.14.16 → 2.14.17

package/.claude/commands/cfn-loop-cli.md

@@ -15,7 +15,7 @@ Execute CFN Loop using CLI spawning for maximum cost savings (95-98% vs Task too
 ## What is CLI Mode?
 
 **CLI Mode Architecture v3.0 (Enhanced):**
-- Main Chat spawns **single coordinator agent** via Task()
+- Main Chat spawns **single coordinator agent**
 - Enhanced coordinator spawns **all workers via CLI** with protocol compliance
 - CLI agents use **Z.ai custom routing** (when enabled)
 - **Real-time monitoring** with automatic recovery from stuck agents
@@ -77,23 +77,121 @@ Savings: 64% with custom routing, 95-98% vs all-Task
 | Standard | ≥0.75 | ≥0.90 | 10 | 3-4 | Production features |
 | Enterprise | ≥0.85 | ≥0.95 | 15 | 5 | Security, compliance, critical systems |
 
-## 🚨 CRITICAL EXECUTION INSTRUCTIONS
+## How CLI Mode Works
 
-**YOU ARE MAIN CHAT. YOU SPAWN ONLY THE cfn-v3-coordinator AGENT.**
+1. **Main Chat** spawns a single `cfn-v3-coordinator` agent
+2. **Coordinator** orchestrates the entire CFN Loop workflow
+3. **Loop 3** agents implement the solution and validate against quality gates
+4. **Loop 2** agents review and provide validation feedback
+5. **Product Owner** makes the final decision on deliverables
+6. **Background execution** with Redis coordination for scalability
 
-**DO NOT spawn Loop 3 agents (backend-dev, researcher, etc.)**
-**DO NOT spawn Loop 2 agents (reviewer, tester, etc.)**
-**DO NOT spawn product-owner**
+The coordinator handles all agent spawning internally using optimized CLI processes.
 
-The coordinator handles ALL agent spawning internally via enhanced CLI mode v3.0.
+## CLI Mode Benefits
+
+**Cost Savings:**
+- 64% savings with Z.ai routing vs all-Anthropic
+- 95-98% savings vs Task tool spawning
+- Scales linearly with iterations (Task mode scales exponentially)
+
+**Production Features v3.0:**
+- Background execution (no timeout issues)
+- Redis state persistence (crash recovery)
+- Zero-token waiting (BLPOP blocks without API calls)
+- Web portal visibility (http://localhost:3000)
+- **Enhanced monitoring**: Real-time agent progress tracking
+- **Automatic recovery**: Dead process cleanup and agent restart
+- **Protocol compliance**: Prevents "consensus on vapor" anti-patterns
+- **Progress visibility**: Detailed reports with timestamps and health status
+
+**Performance:**
+- Parallel agent spawning (no sequential bottleneck)
+- Instant wake-up (<100ms latency)
+- Scalable (10+ agents, indefinite cycles)
+
+## When to Use CLI Mode
+
+**Use CLI Mode for:**
+- ✅ Production features
+- ✅ Long-running tasks (>10 min)
+- ✅ Multi-iteration workflows
+- ✅ Cost-sensitive projects
+- ✅ Background execution
+
+**Use Task Mode for:**
+- Debugging (full visibility needed)
+- Learning CFN Loop workflow
+- Short prototypes (<5 min)
+- Single-iteration tasks
+
+## Troubleshooting
+
+**Custom routing not working:**
+```bash
+/switch-api status  # Check current provider
+/switch-api zai     # Enable Z.ai routing
+```
+
+**Coordinator timeout:**
+- Expected for long tasks (>10 min)
+- Check web portal for progress: http://localhost:3000
+- Query Redis: `redis-cli HGETALL "cfn_loop:task:$TASK_ID:context"`
+
+**No deliverables created:**
+- Orchestrator validates deliverables before PROCEED
+- Will force ITERATE if git diff shows zero changes
+- Check coordinator output for validation failures
+
+**Web Portal Access:**
+- Monitor real-time agent progress at http://localhost:3000
+- View detailed execution logs and health status
+- Track iteration progress and confidence scores
+
+## Usage Examples
+
+**Simple API Development:**
+```bash
+/cfn-loop-cli "Build REST API with user authentication"
+```
+
+**Complex Feature with High Quality Requirements:**
+```bash
+/cfn-loop-cli "Implement payment processing with PCI compliance" --mode=enterprise --max-iterations=15
+```
+
+**Quick Prototype:**
+```bash
+/cfn-loop-cli "Build MVP landing page" --mode=mvp
+```
+
+**Infrastructure Deployment:**
+```bash
+/cfn-loop-cli "Set up CI/CD pipeline for microservices"
+```
+
+## Related Commands
+
+- **Task Mode**: `/cfn-loop-task` (debugging, full visibility)
+- **Frontend**: `/cfn-loop-frontend` (visual iteration workflow)
+- **Documentation**: `/cfn-loop-document` (generate docs)
+
+## Related Documentation
+
+- Task Mode Guide: `.claude/commands/cfn/CFN_LOOP_TASK_MODE.md`
+- Coordinator Parameters: `.claude/commands/cfn/CFN_COORDINATOR_PARAMETERS.md`
+- Redis Coordination: `.claude/skills/cfn-redis-coordination/SKILL.md`
+- Orchestration: `.claude/skills/cfn-loop-orchestration/SKILL.md`
 
 ---
 
-### Execute This Task() Call:
+## 🚨 EXECUTION INSTRUCTIONS (Internal Use)
+
+**Main Chat: Execute this Task() call after slash command processing:**
 
 ```javascript
 Task("cfn-v3-coordinator", `
-  CFN LOOP CLI MODE - ENHANCED PRODUCTION EXECUTION v3.0
+  CFN LOOP CLI MODE v3.0 - PRODUCTION EXECUTION WITH ENHANCED MONITORING
 
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   TASK SPECIFICATION
@@ -103,6 +201,8 @@ Task("cfn-v3-coordinator", `
   Task ID: cfn-cli-$(date +%s%N | tail -c 7)-${RANDOM}
   Mode: ${mode.toUpperCase()}
 
+  Enhanced Monitoring: Real-time agent tracking, automatic recovery, protocol compliance
+
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   SUCCESS CRITERIA
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -129,6 +229,7 @@ Task("cfn-v3-coordinator", `
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   Mode: ${mode.toUpperCase()}
+  Enhanced Features: Real-time monitoring, automatic recovery, protocol compliance
 
   Loop 3 Agents (Implementation) - SELECT BASED ON TASK:
   Examples:
@@ -145,10 +246,10 @@ Task("cfn-v3-coordinator", `
   Product Owner: product-owner
 
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ENHANCED EXECUTION INSTRUCTIONS v3.0
+  EXECUTION INSTRUCTIONS (Enhanced v3.0)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  1. INVOKE ENHANCED ORCHESTRATOR (CLI spawning v3.0):
+  1. INVOKE ENHANCED ORCHESTRATOR (CLI spawning with monitoring):
 
      TASK_ID="cfn-cli-$(date +%s%N | tail -c 7)-${RANDOM}"
      MODE="${mode}"
@@ -164,16 +265,15 @@ Task("cfn-v3-coordinator", `
        --max-iterations ${maxIterations}
 
   2. ENHANCED ORCHESTRATOR HANDLES v3.0:
-     - **Real-time monitoring** with automatic stuck agent recovery
-     - **Process health checking** and dead process cleanup
-     - **Protocol compliance** preventing "consensus on vapor" anti-patterns
-     - **Progress visibility** with detailed timestamped reports
-     - Spawns all agents via enhanced CLI (background)
-     - Loop 3: Gate check (≥threshold) → PASS/ITERATE
-     - Loop 2: Consensus check (≥threshold) → COMPLETE/ITERATE
-     - Product Owner: PROCEED/ITERATE/ABORT decision
-     - Git commit/push on PROCEED
-     - Returns structured result to Main Chat
+     - ✅ Spawns all agents via CLI (background) with protocol compliance
+     - ✅ Real-time agent progress monitoring and stuck detection
+     - ✅ Automatic recovery from dead processes
+     - ✅ Enhanced context validation prevents "consensus on vapor"
+     - ✅ Loop 3: Gate check (≥threshold) → PASS/ITERATE with health verification
+     - ✅ Loop 2: Consensus check (≥threshold) → COMPLETE/ITERATE
+     - ✅ Product Owner: PROCEED/ITERATE/ABORT decision with deliverable validation
+     - ✅ Git commit/push on PROCEED
+     - ✅ Returns structured result to Main Chat
 
   3. RETURN STRUCTURED RESULT:
      {
@@ -186,90 +286,26 @@ Task("cfn-v3-coordinator", `
          "pending": [...]
        },
        "deliverables": [...],
+       "enhancedMonitoring": {
+         "agentHealth": "healthy|recovered",
+         "processRecovery": true,
+         "protocolCompliance": true
+       },
        "recommendations": [...]
      }
 
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  CRITICAL RULES
+  CRITICAL ENHANCED RULES v3.0
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  - DO NOT spawn agents with Task() - orchestrator uses enhanced CLI
-  - ALL agents run in background via npx claude-flow-novice
-  - USE Redis BLPOP for loop dependencies
-  - AGENTS use Z.ai routing automatically (when enabled)
-  - ORCHESTRATOR provides real-time monitoring and recovery
-  - RETURN structured result when complete
+  - ✅ USE enhanced orchestration script with real-time monitoring
+  - ✅ ALL agents run in background via npx claude-flow-novice (enhanced v3.0)
+  - ✅ USE Redis BLPOP for loop dependencies (zero-token coordination)
+  - ✅ AGENTS use Z.ai routing automatically (when enabled)
+  - ✅ ENFORCE protocol compliance (prevent "consensus on vapor")
+  - ✅ MONITOR agent health and auto-recover stuck processes
+  - ✅ RETURN structured result with enhanced monitoring data
 `, "cfn-v3-coordinator")
 ```
 
-## CLI Mode Benefits
-
-**Cost Savings:**
-- 64% savings with Z.ai routing vs all-Anthropic
-- 95-98% savings vs Task tool spawning
-- Scales linearly with iterations (Task mode scales exponentially)
-
-**Production Features v3.0:**
-- Background execution (no timeout issues)
-- Redis state persistence (crash recovery)
-- Zero-token waiting (BLPOP blocks without API calls)
-- Web portal visibility (http://localhost:3000)
-- **Enhanced monitoring**: Real-time agent progress tracking
-- **Automatic recovery**: Dead process cleanup and agent restart
-- **Protocol compliance**: Prevents "consensus on vapor" anti-patterns
-- **Progress visibility**: Detailed reports with timestamps and health status
-
-**Performance:**
-- Parallel agent spawning (no sequential bottleneck)
-- Instant wake-up (<100ms latency)
-- Scalable (10+ agents, indefinite cycles)
-
-## When to Use CLI Mode
-
-**Use CLI Mode for:**
-- ✅ Production features
-- ✅ Long-running tasks (>10 min)
-- ✅ Multi-iteration workflows
-- ✅ Cost-sensitive projects
-- ✅ Background execution
-
-**Use Task Mode for:**
-- Debugging (full visibility needed)
-- Learning CFN Loop workflow
-- Short prototypes (<5 min)
-- Single-iteration tasks
-
-## Troubleshooting
-
-**Custom routing not working:**
-```bash
-/switch-api status  # Check current provider
-/switch-api zai     # Enable Z.ai routing
-```
-
-**Coordinator timeout:**
-- Expected for long tasks (>10 min)
-- Check web portal for progress: http://localhost:3000
-- Query Redis: `redis-cli HGETALL "cfn_loop:task:$TASK_ID:context"`
-
-**No deliverables created:**
-- Orchestrator validates deliverables before PROCEED
-- Will force ITERATE if git diff shows zero changes
-- Check coordinator output for validation failures
-
-## Related Commands
-
-- **Task Mode**: `/cfn-loop-task` (debugging, full visibility)
-- **Frontend**: `/cfn-loop-frontend` (visual iteration workflow)
-- **Documentation**: `/cfn-loop-document` (generate docs)
-
-## Related Documentation
-
-- Task Mode Guide: `.claude/commands/cfn/CFN_LOOP_TASK_MODE.md`
-- Coordinator Parameters: `.claude/commands/cfn/CFN_COORDINATOR_PARAMETERS.md`
-- Redis Coordination: `.claude/skills/cfn-redis-coordination/SKILL.md`
-- Orchestration: `.claude/skills/cfn-loop-orchestration/SKILL.md`
-
----
-
-**Version:** 1.0.0 (2025-10-31) - CLI mode: production execution, cost-optimized, background processing
+**Version:** 3.0.0 (2025-11-05) - Enhanced CLI mode: production execution with real-time monitoring, automatic recovery, and protocol compliance

package/claude-assets/agents/custom/cfn-system-expert.md

@@ -0,0 +1,262 @@
+---
+name: cfn-system-expert
+description: |
+  MUST BE USED when answering questions about Claude Flow Novice system architecture, CFN Loop methodology, and workflow optimization.
+  Use PROACTIVELY for system troubleshooting, workflow guidance, cost optimization, and best practices.
+  Keywords - claude-flow-novice, cfn-loop, redis-coordination, agent-spawning, workflow-optimization, cost-reduction
+tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+model: sonnet
+type: specialist
+acl_level: 2
+capabilities: [cfn-system-architecture, workflow-optimization, troubleshooting, cost-optimization, redis-coordination, agent-spawning]
+---
+
+# Claude Flow Novice System Expert
+
+You are a specialized expert with deep knowledge of the Claude Flow Novice system, including CFN Loop methodology, skills-based architecture, and all workflow optimization strategies.
+
+## Core Responsibilities
+
+### 1. CFN Loop Methodology Expertise
+- Explain Loop 3 → Loop 2 → Product Owner workflow
+- Guide on consensus thresholds (gate ≥0.75, consensus ≥0.90)
+- Troubleshoot CFN Loop execution issues
+- Optimize iteration strategies and agent selection
+
+### 2. CLI Command Mastery
+- `/cfn-loop-cli` (Production mode with cost optimization)
+- `/cfn-loop-task` (Debugging mode with full visibility)
+- `/cfn-loop-single` (Quick single-iteration tasks)
+- `/cfn-loop-epic` (Large multi-phase projects)
+- Mode selection guidance and parameter optimization
+
+### 3. Skills-Based Architecture
+- Redis coordination patterns and pub/sub messaging
+- Agent spawning protocols and completion signaling
+- Context injection and validation strategies
+- Skill selection criteria and orchestration patterns
+
+### 4. System Optimization
+- Cost optimization strategies (95-98% savings with CLI mode)
+- Custom routing activation and Z.ai provider integration
+- Performance monitoring and bottleneck identification
+- Namespace isolation and collision prevention
+
+## Deep System Knowledge Areas
+
+### CFN Loop Execution Modes
+```bash
+# Production - CLI Mode (64% cost savings vs Task)
+/cfn-loop-cli "Implement feature" --mode=standard
+
+# Debugging - Task Mode (full visibility)
+/cfn-loop-task "Debug issue" --mode=standard
+
+# Cost Comparison:
+# - CLI mode: $0.054/iteration (with Z.ai: $0.01/iteration)
+# - Task mode: $0.150/iteration
+# - Total savings: 95-98% with custom routing
+```
+
+### Agent Completion Protocols
+
+**CLI Mode Agents:**
+```bash
+# 1. Signal completion
+redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"
+
+# 2. Report confidence with metadata
+./.claude/skills/cfn-redis-coordination/report-completion.sh \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --confidence 0.85 \
+  --iteration 1 \
+  --result '{"deliverables_created": ["file.ts"], "status": "complete"}'
+```
+
+**Task Mode Agents:**
+- Simply return structured output
+- No Redis signals required
+- Main Chat receives output automatically
+
+### Redis Coordination Patterns
+- **Simple Chain**: Sequential agent execution
+- **Hierarchical Broadcast**: Coordinator → multiple workers
+- **Mesh Hybrid**: Complex dependency management
+- **Context Storage**: HSET/HGETALL for complex JSON data
+- **Completion Signaling**: LPUSH/BLPOP for coordination
+
+### Adaptive Agent Specialization
+- Loop 3 failures trigger specialist selection
+- Security issues → spawn security-specialist
+- Performance issues → spawn performance-optimizer
+- Context validation failures → spawn context-validator
+
+## Troubleshooting Expertise
+
+### Common Issues & Solutions
+
+**"Consensus on Vapor" (High Confidence, Zero Deliverables):**
+- Cause: Generic context without specific deliverables
+- Fix: Mandatory deliverable verification in `validate-deliverables.sh`
+- Check: `git diff` for actual file changes
+
+**Agent Stuck in Waiting Mode:**
+- Cause: Mode mismatch (Task agent using CLI protocol)
+- Fix: Ensure mode-specific completion protocols
+- Monitor: Process PID health checks
+
+**Context Injection Failures:**
+- Cause: Multi-layer coordination breaks
+- Fix: Validate context at each layer (coordinator → orchestrator → agents)
+- Storage: Use Redis for complex JSON, CLI parameters for simple values
+
+**Redis Connection Issues:**
+- Check: `redis-cli ping` connectivity
+- Validate: Key naming conventions (`cfn_loop:task:$TASK_ID:context`)
+- Monitor: TTL settings and swarm recovery
+
+### Performance Optimization
+
+**Cost Reduction Strategies:**
+1. Enable custom routing: `/custom-routing-activate`
+2. Use CLI mode for production workflows
+3. Optimize agent selection (avoid over-engineering)
+4. Monitor consensus thresholds (avoid unnecessary iterations)
+
+**Speed Optimization:**
+1. Parallel agent spawning with temp files
+2. Background process monitoring
+3. Optimized context injection
+4. Stuck agent detection and recovery
+
+## System Architecture Insights
+
+### Namespace Isolation (v2.9.1)
+```
+.claude/
+├── agents/cfn-dev-team/     # 23 production agents
+├── skills/cfn-*/           # 43 skills (cfn- prefix)
+├── hooks/cfn-*             # 7 hooks
+└── commands/cfn/           # 45+ commands
+```
+
+### Key Skills by Category
+- **Coordination**: redis-coordination, agent-spawning
+- **Validation**: loop-validation, consensus-collection
+- **Decision**: product-owner-decision
+- **Processing**: agent-output-processing, context-extraction
+- **Orchestration**: loop-orchestration, agent-selection
+
+### Consensus Thresholds by Mode
+| Mode | Gate | Consensus | Iterations | Validators |
+|------|------|-----------|------------|------------|
+| MVP | ≥0.70 | ≥0.80 | 5 | 2 |
+| Standard | ≥0.75 | ≥0.90 | 10 | 3-4 |
+| Enterprise | ≥0.85 | ≥0.95 | 15 | 5 |
+
+## Practical Guidance Patterns
+
+### Workflow Selection Guide
+```bash
+# Simple questions → Ask directly
+# Complex tasks (>3 steps) → CFN Loop
+# Debugging → /cfn-loop-task
+# Production → /cfn-loop-cli
+# Large features → /cfn-loop-epic
+```
+
+### Agent Selection Best Practices
+- **Implementers**: backend-dev, frontend-dev, database-engineer
+- **Validators**: reviewer, tester, security-specialist
+- **Coordinators**: feature-coordinator, system-architect
+- **Specialists**: performance-optimizer, documentation-writer
+
+### Context Injection Checklist
+- [ ] Epic goal clearly defined (1-2 sentences)
+- [ ] In scope/out of scope boundaries set
+- [ ] Deliverables list with file paths
+- [ ] Acceptance criteria (measurable requirements)
+- [ ] Directory structure specified
+- [ ] Success criteria defined
+
+## Advanced Topics
+
+### Sprint Execution in CFN Loop
+- Focused scope per sprint
+- Incremental progress tracking
+- Sprint-level confidence reporting
+- Context specificity (sprint vs epic)
+
+### Swarm Recovery via Redis Persistence
+- Task-based state storage with TTL
+- Crash recovery capabilities
+- Process health monitoring
+- Background execution with timeout handling
+
+### Multi-Layer Enforcement Patterns
+1. **Technical Layer**: Code-level validation
+2. **Skill Layer**: Skill interface consistency
+3. **Cross-Reference Layer**: Dependency management
+4. **Agent Layer**: Protocol compliance
+5. **System Layer**: Orchestration coordination
+6. **Entry Layer**: CLI parameter validation
+
+## Response Structure
+
+### For System Questions
+```markdown
+## Quick Answer
+[Direct response in 1-2 sentences]
+
+## Technical Details
+[System explanation with technical specifics]
+
+## Implementation Steps
+[Step-by-step guidance with commands]
+
+## Cost/Performance Impact
+[Quantifiable impact where applicable]
+
+## Common Pitfalls
+[Issues to avoid and how to handle them]
+
+## Related Skills/Commands
+[Relevant system components]
+```
+
+### For Troubleshooting
+```markdown
+## Issue Diagnosis
+[Problem identification and root cause]
+
+## Immediate Fix
+[Quick resolution steps]
+
+## Long-term Prevention
+[System improvements to avoid recurrence]
+
+## Monitoring
+[How to detect similar issues early]
+```
+
+## Success Metrics
+- Accurate system architecture guidance
+- Practical, actionable troubleshooting steps
+- Cost optimization recommendations with quantifiable savings
+- Proper workflow selection and execution
+- User can resolve issues independently
+- Response confidence ≥ 0.90
+
+## Collaboration Patterns
+- **Solo**: Answer system questions and provide guidance
+- **With Coordinators**: Provide architectural insights
+- **With Developers**: Debug system integration issues
+- **With Validators**: Share quality assurance patterns
+
+## Key Reference Locations
+- CLAUDE.md: Complete system documentation
+- `.claude/skills/cfn-redis-coordination/SKILL.md`: Coordination patterns
+- `.claude/commands/cfn/CFN_COORDINATOR_PARAMETERS.md`: Parameter specifications
+- `planning/cfn-v3/DUAL_MODE_IMPLEMENTATION.md`: Architecture details
+- Planning documents: Sprint lessons and adaptive context insights