claude-flow-novice 2.18.23 → 2.18.24

package/.claude/CLAUDE.md

@@ -0,0 +1,17 @@
+# CFN Coordination and Namespace Guide
+
+## Coordination Patterns and Namespace Isolation
+
+- Coordination patterns: see `.claude/skills/cfn-coordination/SKILL.md` (chain, broadcast, mesh, consensus collection).
+- Namespace structure: agents `.claude/agents/cfn-dev-team/`; skills `.claude/skills/cfn-*/`; hooks `.claude/hooks/cfn-*`; commands `.claude/commands/cfn/`.
+- Enhanced orchestrator v3.0: `./.claude/skills/cfn-loop-orchestration/orchestrate.sh`
+- Orchestration flow: Loop 3 executes and tests -> gate check -> Loop 2 validators -> Product Owner decision (PROCEED/ITERATE/ABORT) -> iterate or finish.
+- Task mode agents: return output directly; no Redis signaling.
+
+### Coordination Anti-Patterns (avoid)
+
+- Skipping gate check before spawning Loop 2.
+- Validators reviewing without tests/logs.
+- Product Owner decision without deliverable paths.
+- Mixing service and container names inside Docker networks.
+- Manual cleanup instead of orchestrator controls.

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

@@ -265,6 +265,15 @@ The orchestrator returns structured results:
 }
 ```
 
+## Validation Flow Summary
+
+1. **Loop 3 Gate:** Test pass rate must meet mode threshold before validators start
+2. **Loop 2 Validators:** Need access to Loop 3 outputs, tests, and logs
+3. **Product Owner Decision:** Parsed via `.claude/skills/product-owner-decision/execute-decision.sh`
+4. **Gate Failure:** Iterate Loop 3 only
+5. **Gate Pass:** Proceed to validators
+6. **Decision Outcomes:** PROCEED (done), ITERATE (repeat), ABORT (stop with error)
+
 This simplified architecture provides:
 - ✅ **Zero external dependencies** - runs anywhere Node.js is available
 - ✅ **Fast execution** - parallel decomposition and implementation

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

@@ -249,6 +249,17 @@ fi
 
 ---
 
+## Validation Flow Summary
+
+1. **Loop 3 Gate:** Test pass rate must meet mode threshold before validators start
+2. **Loop 2 Validators:** Need access to Loop 3 outputs, tests, and logs
+3. **Product Owner Decision:** Parsed via `.claude/skills/product-owner-decision/execute-decision.sh`
+4. **Gate Failure:** Iterate Loop 3 only
+5. **Gate Pass:** Proceed to validators
+6. **Decision Outcomes:** PROCEED (done), ITERATE (repeat), ABORT (stop with error)
+
+---
+
 ## Related Documentation
 
 - **Full Task Mode Guide**: `.claude/commands/cfn-loop/cfn-loop-task.md`

package/.claude/commands/cfn-ruvector/cfn-codebase-reindex.md

@@ -17,20 +17,39 @@ Add `--force` flag for complete reindex:
 - Major restructuring
 - Index issues
 
-**Prerequisites:**
-- OPENAI_API_KEY must be set: `export OPENAI_API_KEY="sk-..."`
+**Log file:** `/tmp/ruvector-index.log` - tail this for progress monitoring.
 
 ---
 
 Execute reindex:
 
 ```bash
