claude-flow-novice 2.11.0 → 2.13.0

package/.claude/commands/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

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

@@ -0,0 +1,349 @@
+---
+skill_id: cfn-changelog-management
+name: CFN Changelog Management
+version: 1.0.0
+category: documentation
+tags: [changelog, versioning, release-notes, sparse-logging]
+dependencies: []
+---
+
+# CFN Changelog Management Skill
+
+## Purpose
+Systematically track implementation changes with sparse, structured entries appended to project changelog. Enables quick visibility into what changed, when, and why without verbose commit-style messages.
+
+## Problem Solved
+Traditional changelogs require manual curation and often become stale or inconsistent. Agents completing features, fixing bugs, or making architectural changes need a lightweight way to document impact without context-switching to git commits or detailed documentation.
+
+## When to Use
+
+### ✅ REQUIRED Usage Scenarios
+- **After feature implementation** - Agent completes feature work
+- **After bug fix** - Agent resolves issue with code changes
+- **After breaking change** - API/interface modifications that affect consumers
+- **After dependency update** - Major version bumps or security patches
+- **After architectural change** - Coordination pattern modifications, skill refactors
+
+### ⚠️ OPTIONAL Usage Scenarios
+- **After performance optimization** - Measurable improvements (>10% speedup)
+- **After security enhancement** - Hardening, vulnerability fixes
+- **Internal refactoring** - Code cleanup without behavioral changes (use judgment)
+
+### ❌ DO NOT USE For
+- **Routine maintenance** - Formatting, linting, comment updates
+- **Work-in-progress** - Incomplete features or experimental changes
+- **Test-only changes** - Adding tests without production code changes
+- **Documentation-only updates** - README edits, comment clarifications
+
+## Interface
+
+### Primary Script: `add-changelog-entry.sh`
+
+**Required Parameters:**
+- `--type`: Entry type (feature|bugfix|breaking|dependency|architecture|performance|security)
+- `--summary`: One-line description (10-100 chars)
+- `--impact`: What changed and why it matters
+
+**Optional Parameters:**
+- `--version`: Target version (default: auto-increment patch)
+- `--issue`: Related issue/bug number (e.g., "BUG-123", "#456")
+- `--files`: Key files affected (comma-separated, max 5)
+- `--migration`: Migration notes for breaking changes
+
+**Usage:**
+```bash
+./.claude/skills/cfn-changelog-management/add-changelog-entry.sh \
+  --type "feature" \
+  --summary "Add backlog management skill for deferred work tracking" \
+  --impact "Agents can now systematically capture deferred items with structured metadata instead of losing context in chat history" \
+  --files ".claude/skills/cfn-backlog-management/SKILL.md,readme/BACKLOG.md"
+```
+
+### Output Location
+All entries appended to: `readme/CHANGELOG.md`
+
+## Changelog File Structure
+
+```markdown
+# Claude Flow Novice Changelog
+
+## [Unreleased]
+
+### Features
+- Add backlog management skill (2025-10-31)
+  - Impact: Systematic deferred work tracking with priority/tag organization
+  - Files: `.claude/skills/cfn-backlog-management/`
+
+### Bug Fixes
+
+### Breaking Changes
+
+### Dependencies
+
+### Architecture
+
+### Performance
+
+### Security
+
+---
+
+## [2.11.0] - 2025-10-31
+
+### Features
+- Backlog management skill implementation
+  - Impact: Centralized tracking of deferred work items
+  - Files: `.claude/skills/cfn-backlog-management/add-backlog-item.sh`
+
+...
+```
+
+## Entry Types
+
+### Feature
+New functionality, skills, commands, or capabilities.
+```bash
+--type "feature"
+--summary "Implement Redis pub/sub coordination for zero-token waiting"
+--impact "Agents block on BLPOP instead of polling, eliminating API calls during wait cycles"
+```
+
+### Bug Fix
+Defect resolution, error handling improvements.
+```bash
+--type "bugfix"
+--summary "Fix race condition in Loop 3 confidence collection"
+--impact "Orchestrator now uses synchronous temp file capture instead of polling Redis keys"
+--issue "BUG-10"
+```
+
+### Breaking Change
+Incompatible changes requiring user/agent migration.
+```bash
+--type "breaking"
+--summary "Rename skill cfn-redis-coordination → cfn-swarm-coordination"
+--impact "All agent spawn commands must update skill references"
+--migration "Run: sed -i 's/cfn-redis-coordination/cfn-swarm-coordination/g' .claude/agents/**/*.md"
+```
+
+### Dependency
+Package updates, version bumps, security patches.
+```bash
+--type "dependency"
+--summary "Upgrade redis 5.0.0 → 5.8.3"
+--impact "Fixes CVE-2024-1234, adds BLPOP timeout parameter support"
+```
+
+### Architecture
+Coordination pattern changes, skill refactors, system design updates.
+```bash
+--type "architecture"
+--summary "Extract output processing into dedicated skill"
+--impact "95% code reuse between Loop 3 and Loop 2 consensus collection"
+--files ".claude/skills/cfn-agent-output-processing/SKILL.md"
+```
+
+### Performance
+Optimizations with measurable impact.
+```bash
+--type "performance"
+--summary "Parallel agent spawning with background processes"
+--impact "3x speedup for 3-agent coordination (sequential: 15s → parallel: 5s max latency)"
+```
+
+### Security
+Hardening, vulnerability fixes, audit improvements.
+```bash
+--type "security"
+--summary "Add pre-edit backup hook for safe file revert"
+--impact "Prevents git conflicts in parallel sessions, 24h backup retention"
+```
+
+## Validation Rules
+
+1. **Type validation**: Must be one of 7 defined types
+2. **Summary length**: 10-100 characters (enforces brevity)
+3. **Impact required**: Cannot be empty (enforces "why it matters")
+4. **File limit**: Max 5 files (prevents noise)
+5. **Version format**: Semantic versioning (X.Y.Z)
+
+## Sparse Language Guidelines
+
+### ✅ Good Examples
+```
+Summary: "Add Redis coordination skill"
+Impact: "Zero-token agent waiting via BLPOP"
+
+Summary: "Fix confidence parsing edge case"
+Impact: "Handles percentage format (85%) in addition to decimal (0.85)"
+
+Summary: "Upgrade better-sqlite3 to v12.4.1"
+Impact: "Node 22 compatibility, fixes installation errors on WSL2"
+```
+
+### ❌ Bad Examples (Too Verbose)
+```
+Summary: "We have implemented a comprehensive Redis-based coordination system..."
+Impact: "This change allows agents to coordinate more efficiently by using a blocking..."
+
+Summary: "Fixed a bug"
+Impact: "There was an issue that has been resolved"
+```
+
+### Sparse Pattern Rules
+- **Active voice**: "Add feature" not "Feature added"
+- **No articles**: "Fix bug" not "Fix the bug"
+- **No fluff**: "Enables X" not "This change enables X"
+- **Measurable impact**: Include numbers when relevant (3x speedup, 95% reduction)
+
+## Integration Examples
+
+### Loop 3 Agent (After Feature Implementation)
+```bash
+# Agent completes feature work
+Edit: file_path="src/new-feature.ts" ...
+
+# Document change
+./.claude/skills/cfn-changelog-management/add-changelog-entry.sh \
+  --type "feature" \
+  --summary "JWT authentication middleware" \
+  --impact "Stateless auth reduces session storage by 80%" \
+  --files "src/middleware/auth.ts,src/types/jwt.ts"
+```
+
+### Loop 2 Validator (After Identifying Bug Fix)
+```bash
+# Validator reviews fix
+./.claude/skills/cfn-changelog-management/add-changelog-entry.sh \
+  --type "bugfix" \
+  --summary "Prevent null pointer in Redis connection retry" \
+  --impact "Eliminates crashes during Redis unavailability" \
+  --issue "BUG-42" \
+  --files "src/redis/client.ts"
+```
+
+### Product Owner (After Architectural Decision)
+```bash
+# Product Owner approves design change
+./.claude/skills/cfn-changelog-management/add-changelog-entry.sh \
+  --type "architecture" \
+  --summary "Split orchestrator into modular helper scripts" \
+  --impact "78% code reduction, improved testability" \
+  --files ".claude/skills/cfn-loop-orchestration/helpers/"
+```
+
+## Versioning Strategy
+
+### Auto-Increment (Default)
+Script reads current version from `package.json`, increments patch:
+- Current: `2.11.0` → Entry added to: `[Unreleased]`
+- On release: Move `[Unreleased]` → `[2.11.1] - YYYY-MM-DD`
+
+### Manual Version (Override)
+```bash
+--version "3.0.0"  # Specify major/minor bump explicitly
+```
+
+### Release Workflow
+1. Agents add entries to `[Unreleased]` section
+2. On release trigger (manual or automated):
+   - Rename `[Unreleased]` → `[X.Y.Z] - DATE`
+   - Create new empty `[Unreleased]` section
+   - Update `package.json` version
+
+## Query Interface
+
+**Filter by type:**
+```bash
+sed -n '/### Features/,/### Bug Fixes/p' readme/CHANGELOG.md
+```
+
+**Recent entries (last 10):**
+```bash
+grep -A 2 "^- " readme/CHANGELOG.md | head -30
+```
+
+**Search by keyword:**
+```bash
+grep -i "redis" readme/CHANGELOG.md
+```
+
+**Entries for specific version:**
+```bash
+sed -n '/## \[2.11.0\]/,/## \[2.10.0\]/p' readme/CHANGELOG.md
+```
+
+## Best Practices
+
+1. **Immediate logging**: Add entry immediately after completing work, not batched
+2. **User perspective**: Describe impact from user/agent consumer viewpoint
+3. **File references**: Include key files for context (not exhaustive list)
+4. **Link issues**: Reference bug numbers or GitHub issues when applicable
+5. **Migration notes**: Always include for breaking changes
+
+## Anti-Patterns
+
+❌ **Verbose commit messages**: "This commit implements a new feature that..."
+❌ **Generic summaries**: "Fixed bugs", "Updated code", "Improvements"
+❌ **Missing impact**: "Added function X" (Why does it matter?)
+❌ **Duplicate entries**: Check existing changelog before adding
+❌ **Version conflicts**: Don't manually edit version, use --version flag
+
+## Example Entry Lifecycle
+
+**Step 1: Agent completes feature**
+```bash
+add-changelog-entry.sh \
+  --type "feature" \
+  --summary "Multi-pattern confidence parsing" \
+  --impact "100% extraction success, supports explicit/percentage/qualitative formats"
+```
+
+**Result in CHANGELOG.md:**
+```markdown
+## [Unreleased]
+
+### Features
+- Multi-pattern confidence parsing (2025-10-31)
+  - Impact: 100% extraction success, supports explicit/percentage/qualitative formats
+  - Files: `.claude/skills/cfn-agent-output-processing/parse-confidence.sh`
+```
+
+**Step 2: Release triggered**
+```bash
+# Manual or automated
+npm version minor  # 2.11.0 → 2.12.0
+```
+
+**Result:**
+```markdown
+## [2.12.0] - 2025-11-01
+
+### Features
+- Multi-pattern confidence parsing (2025-10-31)
+  - Impact: 100% extraction success, supports explicit/percentage/qualitative formats
+  - Files: `.claude/skills/cfn-agent-output-processing/parse-confidence.sh`
+
+---
+
+## [Unreleased]
+
+### Features
+
+### Bug Fixes
+...
+```
+
+## Success Metrics
+
+- **Entry quality**: ≥90% of entries include measurable impact
+- **Sparse language**: Average summary length ≤60 characters
+- **Timeliness**: ≥80% of entries added within same sprint as implementation
+- **Coverage**: 100% of features/breaking changes documented
+- **Queryability**: Users can find relevant changes in <30 seconds
+
+## References
+
+- **Sparse Language**: readme/CLAUDE.md - Documentation Guidelines
+- **Backlog Management**: `.claude/skills/cfn-backlog-management/SKILL.md`
+- **Versioning**: `package.json` - Single source of truth