claude-flow-novice 2.10.8 → 2.11.0

package/.claude/commands/README.md

@@ -0,0 +1,157 @@
+# CLAUDE.md Slash Command System
+
+## 🎯 Simple, Focused CLAUDE.md Generation
+
+A lightweight slash command system for generating CLAUDE.md files with NPX protection.
+
+## 📋 Features
+
+### ✅ **Simple Slash Command**
+```bash
+/claude-md                    # Generate CLAUDE.md for current project
+/claude-md --preview         # Show what would be generated
+/claude-md --force           # Overwrite without confirmation
+/claude-md --detect          # Auto-detect project and show recommendations
+/claude-md --no-backup       # Skip backup creation
+```
+
+### 🛡️ **NPX Protection System**
+- **Problem**: NPX installs overwrite customized CLAUDE.md files
+- **Solution**: Generate `claude-copy-to-main.md` when existing CLAUDE.md detected
+- **Benefit**: User customizations are never lost
+
+### 🔄 **Integration Flow**
+
+**Normal Usage (Slash Command):**
+1. User runs `/claude-md`
+2. System detects project type
+3. Generates appropriate CLAUDE.md
+4. Creates backup if file exists
+
+**NPX Install Protection:**
+1. NPX installs claude-flow-novice
+2. `postinstall` script runs
+3. Detects existing CLAUDE.md
+4. Creates `claude-copy-to-main.md` instead
+5. User manually merges desired changes
+
+## 🏗️ Architecture
+
+### **Files:**
+- `claude-md.js` - Core slash command implementation
+- `register-claude-md.js` - Slash command registration
+- `../npx/claude-md-protection.js` - NPX protection logic
+- `../../scripts/post-install-claude-md.js` - Post-install hook
+
+### **Integration Points:**
+- **Existing Generator**: Uses `../language/claude-md-generator.js`
+- **Language Detection**: Uses `../language/language-detector.js`
+- **Preferences**: Reads `.claude-flow-novice/preferences/generation.json`
+- **Package.json**: `postinstall` script triggers protection
+
+## 🎮 Usage Examples
+
+### **Basic Generation:**
+```bash
+# Generate CLAUDE.md for current project
+/claude-md
+
+# Output:
+# 🚀 Generating CLAUDE.md...
+# ✅ CLAUDE.md generated successfully
+```
+
+### **Preview Mode:**
+```bash
+# See what would be generated
+/claude-md --preview
+
+# Output:
+# 📄 CLAUDE.md Preview:
+# ══════════════════════════════════════════════════
+# # Claude Code Configuration - JavaScript Project
+# ...
+# ══════════════════════════════════════════════════
+# 📊 Total length: 2,847 characters
+```
+
+### **NPX Protection:**
+```bash
+# When NPX detects existing CLAUDE.md
+npm install claude-flow-novice
+
+# Output:
+# 🛡️ NPX Protection Activated
+# 📄 Generated: claude-copy-to-main.md
+# 💡 Your existing CLAUDE.md is protected from overwrite
+# 🔄 Review and merge changes manually as needed
+```
+
+## 🧠 Smart Detection
+
+### **Project Type Detection:**
+- Analyzes `package.json`, file patterns, and directory structure
+- Detects frameworks (React, Express, Django, etc.)
+- Suggests appropriate CLAUDE.md configurations
+
+### **Confidence Levels:**
+- **High (>70%)**: Automatic generation recommended
+- **Medium (30-70%)**: Generate with user confirmation
+- **Low (<30%)**: Manual review suggested
+
+## 🔧 Configuration
+
+### **Generation Preferences:**
+`.claude-flow-novice/preferences/generation.json`:
+```json
+{
+  "autoGenerate": true,
+  "includeFrameworkSpecific": true,
+  "includeBestPractices": true,
+  "backupExisting": true,
+  "confidenceThreshold": 0.3
+}
+```
+
+### **NPX Detection:**
+- Environment variables (`NPX_INSTALL=true`)
+- Temporary directory patterns (`/.npm/_npx/`)
+- Package.json analysis (fresh installs)
+
+## 🎯 Design Principles
+
+### **Keep It Simple:**
+- Single focused command
+- Minimal configuration
+- Clear user feedback
+- No feature bloat
+
+### **Protect User Work:**
+- Never overwrite without permission
+- Always offer backup options
+- Provide clear merge instructions
+- Preserve customizations
+
+### **Smart Defaults:**
+- Auto-detect project type
+- Use appropriate templates
+- Respect user preferences
+- Fail safely
+
+## 🚀 Future Enhancements
+
+### **Potential Improvements (If Needed):**
+- Interactive confirmation prompts
+- Template customization options
+- Multi-project detection
+- Advanced merge assistance
+
+### **Not Planned (Avoiding Bloat):**
+- SQLite analysis integration
+- Multi-file scaffolding
+- Complex workflow automation
+- Enterprise features
+
+---
+
+**Simple, focused, and protective - exactly what CLAUDE.md generation should be!** 🎯

