claude-flow-novice 2.18.2 → 2.18.3

package/README.md

@@ -1,712 +1,106 @@
-# Claude Flow Novice v2.16.0 - AI Agent Orchestration Framework
-
-[![npm version](https://badge.fury.io/js/claude-flow-novice.svg)](https://badge.fury.io/js/claude-flow-novice)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
-[![CI Pipeline](https://github.com/yourusername/claude-flow-novice/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/claude-flow-novice/actions/workflows/ci.yml)
-[![Coverage Report](https://img.shields.io/badge/coverage-dynamic-blue)](.github/workflows)
-
-Autonomous self-correcting AI agent orchestration with multi-domain support and intelligent learning capabilities.
-
-## Quick Start
-
-```bash
-# 1. Install package (automatically initializes CFN files)
-npm install claude-flow-novice
-
-# 2. Activate CFN instructions for CLI agents
-cp CFN-CLAUDE.md CLAUDE.md
-
-# 3. Execute CFN Loop for complex features
-npx cfn-loop "Implement JWT authentication system" --mode=standard
-
-# Or spawn agents directly
-npx cfn-spawn backend-developer --task-id auth-task
-```
-
-**Package Details:**
-- 573 KB tarball, 2.4 MB unpacked, 303 files
-- 23 agents in `.claude/agents/cfn-dev-team/`
-- 43 skills in `.claude/skills/cfn-*/`
-- 7 hooks in `.claude/hooks/cfn-*`
-- 45+ commands in `.claude/commands/cfn/`
-- Collision risk: ~0.01% (user custom files preserved)
-
-**Important**: CLI-spawned agents read instructions from `CLAUDE.md` in your project root. Copy `CFN-CLAUDE.md` → `CLAUDE.md` to activate CFN workflows.
-
-## What You Get
-
-**Self-Correcting Workflows** - Automatic iteration until quality gates met
-- MVP mode: Gate ≥0.70, Consensus ≥0.80, max 5 iterations
-- Standard mode: Gate ≥0.75, Consensus ≥0.90, max 10 iterations
-- Enterprise mode: Gate ≥0.85, Consensus ≥0.95, max 15 iterations
-
-**Cost Optimization** - CLI mode with custom routing
-- Z.ai routing: $0.50/1M tokens (vs $3-15/1M Anthropic)
-- 95-98% savings with CLI mode
-- Zero-token coordination via Redis BLPOP
-
-**Intelligent Learning** - SQLite playbook system
-- Pattern storage with similarity matching
-- Agent performance tracking per domain
-- Reduces iterations after repeated similar tasks
-
-**Multi-Domain Support** - Works across software, content, infrastructure, design, research, and data engineering tasks with domain-specific validation
-
-**Zero-Token Coordination** - Redis BLPOP for infinite waiting without API costs
-
----
-
-## CFN Loop Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                       CFN Loop v2.16.0 Flow                     │
-└─────────────────────────────────────────────────────────────────┘
-
-User Task Description
-    ↓
-┌───────────────────────────────────────┐
-│ cfn-v3-coordinator                    │
-│ • Classify task type                  │
-│ • Query playbook for similar tasks    │
-│ • Select Loop 3 + Loop 2 agents       │
-│ • Load validation templates           │
-│ • Estimate complexity & iterations    │
-└───────────────┬───────────────────────┘
-                ↓
-┌───────────────────────────────────────┐
-│ CFN Loop Orchestrator                 │
-│ (orchestrate.sh)                      │
-└───────────────┬───────────────────────┘
-                ↓
-┌───────────────────────────────────────────────────────────┐
-│ ITERATION N                                               │
-├───────────────────────────────────────────────────────────┤
-│                                                           │
-│  ┌─────────────────────────────────────────────┐        │
-│  │ Loop 3: Implementation (parallel agents)    │        │
-│  │ • backend-developer, coder, devops-engineer │        │
-│  │ • Each reports confidence score (0.0-1.0)   │        │
-│  └─────────────────┬───────────────────────────┘        │
-│                    ↓                                      │
-│  ┌─────────────────────────────────────────────┐        │
-│  │ Gate Check: Self-Validation                 │        │
-│  │ • Check Loop 3 confidence ≥ threshold       │        │
-│  │ • MVP: 0.70 | Standard: 0.75 | Enterprise: 0.85 │   │
-│  └─────────────────┬───────────────────────────┘        │
-│                    ↓                                      │
-│         ┌──────────┴──────────┐                         │
-│         │ Gate PASS?          │                         │
-│         └──┬────────────────┬─┘                         │
-│           NO                YES                          │
-│            ↓                 ↓                           │
-│    ┌───────────┐    ┌───────────────────────────┐     │
-│    │ ITERATE   │    │ Deliverable Verification  │     │
-│    │ N+1       │    │ • git diff for file changes│     │
-│    │ (retry)   │    │ • Force ITERATE if no files│     │
-│    └───────────┘    └──────────┬────────────────┘     │
-│                                  ↓                       │
-│                    ┌─────────────────────────────────┐ │
-│                    │ Loop 2: Validation (parallel)   │ │
-│                    │ • reviewer, tester, security    │ │
-│                    │ • Each reports consensus score  │ │
-│                    └──────────┬──────────────────────┘ │
-│                                ↓                        │
-│                    ┌─────────────────────────────────┐ │
-│                    │ Consensus Check                 │ │
-│                    │ • Aggregate validator scores    │ │
-│                    │ • MVP: 0.80 | Std: 0.90 | Ent: 0.95 │ │
-│                    └──────────┬──────────────────────┘ │
-│                                ↓                        │
-│                    ┌─────────────────────────────────┐ │
-│                    │ Loop 4: Product Owner Decision  │ │
-│                    │ • PROCEED: Accept deliverables  │ │
-│                    │ • ITERATE: Retry with feedback  │ │
-│                    │ • ABORT: Stop execution         │ │
-│                    └──────────┬──────────────────────┘ │
-│                                ↓                        │
-│                     ┌──────────┴─────────┐            │
-│                     │ Decision?           │            │
-│                     └──┬──────────────┬──┘            │
-│                       ITERATE        PROCEED           │
-│                        ↓                ↓              │
-└────────────────────────┼────────────────┼──────────────┘
-                         │                │
-                 ┌───────┘                └────────┐
-                 ↓                                  ↓
-          (Next Iteration)                  ┌──────────────┐
-          Max iterations:                   │ Loop 5:      │
-          • MVP: 5                          │ Retrospective│
-          • Standard: 10                    │ • Extract    │
-          • Enterprise: 15                  │   patterns   │
-                                            │ • Update     │
-                                            │   playbook   │
-                                            │ • Rank agents│
-                                            └──────────────┘
-```
-
-### Dual-Mode Execution
-
-**CLI Mode (Default)** - Production cost optimization
-- 95-98% cost reduction via Z.ai routing
-- Redis context storage for swarm recovery
-- Zero-token waiting (BLPOP)
-- Scalable to 10+ agents
-
-**Task Mode** - Development & debugging
-- Full visibility in Main Chat
-- Direct context injection
-- Anthropic routing
-- Easier troubleshooting
-
-```bash
-# CLI mode (default)
-/cfn-loop "Task description" --mode=standard
-
-# Task mode (debugging)
-/cfn-loop "Task description" --spawn-mode=task
-```
-
-### Custom Routing (Z.ai Provider Integration)
-
-**Provider Routing Model:**
-- Task() agents → Use Main Chat provider (Anthropic)
-- CLI-spawned agents → Use custom routing (Z.ai when enabled)
-
-**Enable Custom Routing:**
-```bash
-/custom-routing-activate
-/switch-api zai  # or max for Claude subscription
-```
-
-**Cost Impact:**
-- Without custom routing: CLI agents use Anthropic ($3-15/1M tokens)
-- With custom routing: CLI agents use Z.ai ($0.50/1M tokens)
-- Combined with CLI spawning: 95-98% total savings vs Task tool
-
----
-
-## Core Skills & Capabilities
-
-### 12 Key Skills (31 More Available)
-
-| Skill | Purpose | Impact |
-|-------|---------|--------|
-| `cfn-task-classifier` | Detect domain (software/content/research/design/infra/data) | Automatic agent selection |
-| `cfn-validation-templates` | Domain-specific quality criteria | Relevant validation gates |
-| `cfn-playbook` | SQLite pattern storage with similarity matching | Reduces iterations over time |
-| `cfn-complexity-estimator` | Predict iterations from task analysis | Accurate effort estimates |
-| `cfn-epic-decomposer` | Break epics into focused sprints | Manageable scope |
-| `cfn-intervention-detector` | Identify stuck loops | Automatic recovery |
-| `cfn-specialist-injection` | Add domain experts mid-loop | Adaptive team optimization |
-| `cfn-playbook-auto-update` | Store successful strategies and patterns | Continuous learning |
-| `cfn-redis-coordination` | Zero-token agent communication | Infinite BLPOP waiting |
-| `cfn-agent-spawning` | Dynamic agent deployment | Skill-based selection |
-| `cfn-loop-orchestration` | Multi-loop workflow execution | Self-correcting validation |
-| `cfn-hybrid-routing` | Custom provider routing | 95-98% cost savings |
-
-**Additional Skills**: Redis coordination, agent spawning, CFN loop orchestration, validation processing, hook pipeline, hybrid routing, SQLite memory, transparency middleware, and 23 more. See `.claude/skills/` for complete list.
-
----
-
-## Agent Library
-
-### Top Agents by Category
-
-**Coordinators (3)**
-- `cfn-v3-coordinator` - Main CFN Loop analyzer and configuration generator
-- `multi-sprint-coordinator` - Epic-level orchestration across sprints
-- `retrospective-analyst` - Automatic learning and pattern extraction
-
-**Implementation (12)**
-- `coder` - General-purpose code implementation
-- `backend-developer` - Backend services and APIs
-- `frontend-dev` - Frontend applications
-- `mobile-dev` - React Native and cross-platform
-- `rust-developer` - Rust language specialist
-- `devops-engineer` - DevOps and deployment
-- `database-engineer` - Database design and optimization
-- `api-designer` - API architecture and REST design
-- `terraform-engineer` - Infrastructure as code
-- `kubernetes-architect` - Container orchestration
-- `data-engineer` - Data pipelines and ETL
-- `pipeline-builder` - CI/CD and automation
-
-**Quality Assurance (8)**
-- `reviewer` - Code review and quality validation
-- `tester` - Test writing and execution
-- `security-specialist` - Security analysis and hardening
-- `architect` - System design and architecture
-- `performance-benchmarker` - Performance testing
-- `accessibility-advocate` - Accessibility compliance
-- `security-auditor` - Security auditing
-- `compliance-checker` - Standards compliance
-
-**Full agent library (81 agents)**: See `.claude/agents/cfn-dev-team/` for complete list including content creation, design, research, and domain specialists.
-
----
-
-## CLI & Slash Commands
-
-### CFN Loop Commands
-
-```bash
-# Single task execution
-/cfn-loop "Implement JWT authentication" --mode=standard
-
-# Quick single-iteration task
-/cfn-loop-single "Fix security bug in auth module"
-
-# Large multi-phase epic
-/cfn-loop-epic "Build complete authentication system"
-
-# Phase with multiple sprints
-/cfn-loop-sprints "Implement payment processing"
-
-# Documentation generation
-/cfn-loop-document --sprint=auth --epic=user-mgmt
-
-# Toggle spawning mode
-/cfn-mode # Switch between CLI and Task spawning
-```
-
-### Binary Commands
-
-```bash
-cfn-spawn          # Spawn individual agents
-cfn-loop           # Execute CFN Loop workflow
-cfn-swarm          # Multi-agent coordination
-cfn-portal         # Web monitoring dashboard
-cfn-context        # Context management
-cfn-metrics        # Performance tracking
-cfn-redis          # Redis coordination utilities
-```
-
----
-
-## Redis Coordination
-
-### Zero-Token Waiting Mode
-
-**BLPOP-Based Blocking** - Infinite wait, zero API cost
-- Agents block with `redis-cli blpop "queue" 0`
-- Coordinator wakes agents with `redis-cli lpush "queue" "signal"`
-- <100ms latency wake-up
-- Context preserved across iterations
-
-**Swarm Recovery** - Redis persistence enables crash recovery
-- Task context stored in Redis with TTL
-- Agents resume from last known state
-- Critical for long-running CFN Loops
-
-### Coordination Patterns
-
-| Pattern | Use Case | Agent Count |
-|---------|----------|-------------|
-| **Simple Chain** | Sequential dependencies | 2-3 |
-| **Hierarchical Broadcast** | Coordinator → Workers | 4-10 |
-| **Mesh Hybrid** | Complex collaboration | 5-15 |
-
----
-
-## Performance & Cost Metrics
-
-| Metric | Value | Details |
-|--------|-------|---------|
-| **CLI Mode Cost Savings** | 95-98% | Z.ai routing ($0.50/1M vs Anthropic $3-15/1M) |
-| **Zero-Token Coordination** | 100% savings during waits | BLPOP blocking costs nothing |
-| **Context Pruning** | 88% token reduction | Summarization at iteration 10 |
-| **Average Iterations** | 3.5-4.0 vs 5.2 baseline | 33% improvement with playbook |
-| **Context Size (iter 10)** | 15-20 KB vs 120 KB baseline | 88% reduction |
-| **Time to Converge** | 30-35 min vs 45 min baseline | 33% faster |
-| **Playbook Hit Rate** | 60%+ after learning | Improves with repeated task types |
-
----
-
-## Developer Experience
-
-### Skills-Based Architecture
-
-43 total skills (20 CFN-specific + 23 core infrastructure) with modular design, clear interfaces, comprehensive documentation, and easy extensibility.
-
-### Hooks & Automation
-
-```bash
-# Automatic post-edit validation (39 hooks)
-./.claude/hooks/invoke-post-edit.sh "$FILE" --agent-id "$AGENT_ID"
-```
-
-### Complexity Analysis Tools
-
-**Built-in Code Quality Monitoring**
-- Simple complexity analyzer (~23ms bash script)
-- Per-function analyzer with detailed breakdown
-- Lizard (professional multi-language support)
-- Automated monitoring (triggers on files >200 lines)
-- Critical threshold ≥40 auto-spawns refactor agent
-
-```bash
-./tools/simple-complexity.sh script.sh
-./tools/calculate-complexity.sh script.sh
-lizard src/module.ts --CCN 30
-```
-
-See `readme/logs-tools.md` for complete documentation.
-
----
-
-## Security & Quality
-
-### Built-in Security
-
-**ACL System** - 5 levels of access control
-1. Private - Agent's own data only
-2. Swarm - Shared across team of agents
-3. Project - Strategic decisions, audit logs
-4. Strategic - Cross-project patterns
-5. System - Infrastructure only
-
-**Security Features**
-- Secret detection and prevention
-- Path traversal protection
-- Input sanitization
-- Envelope encryption for sensitive data
-
-### Quality Gates
-
-- **Deliverable Verification** - Prevents "consensus on vapor"
-- **Multi-Layer Context Injection** - Validation at coordinator → orchestrator → agent layers
-- **Agent Completion Protocol** - Mandatory confidence reporting
-- **Mandatory Iteration** - Forced retry if zero files created
-
----
-
-## System Requirements
-
-### Required Dependencies
-
-```json
-{
-  "node": ">=18.0.0",
-  "redis": ">=6.0",
-  "sqlite3": ">=5.1.0"
-}
-```
-
-### Core Dependencies
-
-```json
-{
-  "@anthropic-ai/sdk": "^0.67.0",
-  "redis": "^5.8.3",
-  "better-sqlite3": "^12.4.1",
-  "commander": "^11.1.0",
-  "dotenv": "^17.2.3"
-}
-```
-
-### Optional
-
-- Z.ai provider account (for cost savings)
-- Web portal dependencies (Socket.io for real-time monitoring)
-
----
-
-## Learning & Adaptation
-
-### Playbook System
-
-**SQLite-Based Pattern Storage**
-- Similarity matching for task queries
-- Agent performance tracking per domain
-- Historical confidence data
-- Expected iterations prediction
-- 60%+ hit rate after repeated similar tasks
-
-### Continuous Improvement
-
-**Automatic After Each Sprint**
-1. Extract patterns from execution logs
-2. Identify bottlenecks and failures
-3. Rank agent performance
-4. Generate improvement recommendations
-5. Update playbook with successful strategies
-
----
-
-## Testing
-
-Claude Flow Novice includes comprehensive test suites across multiple execution modes and test types. Choose the appropriate test runner based on your development context.
-
-### Quick Start
-
-```bash
-# Run all npm-based tests (unit, integration, e2e)
-npm test
-
-# Run CLI mode test suite (test-driven validation)
-./tests/cli-mode/run-all-tests.sh
-
-# Run Docker mode test suite (45 production tests)
-./tests/docker-mode/run-all-implementations.sh
-```
-
-### Test Execution Modes
-
-#### CLI Mode Tests (Production)
-Run the CLI mode test suite to validate end-to-end coordination, quality gates, and agent spawning:
-
-```bash
-# Full test suite with all assertions
-./tests/cli-mode/run-all-tests.sh
-
-# Expected runtime: ~5-10 minutes
-# Tests: 8 suites, 159 total assertions
-# Coverage: Redis coordination, threshold enforcement, agent spawning, path resolution
-```
-
-**Validates:**
-- `/cfn-loop-cli` slash command workflow
-- Coordinator spawning and orchestration
-- Loop 3 → Loop 2 → Product Owner progression
-- Quality gate enforcement (MVP/Standard/Enterprise modes)
-- Redis coordination layer
-- Agent tool access and permissions
-
-**Prerequisites:**
-- Redis running (`redis-server`)
-- Project built (`npm run build`)
-- Z.ai API key configured (`.env`) for integration tests
-
-**Documentation:** See `tests/cli-mode/README.md` for detailed test descriptions and results.
-
-#### Docker Mode Tests (Integration)
-Run the Docker mode test suite to validate real container-based orchestration:
-
-```bash
-# Run all 45 Docker test implementations
-./tests/docker-mode/run-all-implementations.sh
-
-# Expected runtime: ~3-5 minutes
-# Tests: 45 production tests across 3 suites
-# Coverage: Coordinator spawning, orchestrator workflow, TDD compliance
-```
-
-**Test Suites:**
-- Coordinator Spawning (13 tests): Container cleanup, exit codes, service discovery
-- Orchestrator Workflow (13 tests): Iteration management, monitoring, recovery
-- TDD Compliance (19 tests): Test-driven validation, metrics collection, parallel execution
-
-**Prerequisites:**
-- Docker daemon running (`docker ps`)
-- No port conflicts (Docker networks auto-created)
-- ~2GB available memory for container execution
-
-**Documentation:** See `tests/docker-mode/README.md` for test categories and patterns.
-
-#### NPM-Based Tests (Development)
-Run standard npm test commands for fast feedback during development:
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test suites
-npm run test:unit           # Unit tests only
-npm run test:integration    # Integration tests only
-npm run test:e2e           # End-to-end tests only
-
-# Run with coverage
-npm test -- --coverage
-
-# Watch mode (re-run on file changes)
-npm test -- --watch
-```
-
-**Expected runtime:**
-- Unit tests: ~1-2 minutes
-- Integration tests: ~2-3 minutes
-- E2E tests: ~3-5 minutes
-
-#### CFN Loop End-to-End Tests
-Run specialized CFN Loop tests for validation and debugging:
-
-```bash
-# Validate CFN Loop coordinator handoffs
-./tests/cfn-v3/test-coordinator-handoffs.sh
-
-# Full CFN Loop e2e test
-./tests/cfn-v3/test-e2e-cfn-loop.sh
-
-# Enterprise change management tests
-./tests/enterprise/run-all-enterprise-tests.sh
-```
-
-### Test Organization
-
-```
-tests/
-├── cli-mode/                          # CLI mode validation (8 tests, 159 assertions)
-│   ├── README.md                      # CLI test documentation
-│   ├── run-all-tests.sh              # Test runner
-│   └── test-*.sh                     # Individual test suites
-├── docker-mode/                       # Docker integration tests (45 tests)
-│   ├── README.md                      # Docker test documentation
-│   ├── run-all-implementations.sh     # Test runner
-│   └── implementations/
-│       ├── coordinator-spawning-real-tests.sh
-│       ├── orchestrator-workflow-real-tests.sh
-│       └── tdd-compliance-real-tests.sh
-├── docker/                            # Docker-based core tests
-│   ├── coordination/                  # Redis coordination tests
-│   ├── lifecycle/                     # Container lifecycle tests
-│   └── perf/                          # Performance benchmarks
-├── cfn-v3/                           # CFN Loop validation tests
-├── enterprise/                        # Enterprise mode tests
-├── CLAUDE.md                          # Test authoring standards
-├── test-utils.sh                      # Shared test utilities
-└── README.md                          # Test suite documentation
-```
-
-### Test Coverage Matrix
-
-| Mode | Type | Tests | Duration | Prerequisites |
-|------|------|-------|----------|---|
-| CLI | Unit + Integration + E2E | 159 assertions | 5-10 min | Redis, npm build |
-| Docker | Production integration | 45 tests | 3-5 min | Docker daemon |
-| NPM | Development | Variable | 1-5 min | Node.js, npm |
-| CFN Loop | Workflow validation | Variable | 5-15 min | Full environment |
-
-### Test Authoring Guidelines
-
-For developers writing new tests, see `tests/CLAUDE.md` which documents:
-- Boilerplate template structure
-- GIVEN/WHEN/THEN assertion patterns
-- Production testing requirements (BUG #21)
-- Infrastructure vs integration test patterns
-- Cleanup and resource management
-- Review checklist for test quality
-
-Key principles:
-- Infrastructure tests (mocks OK): Docker networking, volumes, Redis connectivity
-- Integration tests (real images/scripts): Agent spawning, CLI execution, production workflows
-- Always use `set -euo pipefail` and `trap cleanup EXIT`
-- Route output through `log_step`, `log_info`, `annotate`, `assert_success` helpers
-- Cite relevant bugs in test comments for future context
-
-### CI/CD Integration
-
-Tests run automatically in GitHub Actions on every push and pull request. See [CI/CD Pipeline Documentation](.github/workflows) for:
-- Coverage gates (80%+ lines/statements/functions)
-- Test failure notifications
-- Performance benchmarking
-- Security scanning
-- Deployment workflows
-
-### Troubleshooting
-
-**Redis not available:**
-```bash
-# Start Redis in background
-redis-server --daemonize yes
-
-# Or run in Docker
-docker run -d -p 6379:6379 redis:7-alpine
-```
-
-**Docker permission denied:**
-```bash
-# Add user to docker group
-sudo usermod -aG docker $USER
-newgrp docker
-```
-
-**Port conflicts:**
-```bash
-# Stop and remove existing containers
-docker stop $(docker ps -aq)
-docker rm $(docker ps -aq)
-
-# Clean up Docker networks
-docker network prune -f
-```
-
-**Test failures with unclear messages:**
-```bash
-# Run with verbose output
-DEBUG=true ./tests/cli-mode/run-all-tests.sh
-DEBUG=true ./tests/docker-mode/run-all-implementations.sh
-
-# Check test logs in .artifacts/
-tail -100 .artifacts/logs/test-execution.log
-```
-
-### Related Documentation
-
-- **Test Suite Overview:** `tests/README.md`
-- **Test Authoring Standards:** `tests/CLAUDE.md`
-- **CLI Mode Details:** `tests/cli-mode/README.md`
-- **Docker Mode Details:** `tests/docker-mode/README.md`
-- **Test Coverage Analysis:** `tests/TEST_COVERAGE_MATRIX.md`
-- **CFN Loop Architecture:** `docs/CFN_LOOP_ARCHITECTURE.md`
-- **CI/CD Pipeline:** `.github/workflows`
-
-### Development Setup
-
-```bash
-# Clone repository
-git clone https://github.com/masharratt/claude-flow-novice.git
-cd claude-flow-novice
-
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build
-```
-
-### CI/CD Pipeline
-
-Comprehensive GitHub Actions automation with unit testing, integration testing, coverage gates (80%+ lines/statements/functions), security scanning, and deployment workflows. See [CI/CD Pipeline Documentation](.github/workflows) for details.
-
----
-
-## License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
-## Support
-
-- **Documentation**: [Wiki](https://github.com/masharratt/claude-flow-novice/wiki)
-- **Issues**: [GitHub Issues](https://github.com/masharratt/claude-flow-novice/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/masharratt/claude-flow-novice/discussions)
-
----
-
-## Roadmap
-
-### v2.17.0 (Q1 2026)
-- [ ] Semantic playbook similarity (embeddings)
-- [ ] Parallel sprint execution
-- [ ] Natural language epic parsing
-
-### v2.18.0 (Q2 2026)
-- [ ] Dynamic sprint adjustment (merge/split)
-- [ ] Cross-sprint learning
-- [ ] Confidence prediction before execution
-
-### v2.19.0 (Q3 2026)
-- [ ] Sprint rollback capability
-- [ ] Epic-level re-planning
-- [ ] Advanced monitoring dashboard
-
-### v3.0.0 (Q4 2026)
-- [ ] Breaking changes: New coordination protocol
-- [ ] Multi-cloud provider support
-- [ ] Enhanced playbook with vector embeddings
+# Claude Flow Novice
+
+AI agent orchestration with namespace-isolated skills, multi-agent coordination, and semantic codebase search.
+
+## Install
+
+```bash
+npm install claude-flow-novice
+```
+
+## Core Features
+
+- **CFN Loop**: 3-loop self-correcting workflow (implement → validate → decide)
+- **RuVector**: Semantic codebase search via embeddings
+- **Skills**: Modular capabilities in `.claude/skills/`
+- **Agents**: Specialist agents in `.claude/agents/`
+- **Provider Routing**: Z.ai, Kimi, OpenRouter, Anthropic
+
+## Quick Start
+
+```bash
+# Initialize project
+npx cfn-init
+
+# Index codebase for semantic search
+./.claude/skills/cfn-ruvector-codebase-index/index.sh --full
+
+# Search codebase
+./.claude/skills/cfn-ruvector-codebase-index/search.sh "authentication logic" --top 5
+
+# Run CFN Loop (CLI mode - cost optimized)
+/cfn-loop-cli "Implement feature X" --mode=standard
+
+# Run CFN Loop (Task mode - full visibility)
+/cfn-loop-task "Debug issue Y" --mode=standard
+```
+
+## Architecture
+
+```
+claude-flow-novice/
+├── src/                    # TypeScript source
+│   ├── ruvector/          # Semantic search module
+│   ├── agents/            # Agent spawning
+│   ├── coordination/      # Redis coordination
+│   └── cfn-loop/          # Loop orchestration
+├── .claude/
+│   ├── agents/            # Agent definitions
+│   ├── skills/            # Skill modules
+│   ├── commands/          # Slash commands
+│   └── hooks/             # Edit hooks
+└── dist/                  # Compiled output
+```
+
+## RuVector Codebase Search
+
+Semantic search using OpenAI embeddings (text-embedding-3-small).
+
+```bash
+# Full reindex
+./.claude/skills/cfn-ruvector-codebase-index/index.sh --full
+
+# Incremental (git changes only)
+/cfn-ruvector:codebase-reindex
+
+# Search
+./.claude/skills/cfn-ruvector-codebase-index/search.sh "React components" --top 10
+```
+
+**Manifest System**: `.cfn-manifest.json` tracks CFN vs custom files. Custom files preserved during updates.
+
+## CFN Loop Modes
+
+| Mode | Command | Use Case |
+|------|---------|----------|
+| CLI | `/cfn-loop-cli` | Production, cost-optimized |
+| Task | `/cfn-loop-task` | Debugging, full visibility |
+
+## Provider Routing
+
+Set `CFN_CUSTOM_ROUTING=true` in `.env`, then:
+
+```bash
+/switch-api kimi    # Switch provider
+/cfn-loop-cli "Task" --provider kimi
+```
+
+Options: `zai`, `kimi`, `openrouter`, `anthropic`, `gemini`, `xai`
+
+## Key Paths
+
+- Config: `CLAUDE.md`
+- Agents: `.claude/agents/cfn-dev-team/`
+- Skills: `.claude/skills/cfn-*/`
+- Hooks: `.claude/hooks/cfn-*`
+- RuVector data: `.claude/skills/cfn-ruvector-codebase-index/data/`
+
+## Requirements
+
+- Node.js >= 18
+- Redis (for CLI mode coordination)
+- `OPENAI_API_KEY` or `ZAI_API_KEY` (for embeddings)
+
+## License
+
+MIT