claude-flow-novice 2.11.0 → 2.13.0

package/.claude/skills/cfn-changelog-management/add-changelog-entry.sh

@@ -0,0 +1,200 @@
+#!/bin/bash
+set -e
+
+# cfn-changelog-management/add-changelog-entry.sh
+# Adds sparse, structured entries to readme/CHANGELOG.md
+
+# Default values
+TYPE=""
+SUMMARY=""
+IMPACT=""
+VERSION=""
+ISSUE=""
+FILES=""
+MIGRATION=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --type)
+      TYPE="$2"
+      shift 2
+      ;;
+    --summary)
+      SUMMARY="$2"
+      shift 2
+      ;;
+    --impact)
+      IMPACT="$2"
+      shift 2
+      ;;
+    --version)
+      VERSION="$2"
+      shift 2
+      ;;
+    --issue)
+      ISSUE="$2"
+      shift 2
+      ;;
+    --files)
+      FILES="$2"
+      shift 2
+      ;;
+    --migration)
+      MIGRATION="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validation
+if [[ -z "$TYPE" ]]; then
+  echo "Error: --type is required" >&2
+  echo "Valid types: feature, bugfix, breaking, dependency, architecture, performance, security" >&2
+  exit 1
+fi
+
+if [[ -z "$SUMMARY" ]]; then
+  echo "Error: --summary is required" >&2
+  exit 1
+fi
+
+if [[ -z "$IMPACT" ]]; then
+  echo "Error: --impact is required" >&2
+  exit 1
+fi
+
+# Validate type
+VALID_TYPES="feature|bugfix|breaking|dependency|architecture|performance|security"
+if [[ ! "$TYPE" =~ ^($VALID_TYPES)$ ]]; then
+  echo "Error: --type must be one of: feature, bugfix, breaking, dependency, architecture, performance, security (got: $TYPE)" >&2
+  exit 1
+fi
+
+# Validate summary length
+SUMMARY_LENGTH=${#SUMMARY}
+if (( SUMMARY_LENGTH < 10 )); then
+  echo "Error: --summary must be at least 10 characters (got $SUMMARY_LENGTH)" >&2
+  exit 1
+fi
+
+if (( SUMMARY_LENGTH > 100 )); then
+  echo "Error: --summary must be at most 100 characters (got $SUMMARY_LENGTH)" >&2
+  exit 1
+fi
+
+# Validate file limit
+if [[ -n "$FILES" ]]; then
+  FILE_COUNT=$(echo "$FILES" | tr ',' '\n' | wc -l)
+  if (( FILE_COUNT > 5 )); then
+    echo "Error: --files can contain at most 5 files (got $FILE_COUNT)" >&2
+    exit 1
+  fi
+fi
+
+# Path to changelog
+CHANGELOG_FILE="readme/CHANGELOG.md"
+PROJECT_ROOT="/mnt/c/Users/masha/Documents/claude-flow-novice"
+CHANGELOG_PATH="$PROJECT_ROOT/$CHANGELOG_FILE"
+
+# Check if changelog exists
+if [[ ! -f "$CHANGELOG_PATH" ]]; then
+  echo "Error: Changelog not found at $CHANGELOG_PATH" >&2
+  echo "Expected format: readme/CHANGELOG.md" >&2
+  exit 1
+fi
+
+# Map type to section header
+case "$TYPE" in
+  feature)
+    SECTION="### Features"
+    ;;
+  bugfix)
+    SECTION="### Bug Fixes"
+    ;;
+  breaking)
+    SECTION="### Breaking Changes"
+    ;;
+  dependency)
+    SECTION="### Dependencies"
+    ;;
+  architecture)
+    SECTION="### Architecture"
+    ;;
+  performance)
+    SECTION="### Performance"
+    ;;
+  security)
+    SECTION="### Security"
+    ;;
+esac
+
+# Current date
+CURRENT_DATE=$(date +%Y-%m-%d)
+
+# Build entry
+ENTRY="- $SUMMARY ($CURRENT_DATE)"
+ENTRY="$ENTRY\n  - Impact: $IMPACT"
+
+if [[ -n "$FILES" ]]; then
+  ENTRY="$ENTRY\n  - Files: \`$FILES\`"
+fi
+
+if [[ -n "$ISSUE" ]]; then
+  ENTRY="$ENTRY\n  - Issue: $ISSUE"
+fi
+
+if [[ -n "$MIGRATION" ]]; then
+  ENTRY="$ENTRY\n  - Migration: $MIGRATION"
+fi
+
+# Find [Unreleased] section and appropriate subsection
+# Insert entry after section header
+
+# Check if [Unreleased] section exists
+if ! grep -q "## \[Unreleased\]" "$CHANGELOG_PATH"; then
+  echo "Error: [Unreleased] section not found in changelog" >&2
+  echo "Expected format:" >&2
+  echo "## [Unreleased]" >&2
+  echo "" >&2
+  echo "### Features" >&2
+  exit 1
+fi
+
+# Check if section exists within [Unreleased]
+if ! awk '/## \[Unreleased\]/,/^---$/ { if (/'"$SECTION"'/) found=1 } END { exit !found }' "$CHANGELOG_PATH"; then
+  echo "Error: $SECTION not found within [Unreleased] section" >&2
+  exit 1
+fi
+
+# Insert entry after section header (first blank line or entry)
+awk -v section="$SECTION" -v entry="$ENTRY" '
+  # Track if we are in [Unreleased] section
+  /## \[Unreleased\]/ { in_unreleased=1 }
+  /^## \[/ && !/## \[Unreleased\]/ { in_unreleased=0 }
+
+  # When we find the target section within [Unreleased]
+  in_unreleased && $0 ~ section {
+    print
+    getline  # Read next line
+    print    # Print it (usually blank line)
+    print entry
+    next
+  }
+  {print}
+' "$CHANGELOG_PATH" > "${CHANGELOG_PATH}.tmp"
+
+mv "${CHANGELOG_PATH}.tmp" "$CHANGELOG_PATH"
+
+echo "✅ Changelog entry added successfully"
+echo "   Type: $TYPE"
+echo "   Summary: $SUMMARY"
+echo "   Section: $SECTION"
+echo "   Location: $CHANGELOG_FILE"
+
+# Output path for scripting
+echo "$CHANGELOG_PATH"

