claude-flow-novice 2.18.23 → 2.18.25

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.**