package/.claude/hooks/cfn-invoke-post-edit.sh

@@ -14,7 +14,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CONFIG_FILE="$SCRIPT_DIR/post-edit.config.json"
+CONFIG_FILE="$SCRIPT_DIR/cfn-post-edit.config.json"
 
 # Parse arguments
 FILE_PATH=""

package/.claude/hooks/cfn-invoke-pre-edit.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+
+# Pre-Edit Backup Hook Wrapper
+# Creates backup before file modifications in agent workflows
+#
+# Usage: .claude/hooks/cfn-invoke-pre-edit.sh FILE_PATH --agent-id AGENT_ID
+#
+# Arguments:
+#   FILE_PATH   - Absolute path to file about to be edited
+#   --agent-id  - Unique identifier for the agent performing the edit
+#
+# Returns:
+#   Backup directory path on success
+#   Exit code 1 on failure
+#
+# Example:
+#   BACKUP_PATH=$(./.claude/hooks/cfn-invoke-pre-edit.sh "/path/to/file.txt" --agent-id "backend-dev-1")
+
+set -euo pipefail
+
+# === Parse Arguments ===
+
+FILE_PATH=""
+AGENT_ID=""
+
+# First positional argument is file path
+if [[ -n "${1:-}" ]] && [[ "$1" != --* ]]; then
+    FILE_PATH="$1"
+    shift
+fi
+
+# Parse remaining named arguments
+while [[ "$#" -gt 0 ]]; do
+    case $1 in
+        --agent-id)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --agent-id requires a value" >&2
+                exit 1
+            fi
+            AGENT_ID="$2"
+            shift 2
+            ;;
+        *)
+            echo "Error: Unknown argument: $1" >&2
+            echo "Usage: cfn-invoke-pre-edit.sh FILE_PATH --agent-id AGENT_ID" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# === Validate Inputs ===
+
+if [[ -z "$FILE_PATH" ]]; then
+    echo "Error: No file path provided" >&2
+    echo "Usage: cfn-invoke-pre-edit.sh FILE_PATH --agent-id AGENT_ID" >&2
+    exit 1
+fi
+
+if [[ -z "$AGENT_ID" ]]; then
+    echo "Error: No agent ID provided" >&2
+    echo "Usage: cfn-invoke-pre-edit.sh FILE_PATH --agent-id AGENT_ID" >&2
+    exit 1
+fi
+
+if [[ ! -f "$FILE_PATH" ]]; then
+    echo "Error: File does not exist: $FILE_PATH" >&2
+    exit 1
+fi
+
+# === Execute Pre-Edit Backup ===
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BACKUP_SCRIPT="${SCRIPT_DIR}/../skills/pre-edit-backup/backup.sh"
+
+if [[ ! -f "$BACKUP_SCRIPT" ]]; then
+    echo "Error: Backup script not found: $BACKUP_SCRIPT" >&2
+    exit 1
+fi
+
+# Execute backup and capture output
+if ! BACKUP_DIR=$("$BACKUP_SCRIPT" "$FILE_PATH" "$AGENT_ID" 2>&1); then
+    echo "Error: Backup failed: $BACKUP_DIR" >&2
+    exit 1
+fi
+
+# Return backup directory path
+echo "$BACKUP_DIR"
+exit 0