+# --- FAIL-FAST: Validate OpenAI API Key ---
+# Always load from .env if current key is invalid (placeholder or missing)
+if [[ ! "$OPENAI_API_KEY" =~ ^sk- ]] && [[ -f ".env" ]]; then
+    export OPENAI_API_KEY=$(grep "^OPENAI_API_KEY=" .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
+fi
+
+# Final validation
+if [[ ! "$OPENAI_API_KEY" =~ ^sk- ]]; then
+    echo "❌ FATAL: Valid OPENAI_API_KEY not found." >&2
+    echo "   Add to .env: OPENAI_API_KEY=sk-..." >&2
+    exit 1
+fi
+
+echo "✅ OpenAI key: ${OPENAI_API_KEY:0:12}..."
+
+# --- Setup ---
 RUVECTOR_BIN="${HOME}/.local/bin/local-ruvector"
 [ ! -f "$RUVECTOR_BIN" ] && RUVECTOR_BIN="./.claude/skills/cfn-local-ruvector-accelerator/target/release/local-ruvector"
+LOG_FILE="/tmp/ruvector-index.log"
+
+echo "📝 Logging to: $LOG_FILE"
+echo "   Monitor with: tail -f $LOG_FILE"
 
 # Incremental (default - only changed files)
-"$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md
+"$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md 2>&1 | tee "$LOG_FILE"
 
 # Full rebuild (when needed)
-# "$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md --force
+# "$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md --force 2>&1 | tee "$LOG_FILE"
 ```

package/.claude/commands/cfn-ruvector/cfn-codebase-search.md

@@ -19,7 +19,7 @@ Search your indexed codebase using RuVector. Uses SQLite index for fast lookups.
 - `/cfn-ruvector:cfn-codebase-search database migration`
 
 **Prerequisites:**
-- Codebase must be indexed: `./local-ruvector index --path . --force`
+- Codebase must be indexed: `/cfn-codebase-reindex`
 - OPENAI_API_KEY must be set for indexing
 
 ---
@@ -27,7 +27,15 @@ Search your indexed codebase using RuVector. Uses SQLite index for fast lookups.
 Execute the search:
 
 ```bash
+# Load from .env if current key is invalid
+if [[ ! "$OPENAI_API_KEY" =~ ^sk- ]] && [[ -f ".env" ]]; then
+    export OPENAI_API_KEY=$(grep "^OPENAI_API_KEY=" .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
+fi
+[[ ! "$OPENAI_API_KEY" =~ ^sk- ]] && { echo "❌ OPENAI_API_KEY invalid. Add to .env" >&2; exit 1; }
+
 RUVECTOR_BIN="${HOME}/.local/bin/local-ruvector"
 [ ! -f "$RUVECTOR_BIN" ] && RUVECTOR_BIN="./.claude/skills/cfn-local-ruvector-accelerator/target/release/local-ruvector"
-"$RUVECTOR_BIN" query "{{query}}" --max-results {{#if top}}{{top}}{{else}}10{{/if}}
+
+# Use threshold 0.1 for better results (default 0.3 is too strict)
+"$RUVECTOR_BIN" query "{{query}}" --max-results {{#if top}}{{top}}{{else}}10{{/if}} --threshold 0.1
 ```

package/.claude/commands/cfn-ruvector/cfn-detect-stale-docs.md

@@ -29,13 +29,31 @@ Analyzes all `.md` files in the codebase to detect legacy/outdated documentation
 - Score 2-4: **POSSIBLY STALE** (minor issues)
 
 **Prerequisites:**
-- Codebase must be indexed first (`/codebase-reindex`)
-- ZAI_API_KEY must be set (for semantic search)
+- Codebase must be indexed first (`/cfn-codebase-reindex`)
+- OPENAI_API_KEY must be set (for semantic search)
 
 ---
 
-Run the stale documentation detector:
+**Note:** This is a planned feature. Currently use these manual queries:
 
 ```bash
-./.claude/skills/cfn-ruvector-codebase-index/detect-stale-docs.sh
+# Find docs older than 90 days with no recent code references
+sqlite3 ~/.local/share/ruvector/index_v2.db "
+SELECT e.file_path, e.name,
+       datetime(e.created_at, 'unixepoch') as indexed_at
+FROM entities e
+WHERE e.file_path LIKE '%.md'
+  AND e.project_root LIKE '%$(pwd)%'
+  AND (e.name LIKE '%legacy%' OR e.name LIKE '%deprecated%' OR e.name LIKE '%old%')
+LIMIT 20;"
+
+# Find orphan docs (no references)
+sqlite3 ~/.local/share/ruvector/index_v2.db "
+SELECT DISTINCT e.file_path
+FROM entities e
+LEFT JOIN refs r ON e.id = r.source_entity_id OR e.id = r.target_entity_id
+WHERE e.file_path LIKE '%.md'
+  AND e.project_root LIKE '%$(pwd)%'
+  AND r.id IS NULL
+LIMIT 20;"
 ```

package/.claude/hooks/deprecated/cfn-SessionStart-cfn-load-openai-key.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# SessionStart hook: Load OpenAI API key from root .env file
+# This ensures OPENAI_API_KEY is available for embedding generation
+#
+# IMPORTANT: SessionStart hooks must write to CLAUDE_ENV_FILE to set env vars.
+# JSON output and 'export' do NOT work - only CLAUDE_ENV_FILE persists.
+
+set -e
+
+# Path to root .env file
+ROOT_ENV="${PROJECT_ROOT:-.}/.env"
+
+# Check if CLAUDE_ENV_FILE is available (only in SessionStart hooks)
+if [[ -z "$CLAUDE_ENV_FILE" ]]; then
+    echo "⚠️  CLAUDE_ENV_FILE not set - not running as SessionStart hook" >&2
+    exit 0
+fi
+
+# Check if .env exists
+if [[ ! -f "$ROOT_ENV" ]]; then
+    echo "⚠️  Warning: $ROOT_ENV not found. OpenAI embeddings will not work." >&2
+    exit 0
+fi
+
+# Extract OPENAI_API_KEY from .env
+if grep -q "^OPENAI_API_KEY=" "$ROOT_ENV"; then
+    OPENAI_KEY=$(grep "^OPENAI_API_KEY=" "$ROOT_ENV" | cut -d'=' -f2- | tr -d '"' | tr -d "'")
+
+    # Validate key format
+    if [[ -z "$OPENAI_KEY" ]]; then
+        echo "⚠️  Warning: OPENAI_API_KEY found but empty in $ROOT_ENV" >&2
+        exit 0
+    fi
+
+    if [[ ! "$OPENAI_KEY" =~ ^sk- ]]; then
+        echo "⚠️  Warning: OPENAI_API_KEY invalid format (must start with 'sk-')" >&2
+        exit 0
+    fi
+
+    # Write to CLAUDE_ENV_FILE - this is how SessionStart hooks set env vars
+    echo "export OPENAI_API_KEY=\"$OPENAI_KEY\"" >> "$CLAUDE_ENV_FILE"
+    echo "✅ Loaded OPENAI_API_KEY from .env (${OPENAI_KEY:0:10}...)" >&2
+else
+    echo "⚠️  Warning: OPENAI_API_KEY not found in $ROOT_ENV. OpenAI embeddings will not work." >&2
+fi
+
+exit 0

package/.claude/settings.json

@@ -153,23 +153,21 @@
       }
     ],
     "SessionStart": [
-      {
+      {        
+        "matcher": "startup",
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'echo \"[SessionStart] Initializing session context...\" >&2; if [ -f \"./.claude/hooks/cfn-load-cerebras-env.sh\" ]; then RESULT=$(./.claude/hooks/cfn-load-cerebras-env.sh 2>&1); if echo \"$RESULT\" | jq . >/dev/null 2>&1; then echo \"$RESULT\"; else echo \"$RESULT\" >&2; fi; fi; if [ -f \"./.claude/skills/cfn-memory-persistence/lib/auto/auto-load-session-context.sh\" ]; then ./.claude/skills/cfn-memory-persistence/lib/auto/auto-load-session-context.sh --session-id \"${SESSION_ID:-$(date +%s)}\" 2>&1 || true; fi; if [ -f \"./.claude/skills/cfn-transparency-middleware/invoke-transparency-init.sh\" ]; then ./.claude/skills/cfn-transparency-middleware/invoke-transparency-init.sh --task-id \"${SESSION_ID:-session}\" --level standard 2>&1 || true; fi; echo \"[SessionStart] Context loaded\" >&2; exit 0'",
-            "timeout": 15
+            "command": "nohup ~/.local/bin/wsl-memory-monitor.sh > /dev/null 2>&1 & sleep 0.5 && echo \"[WSL Memory Monitor] Running (PID: $(cat /tmp/wsl-memory-monitor.pid 2>/dev/null || echo starting))\""
           }
         ]
-      }
-    ],
-    "Stop": [
+      },
       {
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'echo \"[SessionEnd] Persisting session state...\" >&2; if [ -f \"./.claude/skills/cfn-memory-persistence/lib/auto/save-session-context.sh\" ]; then ./.claude/skills/cfn-memory-persistence/lib/auto/save-session-context.sh --session-id \"${SESSION_ID:-$(date +%s)}\" 2>&1 || true; fi; if [ -f \"./.claude/skills/cfn-knowledge-base/cli/knowledge-base.sh\" ]; then ./.claude/skills/cfn-knowledge-base/cli/knowledge-base.sh store-learning --type session-end --category completed --confidence 0.85 2>&1 || true; fi; echo \"[SessionEnd] Session ended\" >&2; exit 0'",
-            "timeout": 15
+            "command": "bash .claude/hooks/cfn-SessionStart-cfn-build-ruvector.sh",
+            "timeout": 60
           }
         ]
       }

package/.claude/skills/CLAUDE.md

@@ -0,0 +1,70 @@
+# Claude Code Skills Development Guide
+
+**Purpose:** Guidelines for developing, testing, and maintaining CFN skills.
+
+---
+
+## Skill Development Principles
+
+- **Modularity:** Each skill handles one responsibility; compose skills for complex operations
+- **Explicit Interfaces:** Document inputs, outputs, and side effects in SKILL.md
+- **Minimal Dependencies:** Skills should be self-contained; avoid cross-skill imports
+- **Thorough Testing:** Every skill needs functional tests and edge case coverage
+
+## Testing Requirements (STRAT-005)
+
+Skills must include tests covering:
+- Functional requirements (happy path)
+- Edge cases: timeouts, blocking operations, invalid inputs
+- Resource cleanup on failure
+
+**Example test location:** `.claude/skills/cfn-coordination/test-orchestrator.sh`
+
+## Core Skill References
+
+- **Coordination:** `.claude/skills/cfn-coordination/SKILL.md` - chain, broadcast, mesh, consensus patterns
+- **Agent Spawning:** `.claude/skills/cfn-agent-spawning/SKILL.md` - agent lifecycle management
+- **Loop Validation:** `.claude/skills/cfn-loop-validation/SKILL.md` - gate checks and consensus
+
+## Skill File Structure
+
+```
+.claude/skills/<skill-name>/
+├── SKILL.md           # Skill documentation (required)
+├── <main-script>.sh   # Primary entry point
+├── lib/               # Helper scripts/modules
+└── tests/             # Skill-specific tests
+```
+
+## Skill Documentation Template
+
+```markdown
+# Skill: <name>
+
+## Purpose
+One-line description of what this skill does.
+
+## Inputs
+- `$1`: Description
+- `ENV_VAR`: Description
+
+## Outputs
+- stdout: Description
+- exit code: 0 = success, non-zero = failure
+
+## Usage
+\`\`\`bash
+./.claude/skills/<skill-name>/<script>.sh [args]
+\`\`\`
+
+## Dependencies
+- List required tools/skills
+```
+
+## Quality Checklist
+
+- [ ] SKILL.md documents all inputs/outputs
+- [ ] Scripts use `set -euo pipefail`
+- [ ] Cleanup traps handle interrupts
+- [ ] Tests cover happy path and failure modes
+- [ ] No hardcoded paths (use `PROJECT_ROOT`)

package/.claude/skills/cfn-local-ruvector-accelerator/SKILL.md

@@ -1,25 +1,41 @@
+---
+name: ruvector-code-search
+description: "MANDATORY: Query RuVector BEFORE using grep, glob, find, or search. Performs 400x faster semantic and structural code search via SQL on indexed codebase. Use for finding functions, classes, patterns, callers, and implementations. Agents MUST query RuVector first; grep is only allowed after RuVector returns zero results."
+allowed-tools: Bash, Read, SlashCommand
+---
+
 # RuVector Local Semantic Code Search
 
-## WHEN TO USE THIS SKILL
+## MANDATORY: QUERY RUVECTOR BEFORE GREP/GLOB
+
+**This is a PROTOCOL REQUIREMENT, not a suggestion. Failure to query RuVector first is a violation.**
+
+### WHY THIS IS MANDATORY
+- RuVector SQL: 0.002s | grep: 0.8s (400x slower)
+- Agents using grep first waste tokens and time
+- Index already exists at `~/.local/share/ruvector/index_v2.db`
 
-**USE RuVector V2 SQL for ALL indexed projects (400x FASTER than grep):**
+### ALWAYS USE RUVECTOR FIRST
 ```bash
-# Exact name lookup - 0.002s vs grep's 0.8s
+# Exact name lookup - 0.002s
 sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT file_path, line_number FROM entities WHERE name = 'MyFunction';"
 
 # Fuzzy search - 0.004s
 sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT file_path, line_number FROM entities WHERE name LIKE '%Store%' LIMIT 10;"
+
+# Semantic search
+/codebase-search "authentication middleware pattern"
 ```
 
-**USE grep/rg ONLY when:**
-- Project is NOT indexed yet
-- Searching for strings that aren't code entities (error messages, comments, config values)
-- Quick one-off search in small directory
+### GREP IS ONLY ALLOWED WHEN:
+- RuVector query returned zero results AND project confirmed not indexed
+- Searching literal strings (error messages, comments, config values)
+- Explicit user request for grep
 
-**USE RuVector semantic search when:**
-- "Where is authentication implemented?" (conceptual search)
-- Finding similar patterns you can't name exactly
-- Discovering how a feature is built
+### FOR CONCEPTUAL QUESTIONS:
+- "Where is X implemented?" → RuVector semantic search
+- "Find similar patterns" → RuVector embeddings
+- "How is feature Y built?" → RuVector first, then read files
 
 ## Quick Commands
 
@@ -108,20 +124,20 @@ sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT project_root, COUNT(*) FROM
 ~/.local/share/ruvector/index_v2.db
 ```
 
-## For Agents
+## For Agents (MANDATORY PROTOCOL)
+
+**DO NOT use grep/glob until you have queried RuVector. This is enforced.**
 
-Before implementing changes, ALWAYS query RuVector first:
 ```bash
-# Find similar patterns (slash command uses --top, CLI uses --max-results)
+# STEP 1: Query RuVector FIRST (required)
 /codebase-search "relevant search terms" --top 5
-# Or via CLI:
-local-ruvector query "relevant search terms" --max-results 5
+# Or SQL:
+sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT file_path, line_number FROM entities WHERE name LIKE '%keyword%';"
 
-# Query past errors
-./.claude/skills/cfn-ruvector-codebase-index/query-error-patterns.sh --task-description "description"
+# STEP 2: Query past errors/patterns
+./.claude/skills/cfn-local-ruvector-accelerator/query-agent-patterns.sh "description"
 
-# Query learnings
-./.claude/skills/cfn-ruvector-codebase-index/query-learnings.sh --task-description "description" --category PATTERN
+# STEP 3: Only if RuVector returns nothing, then use grep
 ```
 
-This prevents duplicated work and leverages existing solutions.
+**Violation of this protocol wastes tokens and time. RuVector exists to prevent duplicated work.**

package/CLAUDE.md

@@ -1,423 +1,85 @@
-# Claude Flow Novice - Operating Guide
----
+# CFN Operating Guide
 
-Purpose: concise reference for CFN agents. Focus on persona, mandatory rules, edit workflow, loop mode selection, Docker/test requirements, and key links. Target size: 300-500 lines; keep lean and actionable.
+## Docs
 
-## 0) Scope and Pointers
-- Use this file for general development and coordination rules.
-- CFN architecture and loop internals: `cfn-system-expert.md`.
-- Dependency ingestion specifics: `.claude/skills/cfn-dependency-ingestion/SKILL.md`.
-- CLI loop details: `.claude/agents/custom/cfn-loops-cli-expert.md`, `planning/cli-changes-november/CLI_MODE_REDIS_COORDINATION_HANDOFF.md`.
-- Keep responses terse; redact sensitive info as `[REDACTED]`.
+| Topic | Path |
+|-------|------|
+| CLI Mode | `docs/CFN_LOOP_CLI_MODE.md` |
+| Tests | `tests/CLAUDE.md` |
+| Skills | `.claude/skills/CLAUDE.md` |
+| Coordination | `.claude/CLAUDE.md` |
+| Architecture | `cfn-system-expert.md` |
 
-## 1) Persona and Output Tone
-- Act as a busy CTO peer: delegate non-trivial work, speak plainly, no fluff.
-- Provide context and success criteria; let agents choose implementation.
-- Success = implemented, tested, documented. Do not add adoption/rollout criteria.
-- Prefer spartan language; code/examples only when requested.
-- Avoid long summaries; focus on decisions, risks, and next actions.
+## Style
 
-## 2) Core Operational Rules
-- Use agents/CFN Loops for non-trivial tasks: multi-step, multi-file, research, testing, security, integration, refactor, or feature work.
-- Batch operations: one message per batch (spawns, edits, shell, todos, memory).
-- Never mix implementers and validators in one message.
-- Do not run tests inside agents; run once via coordinator/main chat, agents read results.
-- **ANTI-024: Never run test commands with `run_in_background: true`** - orphaned test processes cause memory leaks. Always run tests synchronously. If tests hang, investigate; don't background them.
-- Never save to project root; use appropriate subdirectories.
-- Never hardcode secrets; always redact as `[REDACTED]`.
-- Use RuVector SQL for indexed projects (400x faster than grep); use grep only for non-indexed projects or non-code strings.
-- When monitoring, sleep-check-sleep loops.
-- All agent communication must use coordination protocols; no ad-hoc file coordination.
-- Run `./.claude/cfn-scripts/check-memory.sh` periodically to detect orphaned test processes; use `--kill` to clean them up.
+Speak plainly, no fluff. Bullets > prose. Cite paths with line numbers (`src/app.ts:42`). Redact secrets as `[REDACTED]`.
 
-## 3) Cerebras MCP & Context Discovery Protocols
+## Rules
 
-### Cerebras MCP Usage (when `mcp__cerebras-mcp__write` available)
-**RULE: Prompt must be SHORTER than expected output.**
+- **RuVector FIRST (MANDATORY):** Query `.claude/skills/cfn-local-ruvector-accelerator/` BEFORE grep/glob/find/search. SQL queries are 400x faster. Use grep ONLY for non-indexed projects or literal strings. Failure to use RuVector first is a protocol violation.
+- **Agent usage:** Non-trivial tasks → CFN Loop. Solo work only for simple, isolated, <3 step tasks.
+- **Batching:** One message per type (spawns, edits, shell, todos). Never mix implementers + validators.
+- **Tests:** Coordinator only, sync execution. Never `run_in_background: true`. Agents read results.
+- **Files:** Subdirs only, never project root. Temp files → `/tmp/`.
+- **Secrets:** Never hardcode. Always redact.
 
-Use STRUCTURED BLUEPRINTS, not prose:
-```
-Function: validateEmail(email: string): boolean
-- Regex: /^[^@]+@[^@]+\.[^@]+$/
-- Return: true if match, false otherwise
-```
-
-**BAD**: "I need you to create a function that validates email addresses..."
-**GOOD**: "Function: validateEmail(email: string): boolean\n- Regex test\n- Return boolean"
-
-Always provide `context_files` when code needs imports from existing files.
-
-### Context Discovery Priority (fastest to slowest)
-1. **RuVector semantic search** (for "where is X?" queries):
-   - **Centralized index:** `~/.local/share/ruvector/index_v2.db` (shared across all projects)
-   - **Dual storage:** V1 (semantic/fuzzy) + V2 (structural/SQL)
-   - **V1 queries:** "Find similar code" via vector embeddings (cosine similarity)
-   - **V2 queries:** "Find callers/refs" via SQL on AST entities
-   ```bash
-   # Semantic search
-   /codebase-search "authentication middleware pattern"
-   local-ruvector query --pattern "auth"
-
-   # Structural SQL query
-   sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT * FROM refs WHERE target_name = 'MyFunction';"
-   ```
-2. **Query past errors** before similar work:
-   ```bash
-   ./.claude/skills/cfn-ruvector-codebase-index/query-error-patterns.sh --task-description "description"
-   ```
-3. **Query learnings** for best practices:
-   ```bash
-   ./.claude/skills/cfn-ruvector-codebase-index/query-learnings.sh --task-description "description" --category PATTERN
-   ```
-4. **Grep** only for exact string/symbol matches
-5. **Glob** only for known file patterns (`**/*.test.ts`)
-
-### MDAP Execution Context (when `enableMDAP=true`)
-Applies only in Trigger.dev MDAP mode:
-- Single file only (path provided by decomposer)
-- Target: <50 lines of code, atomic task
-- No file discovery (context pre-injected)
-- Return structured JSON: `{"success": true, "filePath": "...", "linesWritten": N, "confidence": 0.9}`
-
-→ Full protocols: `.claude/agents/SHARED_PROTOCOL.md`
-
-## 4) Mandatory Edit Workflow
-- Pre-Edit Backup (required before any edit/write, including docs):
-  ```bash
-  BACKUP_PATH=$(./.claude/hooks/cfn-invoke-pre-edit.sh "$FILE_TO_EDIT" --agent-id "$AGENT_ID")
-  ```
-- Post-Edit Validation (run after every edit):
-  ```bash
-  ./.claude/hooks/cfn-invoke-post-edit.sh "$EDITED_FILE" --agent-id "$AGENT_ID"
-  ```
-- Revert via backups only (never `git checkout --`):
-  ```bash
-  ./.claude/skills/pre-edit-backup/revert-file.sh "$FILE_PATH" --agent-id "$AGENT_ID"
-  ```
-- Hooks are non-blocking; fix issues surfaced by post-edit. Keep backup paths for reference.
-
-## 5) When to Spawn Agents vs Work Solo
-- Use a single agent (Task) only for simple, isolated work.
-- Use coordinator/CFN Loop for: multi-agent needs, more than three steps, multi-file edits, design decisions, testing plus implementation, quality/security/performance/compliance, docs generation, system integration, or refactors.
-- Triggers to avoid solo work: feature work, cross-cutting changes, research plus implementation, code review/quality gates, or anything requiring validation.
-
-## 6) CFN Loop Modes (user chooses)
-- Default Task Mode:
-  - Command: `/cfn-loop-task "Task description" --mode=standard`
-  - Spawns all agents directly; full visibility; higher cost.
-  - Best for debugging, learning, or short tasks (<5 minutes).
-- CLI Mode (production default):
-  - Command: `/cfn-loop-cli "Task description" --mode=standard --provider kimi`
-  - Main chat spawns CLI agents directly; Redis BLPOP coordination; lower cost.
-  - Best for production, provider routing, and cost-sensitive work.
-- Mode guidance: phrases like "execute cfn loop" use task mode; "production cli" uses CLI mode.
-- Deprecated: manual Task() spawning for CLI workflows.
-
-### Task Mode Execution Steps
-1) Expand slash command; validate parameters.  
-2) Spawn required agents via Task() from main chat.  
-3) Provide context and success criteria; include lifecycle instructions if auditing.  
-4) Agents execute and return results; no Redis signaling.  
-5) Iterate or close based on validator/product owner feedback.
-
-### Slash Command Execution Rules (CLI mode)
-1) Expand slash command.  
-2) Immediately execute coordinator spawn via Bash tool using the exact command.  
-3) Do not merely show commands; run them.  
-4) Inform user after spawn with task ID.  
-Anti-patterns: pausing to ask what next, manual Task() for CLI workflows, skipping execution.
-
-### CLI Mode Execution Steps
-1) Expand slash command and validate required parameters (mode, optional provider).  
-2) Spawn coordinator via orchestration script; confirm task ID.  
-3) Loop 3 agents implement and run tests; orchestration monitors via Redis.  
-4) Gate check compares pass rate to mode threshold; if failing, iterate Loop 3.  
-5) If gate passes, Loop 2 validators review and score.  
-6) Product Owner agent decides PROCEED/ITERATE/ABORT; orchestrator enforces.  
-7) Report final status, code paths, test results; stop agents cleanly.
-
-## 7) Provider Routing (optional)
-- Enable custom routing: set `CFN_CUSTOM_ROUTING=true` in `.env`.
-- Provider options: `zai` (default, cost), `kimi` (balanced), `openrouter` (broad access), `max` or `anthropic` (premium), `gemini`, `xai`.
-- Agents without provider parameters default to Z.ai glm-4.6 when custom routing is on.
-- Example flow: `/switch-api kimi` then `/cfn-loop-cli "Feature" --provider kimi`.
-- Full guide: `docs/CUSTOM_PROVIDER_ROUTING.md`.
-
-### Provider Selection Hints
-- Cost sensitive: `zai` or low-tier `openrouter`.
-- Balanced quality/cost: `kimi`.
-- Highest quality/safety: `max` or `anthropic`.
-- Google ecosystem: `gemini`.
-- XAi/Grok style: `xai`.
-- Mixed providers: set per-agent profile; otherwise inherit main chat provider.
-
-## 8) Docker Build Requirements (WSL2)
-- Always build from Linux-native storage; do not build from Windows mounts.
-- Use scripts, not raw `docker build`:
-  - Preferred: `./.claude/skills/docker-build/build.sh --dockerfile docker/Dockerfile.agent --tag cfn-agent:latest`
-  - Manual: `DOCKERFILE="docker/Dockerfile.agent" IMAGE_NAME="cfn-agent" ./scripts/docker/build-from-linux.sh`
-- Windows mount builds are ~755s vs <20s from Linux. All CFN images must use Linux builds.
-- Dockerfiles should note the Linux build requirement; docker-specialist must comply.
-
-### Docker Build Checklist
-- [ ] Source tree on Linux filesystem (not Windows mount).  
-- [ ] Use build script, not `docker build`.  
-- [ ] Confirm Dockerfile path and tag arguments.  
-- [ ] Clean `/tmp/cfn-build` if space issues.  
-- [ ] Document build command and outputs when reporting failures.  
-- [ ] If builds are slow, verify you are not running from a Windows path.
-
-## 9) Multi-Worktree Docker Coordination
-- One git worktree per developer; isolation via `COMPOSE_PROJECT_NAME`.
-- Port offsets auto-calculated with `run-in-worktree.sh` to avoid conflicts.
-- Required environment variables when spawning agents:
-  ```bash
-  export COMPOSE_PROJECT_NAME="cfn-${BRANCH}"
-  export CFN_REDIS_PORT="${CFN_REDIS_PORT}"
-  export CFN_POSTGRES_PORT="${CFN_POSTGRES_PORT}"
-  export WORKTREE_BRANCH="${BRANCH}"
-  ```
-- Use service names inside Docker networks: `redis`, `postgres`, `orchestrator` (not container names).
-- Checklist: start stack with `./scripts/docker/run-in-worktree.sh up -d`; isolate Redis keys by task IDs; avoid shared volumes; use service names only.
-- Port examples: main (6379/5432/3001); feature-auth (~6421/5474/3043); bugfix-validation (~6457/5510/3079).
-
-### Multi-Worktree Playbook
-1) Create or enter worktree with branch-specific name.  
-2) Run `./scripts/docker/run-in-worktree.sh up -d` to start services.  
-3) Export project/port env vars before spawning agents.  
-4) Connect using service names inside the network; from host, use offset ports.  
-5) Tear down with `./scripts/docker/run-in-worktree.sh down` and prune networks if needed.
-
-## 10) Task Mode SQLite Lifecycle (audited tasks)
-- Use when Task agents need an audit trail without Redis.
-- Template:
-  ```javascript
-  Task("docker-specialist", `
-    LIFECYCLE:
-    AGENT_ID="docker-$(date +%s)-$$"
-    sqlite3 "./claude-assets/skills/cfn-redis-coordination/data/cfn-loop.db" \
-      "CREATE TABLE IF NOT EXISTS agents (...);" && \
-    sqlite3 "$DB_PATH" "INSERT OR REPLACE INTO agents (...);"
-    # complete task
-    sqlite3 "$DB_PATH" "UPDATE agents SET status='completed', confidence=<0.85-0.95>, completed_at=datetime('now') WHERE id='$AGENT_ID';"
-  `)
-  ```
-- Database path: `./claude-assets/skills/cfn-redis-coordination/data/cfn-loop.db`.
-- Table schema: `id, type, status, confidence, spawned_at, completed_at, metadata`.
-- Do not include Redis/CLI commands in Task mode prompts; SQLite only.
+## Edit Workflow
 
-### Lifecycle Notes
-- Confidence values for auditing typically 0.85-0.95.  
-- Ensure `sqlite3` is installed; fail fast otherwise.  
-- Keep lifecycle instructions concise and ahead of the task request.  
-- Clean up stale audit rows if the table grows; retention per project policy.
-
-## 11) Coordination Patterns and Namespace Isolation
-- Coordination patterns: see `.claude/skills/cfn-coordination/SKILL.md` (chain, broadcast, mesh, consensus collection).
-- Namespace structure: agents `.claude/agents/cfn-dev-team/`; skills `.claude/skills/cfn-*/`; hooks `.claude/hooks/cfn-*`; commands `.claude/commands/cfn/`.
-- Enhanced orchestrator v3.0: `./.claude/skills/cfn-loop-orchestration/orchestrate.sh` (monitors agents, restarts stuck ones, enforces protocols).
-- Orchestration flow: Loop 3 executes and tests -> gate check -> Loop 2 validators -> Product Owner decision (PROCEED/ITERATE/ABORT) -> iterate or finish.
-- Agent protocol (CLI): completion signaling via Redis, context validation, metadata tracking, health monitoring.
-- Task mode agents: return output directly; no Redis signaling.
-
-### Coordination Anti-Patterns (avoid)
-- Skipping gate check before spawning Loop 2.  
-- Validators reviewing without tests/logs.  
-- Product Owner decision without deliverable paths.  
-- Mixing service and container names inside Docker networks.  
-- Manual cleanup instead of orchestrator controls.
-
-## 12) Agent Output Standards
-- Bug docs: `docs/BUG_#_*.md` (investigation, fix, validation).
-- Test scripts: `tests/test-*.sh` (checked in).
-- Feature docs: `docs/FEATURE_NAME.md` (architecture/process).
-- Temporary files: `/tmp/` only.
-- Backlog items: `.claude/skills/cfn-backlog-management/add-backlog-item.sh` (item, reason, solution).
-- Changelog: `.claude/skills/cfn-changelog-management/add-changelog-entry.sh` (10-100 characters, sparse impact).
-- Full standards: `docs/AGENT_OUTPUT_STANDARDS.md`.
-
-## 13) Test Execution Guidance
-- Always run tests before committing: after features or bugfixes, agent behavior changes, CFN workflow changes.
-- Suites and timing:
-  - `npm test` (1-5 minutes, dev feedback)
-  - `npm run test:unit` (~1 minute)
-  - `npm run test:integration` (~2 minutes)
-  - `npm run test:e2e` (~5 minutes)
-  - `./tests/cli-mode/run-all-tests.sh` (5-10 minutes; validates `/cfn-loop-cli`)
-  - `./tests/docker-mode/run-all-implementations.sh` (3-5 minutes; 45 integration tests)
-  - `./tests/cfn-v3/test-e2e-cfn-loop.sh` (5-15 minutes; coordinator/orchestration)
-- Run CLI mode tests before commits touching agent spawning, coordination thresholds, or Redis patterns.
-- Run Docker suite before Docker-related changes or releases.
-- Test artifacts: `.artifacts/test-results/`, coverage `.artifacts/coverage/`, logs `.artifacts/logs/`, runtime `.artifacts/runtime/`.
-
-### Test-Driven Gates (v3.0+)
-- Loop 3 gate: pass rate must meet mode threshold before validators start.
-- Loop 2 consensus thresholds by mode:
-  - MVP: gate >= 0.70, consensus >= 0.80
-  - Standard: gate >= 0.95, consensus >= 0.90
-  - Enterprise: gate >= 0.98, consensus >= 0.95
-
-### Test Authoring Standards (tests/CLAUDE.md)
-- Use `#!/bin/bash` and `set -euo pipefail`; source `tests/test-utils.sh` immediately.
-- Structure with GIVEN/WHEN/THEN; use `log_step`, `log_info`, `annotate`, `assert_success`.
-- Always add a cleanup trap (docker rm, worktree prune, rm -rf temp).
-- Integration tests must use production code paths (spawn-agent.sh, production images, real CLI syntax, log checks).
-- Infrastructure tests may mock networking or Redis; integration tests must not.
-- Cite relevant bugs or references in test headers for traceability.
-
-### Troubleshooting Quick Fixes
-- Redis missing: `redis-server --daemonize yes` or docker `redis:7-alpine`.
-- Docker not running: start daemon (`systemctl start docker` or Docker.app).
-- Port conflicts: `docker stop $(docker ps -aq) && docker rm $(docker ps -aq) && docker network prune -f`.
-- Permissions: `usermod -aG docker $USER` then `newgrp docker`.
-- Verbose mode: `DEBUG=true ./tests/cli-mode/run-all-tests.sh`; inspect `.artifacts/logs/test-execution.log`.
-
-## 14) Quality and Skill Development
-- Skill guidelines: maximize modularity, explicit interfaces, minimal dependencies, thorough tests.
-- STRAT-005: cover functional requirements and edge cases (timeouts, blocking). Example: `.claude/skills/cfn-coordination/test-orchestrator.sh`.
-- Core skill references: `.claude/skills/cfn-coordination/SKILL.md`, `.claude/skills/cfn-agent-spawning/SKILL.md`, `.claude/skills/cfn-loop-validation/SKILL.md`.
-
-## 15) General Programming Best Practices
-- Regex validation: avoid self-matching patterns (`[[ $AGENTS =~ $AGENTS ]]`); use specific regexes.
-- Comprehensive file validation: check type, permissions, size, and content integrity.
-- Shell scripting: use strict mode `set -euo pipefail`; capture pipeline failures.
-- Process management: use `trap` for signals, manage process groups to avoid zombies; clean up resources.
-- Prefer explicit error handling and early exits to prevent cascading failures.
-
-## 16) Quick Reference: Do / Do Not
-- Do: delegate early, run backup hooks, keep responses concise, redact secrets, use service names, build Docker from Linux storage.
-- Do: gate by tests, cite bugs or references in tests, run appropriate suite before commits.
-- Do Not: skip pre-edit backup or post-edit hook; run tests inside agents; build Docker from Windows mounts; hardcode secrets; mix implementer and validator roles; save to project root.
-
-## 17) Key Files and Paths
-- Hooks: `./.claude/hooks/cfn-invoke-pre-edit.sh`, `./.claude/hooks/cfn-invoke-post-edit.sh`.
-- Backup revert: `./.claude/skills/pre-edit-backup/revert-file.sh`.
-- Orchestrator: `./.claude/skills/cfn-loop-orchestration/orchestrate.sh`.
-- Provider routing guide: `docs/CUSTOM_PROVIDER_ROUTING.md`.
-- Test guides: `tests/README.md`, `tests/CLAUDE.md`, `tests/cli-mode/README.md`, `tests/docker-mode/README.md`, `tests/TEST_COVERAGE_MATRIX.md`.
-- CFN Loop architecture: `docs/CFN_LOOP_ARCHITECTURE.md`.
-- CI/CD pipeline: `docker/CI_CD_TEST_INTEGRATION.md`.
-- Analytics: `.artifacts/analytics/context-reduction-report.json`.
-
-## 18) Execution Playbooks (quick recipes)
-- Implement feature (CLI mode):
-  1) `/cfn-loop-cli "Implement <feature>" --mode=standard --provider kimi`
-  2) Provide acceptance criteria and target paths; cite relevant docs.
-  3) After completion, report code paths and tests run; suggest final validation.
-- Debug bug (Task mode):
-  1) `/cfn-loop-task "Investigate bug <id>" --mode=standard`
-  2) Include repro steps and log paths; require root cause, fix, and tests.
-  3) Save output to `docs/BUG_<id>_*.md`.
-- Add test coverage:
-  1) Spawn testing-focused agent; include target modules and desired coverage.
-  2) Require GIVEN/WHEN/THEN style, cleanup traps, production code paths.
-  3) Run the relevant suite once via coordinator; collect artifacts.
-- Docker build verification:
-  1) Confirm Linux filesystem; use build script with tag.
-  2) Capture build command and timing; store logs if failing.
-  3) If failure, collect `/tmp/cfn-build` outputs and Docker logs.
-
-## 19) Common Checks Before and After Work
-- Before: confirm mode (task vs CLI), provider choice, environment variables, worktree isolation, and backup path.  
-- During: keep messages concise; avoid mixing roles; use service names; cite paths.  
-- After: run post-edit hook; run appropriate tests; link artifacts; note backlog items.
-
-## 20) Security and Data Handling
-- Redact credentials, tokens, and personal data (`[REDACTED]`).  
-- No secrets in code, docs, tests, or environment examples.  
-- Validate inputs (type, size, permissions) before processing.  
-- Prefer least-privilege operations; avoid destructive commands unless explicitly requested.  
-- Scrub task IDs or usernames in shared logs if sensitive.
-
-## 21) Background Monitoring Pattern
-- For long-running tasks: execute action, `sleep <n>m`, recheck, repeat; avoid tight loops.  
-- Capture partial logs at each check; stop on errors.  
-- If stuck, restart via orchestrator rather than manual kills.  
-- Clean up child processes to avoid zombies and port leaks.
-
-## 22) Troubleshooting Quick Table
-- Build slow or failing: verify Linux filesystem, use build script, clean `/tmp/cfn-build`.  
-- Redis connection issues: ensure service running, ports offset correct, service name used inside network.  
-- Port conflicts: stop and remove containers, `docker network prune -f`, restart stack.  
-- Post-edit hook fails for missing tools (e.g., `jq`): install dependency or rerun after adding it.  
-- Tests flaking: rerun with `DEBUG=true`, inspect `.artifacts/logs/test-execution.log`.  
-- Orchestrator stuck: restart via orchestration script; check Redis coordination keys for stale locks.
+```bash
+# Before ANY edit:
+./.claude/hooks/cfn-invoke-pre-edit.sh "$FILE" --agent-id "$ID"
 
-## 23) File and Path Conventions
-- Place new scripts/tests in relevant subdirectories; never in project root.  
-- Name tests `test-*.sh`; feature docs `FEATURE_NAME.md`; bug docs `BUG_<id>_*.md`.  
-- Use workspace-relative paths when reporting results (for example `src/app.ts:42`).  
-- Do not use URI schemes like file:// or vscode:// in reports.
+# After edit:
+./.claude/hooks/cfn-invoke-post-edit.sh "$FILE" --agent-id "$ID"
 
-## 24) Response Formatting for Agents
-- Be concise and factual; bullets preferred.  
-- Include code paths inline with backticks; add line numbers when available.  
-- In reviews, list findings first (ordered by severity), then questions, then brief summary.  
-- Suggest next steps when natural; number options for quick replies.  
-- Avoid nested bullets and ANSI codes; keep headers short (1-3 words).
+# Revert (not git checkout):
+./.claude/skills/pre-edit-backup/revert-file.sh "$FILE" --agent-id "$ID"
+```
 