package/claude-assets/commands/cfn/README.md

@@ -1,157 +1,205 @@
-# CLAUDE.md Slash Command System
+# CFN Loop Commands - Quick Reference
 
-## 🎯 Simple, Focused CLAUDE.md Generation
+## Workflows vs Skills vs Playbooks - When to Use What
 
-A lightweight slash command system for generating CLAUDE.md files with NPX protection.
+### Skills (Most Common) - Building Blocks
+**What:** Single-purpose bash scripts in `.claude/skills/`
+**When:** Most tasks - they're the building blocks
+**Example:** `cfn-redis-coordination`, `cfn-agent-spawning`, `cfn-loop-validation`
 
-## 📋 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
+# Direct skill invocation
+./.claude/skills/cfn-redis-coordination/invoke-waiting-mode.sh enter \
+  --task-id "task-123" \
+  --agent-id "coder-1"
 ```
 
-### 🛡️ **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
+**Use skills when:**
+- Single, focused operation needed
+- Called by agents or coordinators
+- Part of larger workflow
+- Reusable across different tasks
+
+### Playbooks (Not Currently Used) - Pre-Configured Sequences
+**What:** JSON files defining skill sequences for common patterns
+**When:** Repeating the same skill sequence often
+**Status:** Not implemented yet, use skills directly
+
+### Workflows - Complex Automation
+**What:** Event-driven, multi-step automation with conditions/branching
+**When:** Complex sequences with conditional logic
+**Example:** CI/CD pipelines, feature development workflows
+
+```yaml
+name: "feature-development"
+trigger: "branch-created"
+steps:
+  - name: "analyze"
+    agent: "researcher"
+
+  - name: "implement"
+    agent: "backend-dev"
+    depends: ["analyze"]
+    parallel: true  # Multiple agents in parallel
+
+  - name: "test"
+    agent: "tester"
+    depends: ["implement"]
+    condition: "if tests_exist"  # Conditional execution
+```
 
-### 🔄 **Integration Flow**
+**Use workflows when:**
+- Event-driven automation (git hooks, CI/CD)
+- Conditional branching logic needed
+- Multi-agent parallel execution
+- Long-running background processes
+- Integration with external systems
 
-**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
+## Decision Tree
 
-**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
+```
+Need to automate something?
+├─ Single operation?
+│  └─ Use SKILL directly
+├─ Complex logic (conditionals, events, parallel)?
+│  └─ Create WORKFLOW (YAML via /workflow)
+└─ CFN Loop execution?
+   ├─ Planning first? → /write-plan then /cfn-loop-cli
+   ├─ Production? → /cfn-loop-cli
+   ├─ Debugging? → /cfn-loop-task
+   └─ Frontend? → /cfn-loop-frontend
+```
 
-## 🏗️ Architecture
+## Examples
 
-### **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
+### Example 1: Simple Task (Use Skill)
+**Goal:** Enter waiting mode for agent
 
-### **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
+```bash
+./.claude/skills/cfn-redis-coordination/invoke-waiting-mode.sh enter \
+  --task-id "task-123" --agent-id "coder-1"
+```
 
-## 🎮 Usage Examples
+### Example 2: CFN Loop Execution
+**Goal:** Implement JWT authentication
 
-### **Basic Generation:**
+**Option 1: Plan First (Recommended for Complex Tasks)**
 ```bash
