Claude Flow Novice v2.18.1 Documentation

Version: 2.18.1 (RuVector Integration)
Last Updated: 2025-12-05

Package Metrics:
- Namespace-isolated installation (~0.01% collision risk)
- Semantic codebase search via RuVector
- Multi-provider routing (Z.ai, Kimi, OpenRouter, Anthropic)

Overview

AI agent orchestration with semantic codebase search, Redis coordination, and multi-loop consensus validation (CFN Loop).

CFN Loop Execution Modes

$3

- Spawn Method: Main Chat spawns Task() agents directly
- Cost: $0.150/iteration (Anthropic provider)
- Visibility: Complete agent output in Main Chat
- Use Case: Debugging, learning, short tasks (<5 minutes)
- Memory: ANTI-023 protection prevents memory leaks
- Audit: Automatic audit trail storage in SQLite and Redis

$3

- Spawn Method: Coordinator spawns CLI agents via npx claude-flow-novice
- Cost: $0.054/iteration (64% savings vs Task mode)
- Visibility: Background execution with progress tracking
- Use Case: Production, long tasks, cost-sensitive workflows
- Memory: Redis-based coordination with recovery capabilities
- Custom Routing: Optional 5x cost reduction with Z.ai provider
- Redis Configuration: Requires CFN_REDIS_HOST=localhost for non-Docker environments (see CLI Mode Redis Configuration)

$3

- Use Task Mode when: Debugging issues, learning CFN Loop, short tasks requiring full visibility
- Use CLI Mode when: Production work, cost optimization, long-running tasks, background execution
- Custom Routing: /custom-routing-activate for 95-98% total cost savings when using CLI mode

$3

- /cfn-loop-task: Task mode execution (Main Chat → Task() agents)
- /cfn-loop-cli: CLI mode execution (Main Chat → coordinator → CLI agents)
- Mode Parameters: --mode=mvp|standard|enterprise with different confidence thresholds

$3

- Task Mode: $0.150/iteration (full visibility, debugging)
- CLI Mode: $0.054/iteration (64% savings, production)
- With Custom Routing: $0.004-0.010/iteration (95-98% total savings)

Quick Start

$3

``bash

Install and initialize

npm install claude-flow-novice
npx cfn-init

Execute CFN Loop - Main Chat spawns Task() agents directly

/cfn-loop-task "Implement JWT authentication" --mode=standard

Custom routing available for 5x cost reduction

/custom-routing-activate
`

$3

`bash

Install and initialize

npm install claude-flow-novice
npx cfn-init

Configure Redis for non-Docker environments

export CFN_REDIS_HOST=localhost
export CFN_REDIS_PORT=6379

Execute CFN Loop - Coordinator spawns CLI agents in background

/cfn-loop-cli "Implement JWT authentication" --mode=standard

Initialize swarm with skills

npx claude-flow-novice swarm "Task Description" \
--skills=redis-coordination,agent-spawning \
--strategy development
`

Documentation Index

$3

- Skills System - Modular, reusable agent capabilities
- CFN Loop - Three-loop consensus validation framework
- RuVector Search - Semantic codebase indexing
- Redis Coordination - Zero-token agent coordination

$3

- Slash Commands - CLI command reference
- Hooks System - Event-driven automation
- Post-Edit Pipeline - Automatic validation after edits

$3

- API Documentation - JavaScript/TypeScript API
- Features Matrix - Feature availability by mode
- Functions Reference - Core function library

$3

- CFN Loop Flow - Visual workflow diagrams
- CFN Loop Cheatsheet - Quick reference guide

$3

- Changelog - Version history and breaking changes
- Decision Log - Architecture decision records
- Component Status - Dependency health

$3

- Deprecated MCP Logs - Historical MCP implementation
- v1 Documentation - Previous documentation version

Key Features (v2.18.1)

$3

- Semantic Search: Natural language queries against codebase
- OpenAI Embeddings: text-embedding-3-small (1536 dimensions)
- Manifest System: .cfn-manifest.json tracks CFN vs custom files
- Safe Distribution: Custom files preserved during CFN updates

`bash

Index codebase

./.claude/skills/cfn-ruvector-codebase-index/index.sh --full

Search

./.claude/skills/cfn-ruvector-codebase-index/search.sh "authentication" --top 5

Incremental reindex