package/.claude/skills/cfn-agent-spawning/spawn-worker.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+set -eu
+
+# Get the project root directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+# Load team providers configuration
+PROVIDERS_CONFIG="${PROJECT_ROOT}/.claude/cfn-config/team-providers.json"
+
+# Validate configuration file exists
+if [[ ! -f "$PROVIDERS_CONFIG" ]]; then
+    echo "Error: Team providers configuration not found at $PROVIDERS_CONFIG"
+    exit 1
+fi
+
+# Function to validate provider configuration
+validate_provider_config() {
+    local team="$1"
+    local role="$2"  # coordinator or workers
+
+    # Use jq to validate JSON structure and extract provider details
+    if ! jq -e ".teams.${team}.${role}" "$PROVIDERS_CONFIG" &>/dev/null; then
+        echo "Error: Invalid or missing provider configuration for team=${team}, role=${role}"
+        exit 1
+    fi
+}
+
+# Function to select appropriate model based on complexity
+select_model() {
+    local team="$1"
+    local complexity="$2"  # simple or complex
+
+    # Retrieve model based on complexity and team configuration
+    local model=$(jq -r ".teams.${team}.workers.models.${complexity}" "$PROVIDERS_CONFIG")
+
+    if [[ "$model" == "null" ]]; then
+        # Fallback to default complexity from global config
+        local default_complexity=$(jq -r ".global_config.default_complexity // \"simple\"" "$PROVIDERS_CONFIG")
+        model=$(jq -r ".teams.${team}.workers.models.${default_complexity}" "$PROVIDERS_CONFIG")
+    fi
+
+    echo "$model"
+}
+
+# Function to get API key from environment
+get_api_key() {
+    local team="$1"
+    local role="$2"  # coordinator or workers
+
+    # Extract apiKeyEnvVar from config
+    local api_key_env_var=$(jq -r ".teams.${team}.${role}.apiKeyEnvVar" "$PROVIDERS_CONFIG")
+
+    if [[ "$api_key_env_var" == "null" ]]; then
+        echo "Error: apiKeyEnvVar not found for team=${team}, role=${role}"
+        exit 1
+    fi
+
+    # Get actual API key value from environment
+    local api_key_value="${!api_key_env_var:-}"
+
+    if [[ -z "$api_key_value" ]]; then
+        echo "Error: API key not found in environment variable: $api_key_env_var"
+        exit 1
+    fi
+
+    echo "$api_key_value"
+}
+
+# Main worker spawning logic
+spawn_worker() {
+    local team="$1"
+    local complexity="${2:-simple}"
+    local provider_mode="${3:-auto}"
+    local agent_type="${4:-}"
+    local task_context="${5:-}"
+
+    # Validate input parameters
+    validate_provider_config "$team" "workers"
+
+    # Retrieve provider details from config
+    local provider=$(jq -r ".teams.${team}.workers.provider" "$PROVIDERS_CONFIG")
+    local api_key_env_var=$(jq -r ".teams.${team}.workers.apiKeyEnvVar" "$PROVIDERS_CONFIG")
+    local base_url=$(jq -r ".teams.${team}.workers.baseUrl" "$PROVIDERS_CONFIG")
+
+    # Select model dynamically based on complexity
+    local model=$(select_model "$team" "$complexity")
+
+    # Get API key from environment
+    local api_key=$(get_api_key "$team" "workers")
+
+    # Provider routing logic
+    case "$provider_mode" in
+        auto)
+            # Use provider routing rules from config
+            case "$provider" in
+                zai)
+                    echo "Spawning Z.ai worker for team ${team} (Model: ${model}, Complexity: ${complexity})"
+
+                    # Set environment variables for Z.ai spawning
+                    export ZAI_API_KEY="$api_key"
+                    export ZAI_BASE_URL="$base_url"
+                    export ZAI_MODEL="$model"
+
+                    # Call actual spawning logic (to be implemented)
+                    # npx claude-flow-novice spawn "$agent_type" \
+                    #   --provider zai \
+                    #   --model "$model" \
+                    #   --context "$task_context"
+                    ;;
+                anthropic)
+                    echo "Spawning Anthropic worker for team ${team} (Model: ${model}, Complexity: ${complexity})"
+
+                    # Set environment variables for Anthropic spawning
+                    export ANTHROPIC_API_KEY="$api_key"
+                    export ANTHROPIC_BASE_URL="$base_url"
+                    export ANTHROPIC_MODEL="$model"
+
+                    # Call actual spawning logic (to be implemented)
+                    # npx claude-flow-novice spawn "$agent_type" \
+                    #   --provider anthropic \
+                    #   --model "$model" \
+                    #   --context "$task_context"
+                    ;;
+                *)
+                    echo "Error: Unsupported provider: ${provider}"
+                    exit 1
+                    ;;
+            esac
+            ;;
+        zai)
+            echo "Force spawning Z.ai worker for team ${team} (Model: ${model})"
+            local api_key=$(get_api_key "$team" "workers")
+            export ZAI_API_KEY="$api_key"
+            export ZAI_BASE_URL="$base_url"
+            export ZAI_MODEL="$model"
+            ;;
+        anthropic)
+            echo "Force spawning Anthropic worker for team ${team} (Model: ${model})"
+            local api_key=$(get_api_key "$team" "workers")
+            export ANTHROPIC_API_KEY="$api_key"
+            export ANTHROPIC_BASE_URL="$base_url"
+            export ANTHROPIC_MODEL="$model"
+            ;;
+        *)
+            echo "Error: Invalid provider mode: ${provider_mode}"
+            exit 1
+            ;;
+    esac
+
+    # Log successful configuration
+    echo "Worker configuration complete:"
+    echo "  Team: $team"
+    echo "  Provider: $provider"
+    echo "  Model: $model"
+    echo "  Base URL: $base_url"
+    echo "  Complexity: $complexity"
+}
+
+# Allow script to be used as a function or executed directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Script is being run directly
+    if [[ $# -lt 1 ]]; then
+        echo "Usage: $0 <team> [complexity] [provider_mode] [agent_type] [task_context]"
+        echo ""
+        echo "Arguments:"
+        echo "  team           - Team name (marketing, engineering, sales, support, finance)"
+        echo "  complexity     - simple|complex (default: simple)"
+        echo "  provider_mode  - auto|zai|anthropic (default: auto)"
+        echo "  agent_type     - Agent type to spawn (optional)"
+        echo "  task_context   - Task context for agent (optional)"
+        exit 1
+    fi
+
+    spawn_worker "$@"
+fi

package/.claude/skills/cfn-backlog-management/SKILL.md

@@ -0,0 +1,199 @@
+---
+skill_id: cfn-backlog-management
+name: CFN Backlog Management
+version: 1.0.0
+category: coordination
+tags: [backlog, documentation, sprint-planning, technical-debt]
+dependencies: []
+---
+
+# CFN Backlog Management Skill
+
+## Purpose
+Systematically capture and track backlogged items during CFN sprints to prevent work from being forgotten. Provides centralized documentation of deferred tasks with context, rationale, and proposed solutions.
+
+## Problem Solved
+During CFN Loop execution, agents frequently identify improvements, optimizations, or edge cases that should be addressed but are out of scope for the current sprint. Without systematic capture, these items are lost in chat history or forgotten entirely.
+
+## When to Use
+- **During CFN sprints** when identifying work that should be deferred
+- **After consensus** when validators identify future improvements
+- **During retrospectives** when documenting technical debt
+- **Architecture reviews** when noting long-term refactoring needs
+
+## Interface
+
+### Primary Script: `add-backlog-item.sh`
+
+**Required Parameters:**
+- `--item`: Brief description of backlogged work (1-2 sentences)
+- `--why`: Rationale for deferring (why not now?)
+- `--solution`: Proposed implementation approach
+
+**Optional Parameters:**
+- `--sprint`: Sprint identifier (default: auto-detected from context)
+- `--priority`: P0-P3 (default: P2)
+- `--tags`: Comma-separated tags (e.g., "optimization,redis,testing")
+- `--category`: Feature/Bug/Technical-Debt/Optimization (default: Technical-Debt)
+
+**Usage:**
+```bash
+./.claude/skills/cfn-backlog-management/add-backlog-item.sh \
+  --sprint "Sprint 10" \
+  --item "Implement Redis connection pooling for multi-agent coordination" \
+  --why "Current single-connection model causes bottlenecks with 10+ agents, but Sprint 10 scope limited to 3-agent validation" \
+  --solution "Use ioredis library with configurable pool size (min: 5, max: 20). Add pool metrics to monitoring dashboard" \
+  --priority "P2" \
+  --tags "optimization,redis,performance" \
+  --category "Optimization"
+```
+
+### Output Location
+All backlog items are appended to: `readme/BACKLOG.md`
+
+## Backlog File Structure
+
+```markdown
+# Claude Flow Novice - Backlog
+
+Last Updated: 2025-10-31
+
+## Active Items
+
+### P0 - Critical
+[Items requiring immediate attention in next sprint]
+
+### P1 - High Priority
+[Items to address within 2-3 sprints]
+
+### P2 - Medium Priority
+[Items to address when capacity allows]
+
+### P3 - Low Priority / Nice-to-Have
+[Items for future consideration]
+
+## Completed Items
+[Moved here when implemented, with resolution sprint noted]
+
+---
+
+## Item Template
+
+**[PRIORITY] - [Item Title]**
+- **Sprint Backlogged**: Sprint X
+- **Category**: Feature/Bug/Technical-Debt/Optimization
+- **Description**: What needs to be done
+- **Rationale**: Why it was deferred
+- **Proposed Solution**: How to implement
+- **Tags**: `tag1`, `tag2`, `tag3`
+- **Status**: Backlogged | In Progress | Completed
+- **Date Added**: YYYY-MM-DD
+```
+
+## Validation Rules
+
+The skill enforces:
+1. **All required fields present** (item, why, solution)
+2. **Item description clarity** (≥10 characters, ≤500 characters)
+3. **Rationale specificity** (must explain deferral reason, not just "out of scope")
+4. **Solution actionability** (must include concrete implementation approach)
+5. **No duplicates** (checks existing BACKLOG.md for similar items)
+
+## Integration with CFN Loops
+
+### Loop 2 Validators
+When validators identify improvements outside current scope:
+```bash
+# In validator agent
+./.claude/skills/cfn-backlog-management/add-backlog-item.sh \
+  --item "Add integration tests for Redis failure scenarios" \
+  --why "Current sprint validates happy path only; failure testing requires additional test infrastructure" \
+  --solution "Create test-redis-failures.sh with Docker-based Redis crash simulation" \
+  --tags "testing,redis,edge-cases"
+```
+
+### Product Owner Decision
+When Product Owner defers work for future sprint:
+```bash
+# In product-owner agent
+./.claude/skills/cfn-backlog-management/add-backlog-item.sh \
+  --item "Migrate coordination from Redis to etcd for production scale" \
+  --why "Redis sufficient for current 10-agent limit; etcd needed for 100+ agent deployments" \
+  --solution "Abstract coordination layer behind interface, implement etcd adapter" \
+  --priority "P3" \
+  --category "Technical-Debt"
+```
+
+### Coordinator Context
+Coordinators can query backlog for related items before spawning agents:
+```bash
+# Check if backlog contains relevant context
+grep -i "redis pooling" readme/BACKLOG.md
+# Use results to inform agent context injection
+```
+
+## Query Interface
+
+**Search by tag:**
+```bash
+grep -A 10 "Tags:.*redis" readme/BACKLOG.md
+```
+
+**Filter by priority:**
+```bash
+sed -n '/^### P1/,/^### P2/p' readme/BACKLOG.md
+```
+
+**List all optimization items:**
+```bash
+grep -B 2 "Category: Optimization" readme/BACKLOG.md
+```
+
+## Maintenance
+
+**Weekly Review**: Product Owner reviews P0-P1 items for sprint planning
+**Monthly Cleanup**: Archive completed items, reassess P3 priorities
+**Quarterly Audit**: Remove stale items (>6 months old, no activity)
+
+## Best Practices
+
+1. **Be specific**: "Add caching" → "Implement Redis LRU cache for agent context with 1h TTL"
+2. **Explain constraints**: "Not enough time" → "Requires 8h estimation work; current sprint has 2h budget"
+3. **Provide actionable solutions**: "Fix later" → "Refactor using Strategy pattern from planning/PATTERNS.md"
+4. **Tag appropriately**: Enables filtering and sprint planning
+5. **Update status**: Move to "Completed" when resolved, note resolution sprint
+
+## Anti-Patterns
+
+❌ **Vague items**: "Improve performance" (What component? How much improvement?)
+❌ **No rationale**: "Backlog this" (Why defer? What's the blocker?)
+❌ **Solution-less**: "Fix Redis issues" (What's the approach? What research is needed?)
+❌ **Duplicate entries**: Check BACKLOG.md before adding
+❌ **Scope creep**: Backlog is for deferred work, not scope expansion
+
+## Example Backlog Item
+
+```markdown
+**[P1] - Implement Adaptive Validator Scaling**
+- **Sprint Backlogged**: Sprint 9 - CFN v3 Implementation
+- **Category**: Optimization
+- **Description**: Dynamically adjust number of Loop 2 validators (2-5) based on task complexity. Currently fixed at 3-4 validators regardless of task size.
+- **Rationale**: Sprint 9 focused on dual-mode architecture validation. Adaptive scaling requires task complexity classifier (NLP or heuristic-based), estimated 12h implementation vs 4h sprint budget.
+- **Proposed Solution**: Create task-classifier skill that analyzes task description (file count, domain keywords, integration points) and returns complexity score (0.0-1.0). Map score to validator count: <0.3 → 2 validators, 0.3-0.7 → 3-4 validators, >0.7 → 5 validators. Reference: CFN_LOOP_TASK_MODE.md section on adaptive validator scaling.
+- **Tags**: `optimization`, `cfn-loop`, `validation`, `adaptive-scaling`
+- **Status**: Backlogged
+- **Date Added**: 2025-10-31
+```
+
+## Success Metrics
+
+- **Backlog utilization**: ≥30% of backlog items addressed within 3 sprints
+- **Item clarity**: 0 items missing required fields
+- **Discovery rate**: ≥50% of technical debt captured vs lost in chat
+- **Sprint planning efficiency**: Backlog queries reduce planning time by 20%
+
+## References
+
+- **STRAT-025**: Explicit Deliverable Tracking (adaptive context)
+- **CFN Loop Documentation**: `.claude/commands/cfn/CFN_LOOP_TASK_MODE.md`
+- **Sprint Execution**: CLAUDE.md Section 6 - Sprint Context Injection