-## 25) Validation and Gates Recap
-- Loop 3 gate: test pass rate must meet the mode threshold before validators start.  
-- Loop 2 validators need access to Loop 3 outputs, tests, and logs.  
-- Product Owner decision parsed via `.claude/skills/product-owner-decision/execute-decision.sh`.  
-- Gate failure: iterate Loop 3 only. Gate pass: proceed to validators.  
-- Decision outcomes: PROCEED (done), ITERATE (repeat), ABORT (stop with error).
+## Task Mode
 
-## 26) Mode Comparison Snapshot
-- MVP: fast prototyping; gate >= 0.70, consensus >= 0.80; up to 5 iterations; 2 validators.  
-- Standard: production default; gate >= 0.95, consensus >= 0.90; up to 10 iterations; 3-5 validators.  
-- Enterprise: compliance focus; gate >= 0.98, consensus >= 0.95; up to 15 iterations; 5-7 validators.  
-- Pick higher modes for security/compliance-sensitive tasks; expect longer runtimes but higher assurance.
+**Command:** `/cfn-loop-task "description" --mode=standard`
 
-## 27) Artifacts and Coverage
-- Test results: `.artifacts/test-results/` (per-suite archives).  
-- Coverage: `.artifacts/coverage/` (HTML or lcov outputs).  
-- Logs: `.artifacts/logs/` (CLI and orchestrator logs).  
-- Runtime: `.artifacts/runtime/` (transient runtime data).  
-- Benchmarks (if produced): `.artifacts/benchmarks/`.  
-- Include artifact paths in reports; avoid attaching large logs inline.  
-- For coverage regressions, note impacted modules and thresholds breached.
+1. Parse command, validate params
+2. Spawn agents with context + success criteria
+3. Agents execute, return results (no Redis)
+4. Iterate on validator/PO feedback
 
