claude-flow-novice 2.10.5 → 2.10.7

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

@@ -0,0 +1,353 @@
+# CFN Loop Task Mode - Quick Reference
+
+**Version:** 1.0.0  |  **Date:** 2025-10-28  |  **Status:** Production Ready
+
+---
+
+## Overview
+
+Task Mode: Main Chat spawns coordinator and agents via Task() tool with full context injection and visibility.
+
+| Aspect | Task Mode | CLI Mode |
+|--------|-----------|----------|
+| **Spawning** | Main Chat via Task() | Coordinator via npx CLI |
+| **Visibility** | Full transparency in Main Chat | Background, Redis logs |
+| **Provider** | All Anthropic | CLI uses Z.ai routing |
+| **Cost** | ~$0.150/iteration | ~$0.054/iteration (64% savings) |
+| **Use Case** | Debugging, prototyping, learning | Production, cost optimization |
+
+---
+
+## Agent Specialization
+
+### Loop 3 (Implementation)
+
+| Task Type | Agents | Count |
+|-----------|--------|-------|
+| Backend API | backend-dev, researcher, devops | 3 |
+| Full-Stack | backend-dev, react-frontend-engineer, devops | 3 |
+| Mobile | mobile-dev, backend-dev, researcher | 3 |
+| Infrastructure | devops, rust-developer, researcher | 2-3 |
+| NPM Package | npm-package-specialist, backend-dev, researcher | 3 |
+| Documentation | api-documentation, researcher | 2 |
+
+**Available Implementers:** backend-dev, react-frontend-engineer, devops, rust-developer, researcher, mobile-dev, npm-package-specialist, base-template-generator, api-documentation
+
+### Loop 2 (Validation)
+
+| Complexity | Files | LOC | Validators | Agents | Threshold |
+|------------|-------|-----|------------|--------|-----------|
+| Simple | 1-2 | <200 | 2 | reviewer, tester | 0.85 |
+| Standard | 3-5 | 200-500 | 4 | +architect, +security-specialist | 0.90 |
+| Complex/Enterprise | >5 | >500 | 5 | +code-analyzer, +perf/ada* | 0.92-0.95 |
+
+*Add performance-benchmarker if perf-critical, accessibility-advocate-persona if frontend
+
+**Adaptive Scaling Logic:**
+```javascript
+let validators = ['reviewer', 'tester']; // Base (Simple)
+// Standard: 3-5 files or 200-500 LOC
+if (files >= 3 || LOC >= 200) {
+  validators.push('architect', 'security-specialist');
+}
+// Complex/Enterprise: >5 files or >500 LOC
+if (files > 5 || LOC > 500) {
+  validators.push('code-analyzer');
+  if (keywords.match(/performance|cache|optimization/i)) validators.push('performance-benchmarker');
+  if (keywords.match(/frontend|ui|react|vue|angular/i)) validators.push('accessibility-advocate-persona');
+}
+return validators.slice(0, 6); // Max 6
+```
+
+**Available Validators:** reviewer, tester, architect, security-specialist, performance-benchmarker, code-analyzer, accessibility-advocate-persona, playwright-tester, interaction-tester
+
+### Loop 4 (Product Owner)
+
+- **product-owner**: GOAP decision-making, scope enforcement (PROCEED/ITERATE/ABORT)
+- **cto-agent**: Epic-level planning, resource allocation, technology decisions
+
+---
+
+## Sprint Completion Workflow
+
+**Key Difference in Task Mode:**
+- Product Owner spawned via `Task()` by coordinator (NOT via `execute-decision.sh`)
+- Use helper scripts for parsing/validation: `parse-decision.sh`, `validate-deliverables.sh`
+- CLI Mode uses `execute-decision.sh` which handles spawning + all logic
+
+### 1. Consensus Validation
+
+**Task Mode** - Coordinator spawns Product Owner via Task():
+```javascript
+// Coordinator builds context and spawns PO
+const poContext = `
+  CFN Loop iteration ${iteration} complete.
+  Loop 2 Consensus: ${consensus} (threshold: ${threshold})
+
+  Decision Framework:
+  - PROCEED: Consensus >= ${threshold} AND deliverables verified
+  - ITERATE: Consensus < ${threshold} AND iteration < ${maxIterations}
+  - ABORT: Max iterations reached
+
+  Output format: Decision: [PROCEED|ITERATE|ABORT]
+`;
+
+const poOutput = Task("product-owner", poContext);
+
+// Parse decision using helper
+const decision = exec(`parse-decision.sh --output "${poOutput}"`);
+// Output: PROCEED | ITERATE | ABORT
+```
+
+**Note:** Do NOT call `execute-decision.sh` in Task Mode - it spawns PO via CLI, causing duplicate agents.
+
+### 2. Deliverable Verification
+```bash
+# Verify deliverables exist (prevents "consensus on vapor")
+./.claude/skills/cfn-product-owner-decision/validate-deliverables.sh \
+  --task-id "$TASK_ID" \
+  --expected-files "src/auth.ts,tests/auth.test.ts"
+
+# Returns: SUCCESS | FAILED
+# If FAILED + implementation task → override PROCEED to ITERATE
+```
+
+### 3. Git Commit & Push
+```bash
+git add .
+git commit -m "$(cat <<'EOF'
+feat(sprint-X): [feature name]
+
+Deliverables:
+- [files created/modified]
+
+Validation:
+- Consensus: [0.XX]
+- Tests: [status]
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+git push origin main
+```
+
+### 4. Sprint Summary
+```bash
+cat > "docs/SPRINT_${SPRINT_NUM}_COMPLETE.md" <<EOF
+# Sprint ${SPRINT_NUM} Complete
+**Date:** $(date +%Y-%m-%d) | **Consensus:** ${CONSENSUS}
+## Deliverables
+$(git diff HEAD~1 --name-status | awk '{print "- "$2}')
+## Validation
+Iterations: Loop 3: ${L3}, Loop 2: ${L2} | Decision: PROCEED
+EOF
+```
+
+**Checklist:**
+- [ ] Consensus ≥ threshold | [ ] Product Owner approved | [ ] Deliverables verified
+- [ ] Tests passing | [ ] Git committed | [ ] Git pushed | [ ] Summary generated
+
+---
+
+## Backlog Mechanism
+
+### Epic Config Structure
+```json
+{
+  "epic_id": "epic-auth-001",
+  "phases": [...],
+  "backlog": [
+    {
+      "backlog_id": "backlog-001",
+      "title": "Implement OAuth",
+      "reason": "Out of scope - deferred by PO",
+      "priority": "P2",
+      "estimated_complexity": "medium"
+    }
+  ]
+}
+```
+
+### Adding Backlog Items
+
+**Manual:**
+```bash
+./.claude/skills/epic-management/add-backlog-item.sh \
+  --epic-id "epic-auth-001" --title "OAuth" --priority "P2"
+```
+
+**Auto-Deferral (Product Owner):**
+```bash
+# CLI Mode: execute-decision.sh handles this automatically
+# Task Mode: Coordinator should implement this logic after PO decision
+if [[ "$FEEDBACK" == *"out of scope"* ]]; then
+  add-backlog-item.sh --epic-id "$EPIC_ID" --title "$ITEM" --auto-deferred
+fi
+```
+
+### Prioritization
+- **P1**: Critical, blocks progress → process immediately
+- **P2**: High value → next sprint
+- **P3**: Nice to have → background worker
+
+---
+
+## Adaptive Validator Scaling
+
+### Complexity Scoring
+```javascript
+let score = 0;
+score += (files <= 2) ? 10 : (files <= 5) ? 30 : 60;
+score += (LOC <= 200) ? 10 : (LOC <= 500) ? 30 : 60;
+if (task.match(/auth|payment|token/i)) score += 40; // Security
+if (task.match(/performance|cache/i)) score += 30;   // Performance
+if (task.match(/frontend|ui|react|vue|angular/i)) score += 20; // ADA compliance
+
+// Category: simple (≤50), standard (≤100), complex/enterprise (>100)
+// Validators: simple=2, standard=4 (arch+sec), complex=5+ (code-analyzer+perf/ada*)
+```
+
+### Dynamic Thresholds
+```javascript
+const base = {simple: 0.85, standard: 0.90, complex: 0.92};
+threshold = base[category] + (iteration - 1) * 0.02; // Stricter on retries
+threshold = Math.min(threshold, 0.98); // Cap at 0.98
+```
+
+---
+
+## Background Backlog Worker
+
+### Architecture
+- **Main Chat**: Spawns Task() coordinator for Sprint N (foreground)
+- **Background CLI**: Processes P3 backlog items (detached process)
+
+### Launch Background Worker
+```bash
+npx claude-flow-novice agent backlog-worker \
+  --epic-id "epic-auth-001" --priority "P3" --background \
+  --log-file "/tmp/backlog-worker-$(date +%s).log" > /dev/null 2>&1 &
+echo $! > /tmp/backlog-worker.pid
+```
+
+### Worker Logic
+1. Fetch P3 items: `redis-cli SMEMBERS "epic:${EPIC_ID}:backlog:P3"`
+2. For each item:
+   - Mark in_progress: `redis-cli HSET "backlog:${ID}" status "in_progress"`
+   - Spawn CFN Loop: `npx claude-flow-novice swarm "$DESC" --mode mvp --background`
+   - Monitor: `redis-cli BLPOP "swarm:${TASK_ID}:complete" 300`
+   - Mark complete: `redis-cli HSET "backlog:${ID}" status "complete"`
+3. Update Redis every 5 min: `redis-cli HSET "backlog:worker:status" processed "$N"`
+
+### Monitor Progress
+```bash
+redis-cli HGETALL "backlog:worker:status"  # Check status
+tail -f /tmp/backlog-worker-*.log          # View logs
+kill $(cat /tmp/backlog-worker.pid)        # Stop worker
+```
+
+### Safety Mechanisms
+- Max 3 concurrent items, 10-min timeout per item, 2-hour max runtime
+- Redis locks: `redis-cli SET "backlog:${ID}:lock" "worker-$$" EX 600 NX`
+- Manual recovery: Reset stuck items to "pending"
+
+---
+
+## Task Mode Examples
+
+### Example 1: Simple Backend API
+```javascript
+Task("cfn-v3-coordinator", `
+  CFN LOOP TASK MODE - User Profile API
+
+  Complexity: Simple (2 files, ~150 LOC)
+  Loop 3: backend-dev
+  Loop 2: reviewer, tester
+  Consensus: 0.85
+
+  Acceptance:
+  - [ ] GET /profile/:id works
+  - [ ] PUT /profile/:id works
+  - [ ] Tests pass (>80%)
+
+  On Complete: git commit + push + generate docs/SPRINT_1_COMPLETE.md
+`)
+```
+
+### Example 2: Complex Full-Stack
+```javascript
+Task("cfn-v3-coordinator", `
+  CFN LOOP TASK MODE - JWT Authentication
+
+  Complexity: Complex (8 files, ~800 LOC, security-critical)
+  Loop 3: backend-dev, react-frontend-engineer, devops
+  Loop 2: reviewer, tester, architect, security-specialist
+  Consensus: 0.92
+
+  Acceptance:
+  - [ ] JWT generation/validation working
+  - [ ] Refresh token rotation
+  - [ ] Security audit passed
+
+  Backlog: Auto-defer OAuth/MFA as P2
+  On Complete: Security scan + git commit + push + sprint summary
+`)
+```
+
+### Example 3: Background Backlog
+```javascript
+// Foreground: Sprint 2
+Task("cfn-v3-coordinator", `Sprint 2: Authorization & RBAC`)
+
+// Background: Process P3 backlog
+Bash(`
+  npx claude-flow-novice agent backlog-worker \
+    --epic-id "epic-auth-001" --priority "P3" --background \
+    > /dev/null 2>&1 & echo $! > /tmp/backlog-worker.pid
+`, "Launch backlog worker")
+
+// Check progress anytime
+Bash(`redis-cli HGETALL "backlog:worker:status"`, "Check progress")
+```
+
+---
+
+## Quick Reference
+
+### Validator Selection Heuristics
+```
+Simple (1-2 files, <200 LOC): reviewer, tester
+Standard (3-5 files, 200-500 LOC): +architect, +security-specialist
+Complex/Enterprise (>5 files, >500 LOC): +code-analyzer
+  IF performance-critical → +performance-benchmarker
+  IF frontend (react/vue/angular/ui) → +accessibility-advocate-persona
+```
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Low consensus | Add specialized validator or stricter acceptance criteria |
+| Git push fails | Check remote: `git remote -v && git fetch origin` |
+| Backlog worker stuck | Reset items: `redis-cli HSET "backlog:${ID}" status "pending"`, restart worker |
+| Too many validators | Reduce count to 3-4 or lower threshold by 0.02-0.04 |
+
+### Complexity Analysis CLI
+```bash
+./.claude/skills/task-complexity/analyze.sh --task "$DESC" --files "$LIST"
+# Output: {"score": 85, "category": "standard", "validators": ["reviewer","tester","architect","security-specialist"], "threshold": 0.90}
+```
+
+---
+
+## Related Documentation
+
+- **CFN Coordinator Parameters**: `.claude/commands/cfn/CFN_COORDINATOR_PARAMETERS.md`
+- **Redis Coordination**: `.claude/skills/cfn-redis-coordination/SKILL.md`
+- **Product Owner Decision**: `.claude/skills/cfn-product-owner-decision/SKILL.md`
+- **Agent Output Standards**: `docs/AGENT_OUTPUT_STANDARDS.md`
+
+---
+
+**Version:** 1.0.0 (2025-10-28) - Task mode guide: agent specialization, sprint workflow, backlog, adaptive scaling, background processing