/cfn-ruvector:codebase-reindex
`

$3

- Modular Skills: Independently maintainable, testable capabilities
- Explicit Dependencies: Redis pub/sub coordination, no implicit coupling
- Thin Orchestration: Main chat delegates to skills, minimal coordination logic
- Namespace-Isolated Installation: ~0.01% collision risk
- Preserves User Custom Agents/Skills/Hooks

$3

- Redis BLPOP: Agents wait without API calls (0 tokens while idle)
- Instant Wake-Up: <100ms latency for agent activation
- Scalable: 23 agents in cfn-dev-team

$3

- Loop 3: Implementation agents (coders, researchers)
- Loop 2: Validation agents (reviewers, testers)
- Loop 1: Product owner (strategic oversight)
- Adaptive Modes: MVP (fast), Standard (balanced), Enterprise (rigorous)

$3

- CLI Mode: 64% savings vs Task mode ($0.054 vs $0.150/iteration)
- Custom Routing: Optional 5x reduction with Z.ai provider (95-98% total savings)
- Mode-Aware Architecture: Task Mode agents use clean exit, CLI Mode uses Redis coordination
- Memory Safety: ANTI-023 protection prevents memory leaks in Task Mode

Architecture Principles

1. Skills-Based Coordination: All agent communication via explicit Redis dependencies
2. Multi-Layer Enforcement: Coordination primitives at technical, skill, agent, and system layers
3. Centralized Orchestration: Keep orchestration in dedicated skills, not distributed across components
4. Mode-Aware Architecture: Task Mode (direct Task() spawning) vs CLI Mode (coordinator-driven)
5. Post-Edit Validation: All Edit/Write operations trigger validation hooks
6. Parallel Agent Spawning: All Task-based coordinators require parallel spawning (single message, multiple Task calls)

$3

- Task Mode Agents: Clean exit protocol, direct Main Chat communication, audit trail storage
- CLI Mode Agents: Redis coordination, completion signaling, background execution
- Coordinators: Enhanced monitoring with recovery capabilities, progress tracking

Migration Notes

v1 → v2 Changes:
- Deprecated: Implicit agent coordination, distributed orchestration logic
- Added: Skills system, Redis coordination, zero-token waiting, orchestrate-cfn-loop.sh
- Breaking: CFN Loop now requires orchestrator (no manual Task spawning)

v2.14 Changes:
- Dual-Mode Architecture: Task Mode (Main Chat Task() spawning) vs CLI Mode (coordinator-driven)
- Custom Routing: Z.ai integration for 5x cost reduction in CLI mode
- Memory Safety: ANTI-023 protection prevents memory leaks in Task Mode
- Enhanced Coordinators: Progress tracking, recovery capabilities, multi-layer enforcement

v2.16.0 Changes (Integration Standardization - PR #16):
- Skill Lifecycle Management: Automated deployment, versioning, promotion workflows
- Cross-Database Integration: Transaction coordinator for PostgreSQL/SQLite/Redis
- File System Standardization: Unified backup, logging, state persistence patterns
- Edge Case Feedback Loop: Auto-generates patches from test failures
- Data Format Harmonization: JSON schema validation across 43+ skills
- 27/30 Tasks Complete: 90% integration standardization implementation

See CHANGELOG.md and CFN Loop Task Mode Guide for migration details.

Testing

$3

- Task Mode: ✅ Verified (6 hello world files test)
- CLI Mode: ✅ Verified (6 hello world files test with CFN_REDIS_HOST=localhost)
- Docker Mode: ✅ Verified (Bug #6 validation test)

Test Details: See docs/ALL_3_MODES_VERIFIED_WORKING.md

$3

- TDD Compliance: 100% (24/24 tests)
- CLI Mode Coordinator: 100% (23/23 tests)
- CLI Mode Orchestrator: 91% (21/23 tests, 2 flexible)
- CLI Mode Threshold: 100% (6/6 tests)
- CLI Mode Redis: 100% (7/7 tests)

$3

`bash

TDD compliance tests

bash tests/tdd-compliance/test-*.sh

CLI mode tests

bash tests/cli-mode/test-*.sh

Bug #6 Redis validation

bash tests/docker/validation/validate-bug6-redis-vars.sh
`

RuVector - Semantic Codebase Search

Centralized Index: ~/.local/share/ruvector/index_v2.db

RuVector provides dual-mode code intelligence with a centralized index shared across all projects:

$3

| Schema | Purpose | Query Type | Use Case |
|--------|---------|------------|----------|
| V1 (embeddings, files) | Semantic similarity | Vector distance | "Find code similar to X" |
| V2 (entities, refs, modules) | Structured relationships | SQL joins | "Who calls this function?" |

V1 - Semantic Search:
- Stores text chunks with OpenAI embeddings (text-embedding-3-small, 1536 dims)
- Queries: Fuzzy semantic similarity via cosine distance
- Returns: Code that's semantically related regardless of exact syntax

V2 - Code Intelligence:
- Stores AST entities (functions, classes, interfaces) with relationships
- Queries: Precise SQL on structured code graph
- Returns: Exact references, callers, type usage, module dependencies

$3

`bash

Build RuVector

cd .claude/skills/cfn-local-ruvector-accelerator
cargo build --release

Initialize centralized index

./target/release/local-ruvector init

Index current project (all file types)

./target/release/local-ruvector index --path . --types rs,ts,js,json,md,sh

Semantic search across all indexed projects

./target/release/local-ruvector query --pattern "authentication middleware"

SQL queries on code structure

sqlite3 ~/.local/share/ruvector/index_v2.db "
SELECT * FROM refs WHERE target_name = 'MyFunction';
"
`

Supported Files:
- AST extraction: Rust (.rs), TypeScript/JavaScript (.ts, .tsx, .js, .jsx)
- Text indexing: JSON, YAML, Markdown (.md), Shell scripts (.sh)
- Auto-excluded: .artifacts/ (logs/reports)

Benefits:
- Cross-project semantic search
- Shared learnings across codebases
- Dual query modes (semantic + structural)
- Full paths preserve project context

Support

- Documentation Issues: File issue at GitHub repo
- Skill Development: See .claude/skills/*/SKILL.md` files
- Redis Configuration: See docs/CLI_MODE_REDIS_CONFIGURATION.md

License

See LICENSE file in repository root.