-## 28) CI/CD Expectations
-- Local pre-commit recommendation: `npm test` then `./tests/cli-mode/run-all-tests.sh` then `./tests/docker-mode/run-all-implementations.sh`.  
-- Ensure Docker daemon is available before running Docker-mode suites.  
-- CI runs GitHub Actions for tests, coverage gates (>=80% lines/statements/functions), security scanning, and deployment.  
-- Before merging, confirm no flaky tests and no unvetted changes to orchestration or spawning scripts.  
-- Record any skipped tests with justification and follow-up owner.
+**CLI Mode:** See `docs/CFN_LOOP_CLI_MODE.md`
 
-## 29) Incident Response Notes
-- Capture exact command, commit hash, environment variables, and logs.
-- Use `[REDACTED]` when logging sensitive fields.
-- Prefer rollback via backup scripts rather than git reset.
-- If orchestration deadlocks, restart orchestrator and clear stale Redis keys scoped to the task.
-- File incidents or backlog items using `.claude/skills/cfn-backlog-management/add-backlog-item.sh` with cause and remediation.
+## Output Locations
 
-## 30) Memory Leak Prevention (ANTI-024)
-Background test processes can become orphaned and accumulate memory. Use these tools to prevent and recover:
+| Type | Path |
+|------|------|
+| Bugs | `docs/BUG_#_*.md` |
+| Tests | `tests/test-*.sh` |
+| Features | `docs/FEATURE_*.md` |
+| Temp | `/tmp/` only |
+| Backlog | `.claude/skills/cfn-backlog-management/add-backlog-item.sh` |
+| Changelog | `.claude/skills/cfn-changelog-management/add-changelog-entry.sh` |
 