package/claude-assets/commands/cfn/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-assets/commands/cfn/auto-compact.md

@@ -0,0 +1,80 @@
+---
+description: "Compact conversation history to reduce token usage and maintain context efficiency"
+argument-hint: "[--focus=<topic>] [--threshold=<percentage>]"
+allowed-tools: ["Read", "Write", "Bash", "TodoWrite"]
+---
+
+# Auto-Compact - Programmatic Context Compression
+
+Summarize and compress conversation history while preserving key facts, decisions, and context.
+
+**Task**: $ARGUMENTS
+
+## Command Options
+
+```bash
+/auto-compact
+/auto-compact --focus="security decisions and API changes"
+/auto-compact --threshold=70
+/auto-compact --focus="CFN Loop implementation" --threshold=75
+```
+
+**Options:**
+- `--focus=<topic>`: Focus summarization on specific topics (optional)
+- `--threshold=<percentage>`: Token usage threshold to trigger compact (default: 70)
+
+## Current Session Analysis
+
+**Token Usage**: Check current context usage and determine if compaction is needed.
+
+## Compaction Strategy
+
+### What to Preserve
+- Key architectural decisions
+- Active task progress and todos
+- Critical bug fixes and security changes
+- Recent consensus validations
+- Current phase/sprint context
+
+### What to Compress
+- Verbose implementation details
+- Exploratory discussions
+- Resolved issues and completed tasks
+- Historical context from earlier phases
+- Redundant explanations
+
+## Execution Steps
+
+1. **Analyze Current Context**: Review token usage and conversation flow
+2. **Extract Key Facts**: Identify critical decisions, active work, and essential context
+3. **Generate Summary**: Create concise summary preserving:
+   - Active tasks and blockers
+   - Recent decisions (last 10-20% of conversation)
+   - Phase/sprint progress
+   - Technical debt items
+   - Next steps
+4. **Recommend Action**: Suggest when user should run `/compact` with optimal focus
+
+## Output Format
+
+```
+📊 **Context Analysis**
+- Current tokens: X/200k (Y%)
+- Recommendation: [COMPACT NOW | DEFER | MONITOR]
+
+🎯 **Suggested Compact Focus**
+[Generated focus string based on conversation]
+
+💡 **Summary Preview**
+[Key facts to preserve in compact]
+
+✅ **Action Required**
+Run: /compact focus: "[generated focus]"
+```
+
+## Notes
+
+- This command **analyzes** and **recommends** compaction
+- User must manually run `/compact` (built-in command)
+- Threshold default: 70% (140k/200k tokens)
+- Auto-triggered at 95% by Claude Code built-in