-# Generate CLAUDE.md for current project
-/claude-md
+# Step 1: Generate plan
+/write-plan "Implement JWT authentication" --mode=standard
+# Reviews: planning/PLAN_jwt_authentication.md
 
-# Output:
-# 🚀 Generating CLAUDE.md...
-# ✅ CLAUDE.md generated successfully
+# Step 2: Execute
+/cfn-loop-cli "Implement JWT authentication" --mode=standard
 ```
 
-### **Preview Mode:**
+**Option 2: Direct Execution (Simple Tasks)**
 ```bash
-# See what would be generated
-/claude-md --preview
-
-# Output:
-# 📄 CLAUDE.md Preview:
-# ══════════════════════════════════════════════════
-# # Claude Code Configuration - JavaScript Project
-# ...
-# ══════════════════════════════════════════════════
-# 📊 Total length: 2,847 characters
+# Production execution (cost-optimized)
+/cfn-loop-cli "Implement JWT authentication" --mode=standard
+
+# OR debugging (full visibility)
+/cfn-loop-task "Implement JWT authentication" --mode=standard
 ```
 
-### **NPX Protection:**
+### Example 3: Complex Automation (Use Workflow)
+**Goal:** Full feature development (analyze → implement → test → deploy)
+
 ```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
-```
+# Create workflow (via /workflow)
+/workflow create feature-pipeline
 
-## 🧠 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
-}
+# Execute workflow
+/workflow execute feature-pipeline
 ```
 
-### **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
+## Quick Reference Table
+
+| Type | Files | Complexity | Conditional Logic | Parallel Execution | Event-Driven |
+|------|-------|------------|-------------------|-------------------|--------------|
+| **Skill** | `.sh` scripts | Low | No | No | No |
+| **CFN Loop** | Slash commands | Medium | Yes (built-in) | Yes (agents) | No |
+| **Workflow** | `.yaml` definitions | High | Yes | Yes | Yes |
+
+---
+
+## CFN Loop Commands (Current)
+
+### Execution Commands
+- `/cfn-loop-task` - Task mode (debugging, full visibility, Main Chat coordinates)
+- `/cfn-loop-cli` - CLI mode (production, cost-optimized, coordinator spawns CLI agents)
+- `/cfn-loop-frontend` - Visual iteration (screenshot + video validation, supports both modes)
+
+### Planning & Documentation
+- `/write-plan` - Pre-planning phase (generates TDD implementation plan)
+- `/cfn-loop-document` - Documentation generation (updates `/readme`)
+
+### Configuration
+- `/cfn-mode` - Toggle CLI vs Task spawning mode
+- `/cfn-optimize-agents` - Agent optimization settings
+- `/cfn-claude-sync` - Sync rules from CLAUDE.md to commands
+
+### Infrastructure
+- `/switch-api` - Switch between Z.ai and Anthropic providers
+
+### Automation
+- `/workflow` - Event-driven workflow automation (complex multi-step)
+
+### Testing & Utilities
+- `/hello-world-tests` - CFN coordination validation tests (4 layers)
+- `/github-commit` - Git commit with CI/CD monitoring
+- `/launch-web-dashboard` - Start web portal (http://localhost:3000)
+- `/list-agents-rebuild` - Regenerate agent list from discovery
+
+### Adaptive Context (ACE System)
+- `/context-stats` - View adaptive context statistics
+- `/context-reflect` - Extract lessons from task execution
+- `/context-query` - Query context bullets by category/tags
+- `/context-inject` - Inject context into CLAUDE.md dynamically
+- `/context-curate` - Merge reflection deltas with deduplication
+
+---
+
+## When to Use Each Command
+
+### /write-plan (Pre-Planning)
+**Use before complex CFN Loop tasks:**
+- Security-critical features
+- Complex architecture decisions
+- Team collaboration (plan review)
+- Learning CFN Loop workflow
+
+### /cfn-loop-cli (Production)
+**Use for:**
+- Production features
+- Long-running tasks (>10 min)
+- Multi-iteration workflows
+- Cost-sensitive projects
+- **Cost:** $0.054/iteration with Z.ai routing
+
+### /cfn-loop-task (Debugging)
+**Use for:**
+- Debugging CFN Loop issues
+- Learning agent interactions
+- Prototyping configurations
+- Short tasks (<5 min)
+- **Cost:** $0.150/iteration (3x CLI, but full visibility)
+
+### /cfn-loop-frontend (Visual Iteration)
+**Use for:**
+- React/Vue/Angular components
+- UI implementation with mockups
+- Accessibility validation
+- Visual regression testing
+- **Supports:** Both CLI and Task modes
+
+### /workflow (Complex Automation)
+**Use for:**
+- CI/CD pipelines
+- Event-driven automation
+- Multi-step with conditionals
+- External system integration
 
 ---
 
-**Simple, focused, and protective - exactly what CLAUDE.md generation should be!** 🎯
+**Version:** 3.0.0 (2025-10-31) - Consolidated command structure with workflows/skills guide