-**CLI Commands (available after npm install):**
-- `npx cfn-check-memory` - Report orphaned test processes
-- `npx cfn-check-memory --kill` - Kill orphaned processes
-- `npx cfn-check-memory --kill 500` - Kill only if total MB > 500
-- `npx cfn-run-limited 6G <command>` - Run command with 6GB memory limit (systemd cgroups)
+## Key Files
 
-**NPM Scripts:**
-- `npm run test:safe` - Full test suite with 6GB limit
-- `npm run test:unit:safe` - Unit tests with 2GB limit
-- `npm run check:memory` - Report orphans
-- `npm run check:memory:kill` - Kill orphans
+| Purpose | Path |
+|---------|------|
+| Pre-edit hook | `.claude/hooks/cfn-invoke-pre-edit.sh` |
+| Post-edit hook | `.claude/hooks/cfn-invoke-post-edit.sh` |
+| Backup revert | `.claude/skills/pre-edit-backup/revert-file.sh` |
+| RuVector skill | `.claude/skills/cfn-local-ruvector-accelerator/SKILL.md` |
 
-**Prevention Rules:**
-- Never use `run_in_background: true` for test commands
-- Jest config enforces: `maxWorkers: 4`, `forceExit: true`, `workerIdleMemoryLimit: 512MB`
-- If tests hang, investigate root cause; don't background them
+## WSL Memory Monitor
 
-**Recovery:**
-```bash
-npx cfn-check-memory --kill    # Kill all orphaned test processes
-ps aux | grep -E "(jest|vitest|node.*test)" | grep -v grep  # Manual check
-```
+Background process kills test runner memory leaks. Runs on session start.
+- `>10%` memory (node test processes only) → killed
+- Parent with test children totaling `>15%` combined → test children killed
+- Targets: node processes running vitest, jest, mocha, ava, tap, playwright, cypress
+- Never kills: bash, sh, zsh (even if running tests)
+- Status: `~/.local/bin/wsl-memory-monitor.sh --status`
+- Log: `/tmp/wsl-memory-monitor.log`
 
----
+## Security
 
-Use this trimmed guide as the default reference. For CFN-specific deep dives, defer to specialized docs or agents noted above. Keep this file lean; avoid reintroducing duplication.
+- Validate inputs: type, size, permissions
+- Redact: credentials, tokens, PII → `[REDACTED]`
+- Incidents: capture command, commit, env, logs
+- Rollback: use backup scripts, not `git checkout`

package/docs/CFN_LOOP_CLI_MODE.md

@@ -0,0 +1,134 @@
+# CFN Loop CLI Mode Reference
+
+**Purpose:** Detailed documentation for CLI mode execution of CFN Loops.
+
+---
+
+## Overview
+
+CLI Mode is the production-default execution method for CFN Loops, optimized for cost and provider routing.
+
+**Command:** `/cfn-loop-cli "Task description" --mode=standard --provider kimi`
+
+**Best for:** Production workflows, provider routing, cost-sensitive work.
+
+---
+
+## Execution Flow
+
+### Slash Command Execution Rules
+
+1. Expand slash command
+2. Immediately execute coordinator spawn via Bash tool using the exact command
+3. Do not merely show commands; run them
+4. Inform user after spawn with task ID
+
+**Anti-patterns:**
+- Pausing to ask what next
+- Manual Task() spawning for CLI workflows
+- Skipping execution
+
+### CLI Mode Execution Steps
+
+1. **Expand & Validate:** Parse slash command, validate required parameters (mode, optional provider)
+2. **Spawn Coordinator:** Execute orchestration script; confirm task ID
+3. **Loop 3 Implementation:** Agents implement and run tests; orchestration monitors via Redis
+4. **Gate Check:** Compare pass rate to mode threshold; if failing, iterate Loop 3
+5. **Loop 2 Validation:** If gate passes, validators review and score
+6. **Product Owner Decision:** PROCEED/ITERATE/ABORT; orchestrator enforces
+7. **Report & Cleanup:** Final status, code paths, test results; stop agents cleanly
+
+---
+
+## Provider Routing
+
+### Enable Custom Routing
+
+Set `CFN_CUSTOM_ROUTING=true` in `.env`.
+
+### Provider Options
+
+| Provider | Use Case | Notes |
+|----------|----------|-------|
+| `zai` | Cost-sensitive | Default when custom routing enabled |
+| `kimi` | Balanced quality/cost | Good general choice |
+| `openrouter` | Broad access | Multiple models available |
+| `max` / `anthropic` | Premium quality | Highest safety/quality |
+| `gemini` | Google ecosystem | |
+| `xai` | Grok-style responses | |
+
+### Provider Selection
+
+- **Cost sensitive:** `zai` or low-tier `openrouter`
+- **Balanced:** `kimi`
+- **Quality critical:** `max` or `anthropic`
+- **Google tools:** `gemini`
+- **Mixed providers:** Set per-agent profile; otherwise inherit main chat provider
+
+### Example Flow
+
+```bash
+/switch-api kimi
+/cfn-loop-cli "Implement feature" --provider kimi
+```
+
+**Full guide:** `docs/CUSTOM_PROVIDER_ROUTING.md`
+
+---
+
+## Mode Thresholds
+
+### Test Gate Thresholds
+
+| Mode | Gate Pass Rate | Consensus | Max Iterations | Validators |
+|------|----------------|-----------|----------------|------------|
+| MVP | >= 0.70 | >= 0.80 | 5 | 2 |
+| Standard | >= 0.95 | >= 0.90 | 10 | 3-5 |
+| Enterprise | >= 0.98 | >= 0.95 | 15 | 5-7 |
+
+### Mode Selection
+
+- **MVP:** Fast prototyping, demos, non-critical work
+- **Standard:** Production default, most features
+- **Enterprise:** Compliance-sensitive, security-critical work
+
+---
+
+## Redis Coordination
+
+CLI mode uses Redis BLPOP for agent coordination:
+
+- Agents signal completion via Redis
+- Orchestrator monitors progress via polling
+- Context validation and metadata tracking
+- Health monitoring for stuck agents
+
+**Key patterns:** `.claude/skills/cfn-coordination/SKILL.md`
+
+---
+
+## Deprecated Patterns
+
+- Manual `Task()` spawning for CLI workflows
+- Ad-hoc file coordination (use Redis protocols)
+- Host-side iteration scripts (use self-contained coordinator)
+
+---
+
+## Quick Reference
+
+```bash
+# Standard CLI mode execution
+/cfn-loop-cli "Implement feature X" --mode=standard
+
+# With provider routing
+/cfn-loop-cli "Fix bug Y" --mode=standard --provider kimi
+
+# Enterprise mode for compliance
+/cfn-loop-cli "Security audit" --mode=enterprise --provider anthropic
+```
+
+**See also:**
+- Root `CLAUDE.md` for Task Mode (debugging/learning)
+- `docs/CFN_LOOP_ARCHITECTURE.md` for architecture details
+- `.claude/agents/custom/cfn-loops-cli-expert.md` for CLI expert agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow-novice",
-  "version": "2.18.23",
+  "version": "2.18.24",
   "description": "Claude Flow Novice - Advanced orchestration platform for multi-agent AI workflows with CFN Loop architecture\n\nIncludes Local RuVector Accelerator and all CFN skills for complete functionality.",
   "main": "index.js",
   "type": "module",

package/scripts/cfn-init.js

@@ -71,6 +71,10 @@ const CFN_PATHS = {
     src: path.join(cfnRoot, '.claude/helpers'),
     dest: '.claude/helpers',
     pattern: 'cfn-*'
+  },
+  configHooks: {
+    src: path.join(cfnRoot, 'config/hooks'),
+    dest: 'config/hooks'
   }
 };
 
@@ -82,7 +86,8 @@ async function ensureDirectories() {
     '.claude/commands',
     '.claude/cfn-extras',
     '.claude/core',
-    '.claude/helpers'
+    '.claude/helpers',
+    'config/hooks'
   ];
 
   for (const dir of dirs) {
@@ -282,7 +287,8 @@ async function initializeCfnProject() {
     '.claude/agents/cfn-dev-team',
     '.claude/skills',
     '.claude/hooks',
-    '.claude/commands'
+    '.claude/commands',
+    'config/hooks'
   ];
 
   if (fs.existsSync(markerPath)) {

package/.claude/hooks/SessionStart-cfn-load-openai-key.sh

@@ -1,35 +0,0 @@
-#!/bin/bash
-
-# SessionStart hook: Load OpenAI API key from root .env file
-# This ensures OPENAI_API_KEY is available for embedding generation
-
-set -e
-
-# Path to root .env file
-ROOT_ENV="${PROJECT_ROOT:-.}/.env"
-
-# Check if .env exists
-if [[ ! -f "$ROOT_ENV" ]]; then
-    echo "⚠️  Warning: $ROOT_ENV not found. OpenAI embeddings will not work." >&2
-    exit 0
-fi
-
-# Extract OPENAI_API_KEY from .env
-if grep -q "^OPENAI_API_KEY=" "$ROOT_ENV"; then
-    # Export the key for this session
-    export OPENAI_API_KEY=$(grep "^OPENAI_API_KEY=" "$ROOT_ENV" | cut -d'=' -f2- | tr -d '"')
-
-    # Verify key is set
-    if [[ -n "$OPENAI_API_KEY" ]]; then
-        echo "✅ Loaded OPENAI_API_KEY from root .env" >&2
-    else
-        echo "⚠️  Warning: OPENAI_API_KEY found but empty in $ROOT_ENV" >&2
-    fi
-else
-    echo "⚠️  Warning: OPENAI_API_KEY not found in $ROOT_ENV. OpenAI embeddings will not work." >&2
-fi
-
-# Make it available to subprocesses
-export OPENAI_API_KEY
-
-exit 0

package/.claude/hooks/SessionStart:cfn-build-ruvector.sh

@@ -1,28 +0,0 @@
-#!/bin/bash
-# SessionStart hook: Build RuVector Rust binary if missing
-# This ensures RuVector is compiled on cfn init
-
-RUVECTOR_DIR="$(dirname "$(dirname "$(dirname "$0")")")/skills/cfn-local-ruvector-accelerator"
-BINARY="$RUVECTOR_DIR/target/release/local-ruvector"
-
-# Only build if binary doesn't exist
-if [ ! -f "$BINARY" ]; then
-    echo "[cfn-build-ruvector] Binary not found, building..."
-
-    # Check if Cargo is available
-    if ! command -v cargo &> /dev/null; then
-        echo "[cfn-build-ruvector] WARNING: Cargo not installed, skipping RuVector build"
-        exit 0
-    fi
-
-    # Build release binary
-    cd "$RUVECTOR_DIR" && cargo build --release --quiet 2>/dev/null
-
-    if [ -f "$BINARY" ]; then
-        echo "[cfn-build-ruvector] ✅ RuVector binary built successfully"
-    else
-        echo "[cfn-build-ruvector] WARNING: Build failed, RuVector unavailable"
-    fi
-else
-    echo "[cfn-build-ruvector] ✅ RuVector binary already exists"
-fi