claude-flow-novice 2.8.1 → 2.9.0

package/readme/CLAUDE.md

@@ -1,429 +0,0 @@
-# Documentation Guidelines for Claude Flow
-
-## Core Principles
-
-### Language Style
-- **Sparse, concise language** - maximum information, minimum words
-- **Active voice** - "Use this function" not "This function is used"
-- **Present tense** - "Returns data" not "Will return data"
-- **No fluff** - Remove introductory phrases, opinions, unnecessary context
-
-### Structure
-- **Logical hierarchy** - clear sections, subsections
-- **Consistent patterns** - repeatable formats across documentation
-- **Scannable** - headings, bullet points, code blocks
-- **Practical focus** - what developers need, not what we think they want
-
-### Technical Content
-- **Accurate** - code examples must work
-- **Complete** - include parameters, return values, errors
-- **Contextual** - explain when/why to use features
-- **Cross-referenced** - link to related documentation
-
-## Documentation Categories
-
-### V2 Core Documentation
-
-**[README.md](./README.md)**
-- v2 system overview, quick start guide
-- Skills-first architecture, zero-token coordination
-- CFN Loop consensus framework, cost optimization
-- Migration notes from v1
-
-**[log-skills.md](./log-skills.md)**
-- Complete skills system documentation
-- Available skills: Redis Coordination, Agent Spawning, CFN Loop Validation
-- Skill development guide, testing guidelines, coordination patterns
-- Performance metrics, troubleshooting, future enhancements
-
-### CFN Loop Documentation
-
-**[CFN_LOOP_CHEATSHEET.md](./CFN_LOOP_CHEATSHEET.md)**
-- Quick reference for CFN Loop operations
-- Loop structure (Loops 0-4), mode selection (MVP/Standard/Enterprise), iteration limits
-- Redis coordination patterns, telemetry templates, retry strategies
-
-**[cfn-loop-flow-diagram.md](./cfn-loop-flow-diagram.md)**
-- Visual representation of CFN Loop execution flow
-- Loop transitions, gate checks, validator coordination
-
-**[cfn-loop-modes.md](./cfn-loop-modes.md)**
-- MVP mode (0.70/0.80), Standard mode (0.75/0.90), Enterprise mode (0.75/0.95)
-- Mode comparison, performance impacts, resource usage
-
-### System Features Documentation
-
-**[logs-features.md](./logs-features.md)**
-- Complete feature catalog: CFN Loop, swarm coordination, SQLite memory
-- Configuration options, usage patterns, performance metrics
-- Testing frameworks and monitoring capabilities
-
-**[additional-commands.md](./additional-commands.md)**
-- Specialized and infrequent commands
-- Fullstack development, SPARC methodology, fleet management, event bus
-- Enterprise-scale operations, testing, recovery operations
-
-**[COMPONENT_NPM_STATUS.md](./COMPONENT_NPM_STATUS.md)**
-- Complete inventory of all components available in the npm package
-- NPM package status for 200+ components across all categories
-- Implementation verification and coverage analysis
-
-### API and Integration Documentation
-
-**[logs-api.md](./logs-api.md)**
-- REST API, MCP Server APIs (30 essential tools), CLI APIs
-- Web portal API (REST + WebSocket), authentication/authorization
-- Endpoint documentation, request/response formats, error handling
-
-**[logs-slash-commands.md](./logs-slash-commands.md)**
-- Comprehensive slash command reference
-- CFN Loop, fullstack, SPARC, swarm management, agent lifecycle
-- Command syntax, parameters, usage examples
-
-### System Configuration and Integration
-
-**[logs-hooks.md](./logs-hooks.md)**
-- Automation hooks and integration points
-- Post-edit pipeline (TDD validation, security scanning, formatting)
-- Lifecycle hooks, git integration, event-driven automation
-
-**[logs-functions.md](./logs-functions.md)**
-- Utility functions and helper APIs
-- Memory management utilities, coordination helpers, performance optimization
-
-**[deprecated-logs-mcp.md](./deprecated-logs-mcp.md)** - ⚠️ DEPRECATED
-- Historical MCP documentation (removed in v2.0.0)
-- Migration guide to CLI-based architecture
-
-**[logs-cli-redis.md](./logs-cli-redis.md)**
-- Redis CLI integration and command reference
-- State management, coordination patterns, pub/sub messaging, swarm recovery
-
-### NPM Package Distribution
-
-**[command-naming.md](./command-naming.md)**
-- Binary naming strategy to avoid conflicts with existing `claude-flow` package
-- Commands: `claude-flow-novice` (main CLI), `cfn-spawn` (agent spawning utility)
-- Future expansion pattern: `cfn-*` for all utilities (cfn-monitor, cfn-doctor, etc.)
-- Namespace-safe command design, tab completion optimization
-
-**[npm-distribution-summary.md](./npm-distribution-summary.md)**
-- Executive summary of npm package preparation
-- Package configuration (15.3 MB, 1,401 files), included/excluded files
-- Publishing workflow, version management, testing results
-- Web portal separation strategy, post-installation setup
-
-**[installation-process.md](./installation-process.md)**
-- Complete npm installation workflow (download, extract, dependencies, binaries)
-- User experience during install: postinstall hooks, welcome messages
-- Installation methods: global (`npm install -g`), local, npx one-time use
-- Troubleshooting: permissions, native compilation (better-sqlite3), Redis setup
-- Installation metrics: timing, size, dependency count
-
-**[documentation-analysis.md](./documentation-analysis.md)**
-- Analysis of documentation overlaps and integration opportunities
-- File relationship mapping, merger recommendations
-- Modular vs consolidated documentation strategy
-
-### Indexes and Meta-Documentation
-
-**[logs-documentation-index.md](./logs-documentation-index.md)**
-- Master index of all logging and system documentation
-- Quick start guides, architecture overview, integration patterns
-- Document catalog with purpose/audience matrix
-
-**[COMPONENT_INVENTORY_TABLE.md](./COMPONENT_INVENTORY_TABLE.md)**
-- Comprehensive table of all features, slash commands, hooks, and agents
-- Component categorization with descriptions and NPM package planning
-- Complete system inventory for project management and planning
-
-**[CHANGELOG.md](./CHANGELOG.md)**
-- Version history and release notes (user-facing, included in npm package)
-- Sprint summaries, feature releases, bug fixes, migration guides
-
-**[log-changelog.md](./log-changelog.md)**
-- Detailed internal decision log (development-focused, excluded from npm)
-- Technical decisions, architecture changes, rationale documentation
-
-## Documentation Templates
-
-### Function Documentation
-```markdown
-## functionName
-
-**Purpose**: Brief statement of what the function does
-
-**Signature**: `function(param1, param2) -> returnType`
-
-**Parameters**:
-- `param1` (type): Description
-- `param2` (type): Description, optional
-
-**Returns**: Return type and description
-
-**Example**:
-```javascript
-const result = functionName(value1, value2);
-```
-
-**Use Cases**: When to use this function
-```
-
-### API Endpoint Documentation
-```markdown
-### METHOD /endpoint
-
-**Purpose**: What this endpoint does
-
-**Parameters**:
-- `param` (type, in: query/body): Description
-
-**Request**:
-```json
-{
-  "field": "value"
-}
-```
-
-**Response**:
-```json
-{
-  "status": "success"
-}
-```
-
-**Status Codes**: 200, 400, 401, 500
-
-**Example**:
-```bash
-curl -X POST /endpoint -d '{"field":"value"}'
-```
-```
-
-### Feature Documentation
-```markdown
-## Feature Name
-
-**Purpose**: What problem this solves
-
-**Usage**: How to use it
-
-**Configuration**: Available settings
-
-**Examples**: Practical implementations
-
-**Integration**: How it connects to other systems
-```
-
-### Command Documentation Template
-```markdown
-### /command-name [options]
-
-**Purpose**: Single sentence describing what it does
-
-**Usage**:
-```bash
-/command-name --flag value
-```
-
-**Flags**:
-- `--flag`: Description (type, default)
-
-**Output**: What the command returns
-
-**Example**:
-```bash
-/command-name --example input
-# Output: result
-```
-```
-
-## What NOT to Include
-
-### ❌ Marketing Language
-```markdown
-❌ "This revolutionary feature provides incredible 97% cost savings!"
-❌ "Our amazing CFN Loop system offers unparalleled performance!"
-❌ "The best-in-class coordination framework for enterprise teams!"
-```
-
-### ❌ Cost Optimization Details
-```markdown
-❌ "Worker agents cost $0.50 per phase versus $15 with pure Claude"
-❌ "Save 97% on coordination costs using hybrid routing"
-❌ "Token usage drops from 2M to 200K per phase"
-```
-
-**Why**: Agents don't need ongoing cost awareness. This information belongs in:
-- Project planning documents
-- Business case presentations
-- Architecture decision records (ADRs)
-- Pricing documentation for customers
-
-### ❌ Comparative Benchmarks
-```markdown
-❌ "40x faster than traditional approaches"
-❌ "Outperforms competitor X by 200%"
-❌ "Industry-leading throughput of 398,373 events/sec"
-```
-
-**Exception**: Internal performance metrics for optimization decisions are acceptable:
-```markdown
-✅ "Event Bus: 398,373 events/sec, 2.5μs latency, 99.87% cache hit rate"
-```
-
-### ❌ Verbose Explanations
-```markdown
-❌ "This function can be used to initialize the swarm. It will create a
-    new swarm instance that is configured with the topology you specify.
-    You should use this before spawning any agents."
-```
-
-**Use instead**:
-```markdown
-✅ Initialize swarm with specified topology. Required before agent spawning.
-
-   **Signature**: `swarmInit(topology, maxAgents) -> swarmId`
-
-   **Example**:
-   ```javascript
-   const id = swarmInit('mesh', 5);
-   ```
-```
-
-### ❌ Motivational Content
-```markdown
-❌ "With this powerful feature, you'll be able to accomplish..."
-❌ "This exciting capability enables teams to..."
-❌ "Unlock the potential of your workflow by..."
-```
-
-### ❌ Future Promises
-```markdown
-❌ "Coming soon: distributed consensus across regions"
-❌ "Planned enhancements include..."
-❌ "Future versions will support..."
-```
-
-### ❌ Opinions and Recommendations Without Context
-```markdown
-❌ "Always use Enterprise mode for best results"
-❌ "MVP mode is not recommended"
-❌ "This is the preferred approach for most use cases"
-```
-
-**Use instead**:
-```markdown
-✅ **Mode Selection**:
-   - MVP: Prototypes, fast iteration (Gate: 0.70, Consensus: 0.80)
-   - Standard: General features (Gate: 0.75, Consensus: 0.90)
-   - Enterprise: Production systems (Gate: 0.75, Consensus: 0.95)
-```
-
-## Sparse Language Rules
-
-### Active Voice (Required)
-- ✅ "Returns data from Redis"
-- ❌ "Data is returned from Redis"
-
-### Present Tense (Required)
-- ✅ "Initializes swarm"
-- ❌ "Will initialize swarm"
-
-### No Fluff (Required)
-- ✅ "Monitor CI/CD pipeline status"
-- ❌ "This command can be used to monitor your CI/CD pipeline status"
-
-### Minimal Examples (Required)
-- ✅ `swarmInit('mesh', 5)`
-- ❌ Long multi-line examples with excessive comments
-
-### Direct Description (Required)
-- ✅ "Execute autonomous workflow"
-- ❌ "This feature allows you to execute a workflow autonomously"
-
-## File Naming Convention
-
-- **kebab-case** for all markdown files
-- **Prefix with category** (logs-, api-, cli-, etc.)
-- **Descriptive names** that clearly indicate content
-
-## Code Examples
-
-- **Minimal** - show only what's necessary
-- **Working** - all examples must be tested
-- **Contextual** - include imports/dependencies if needed
-- **Commented** - explain non-obvious parts
-
-## Cross-References
-
-- Use relative paths: `[API](./logs-api.md)`
-- Reference specific sections: `[Functions](./logs-functions.md#core-functions)`
-- Link external resources with full URLs
-
-## Quick Navigation by Use Case
-
-### Getting Started with v2
-1. [README.md](./README.md) - v2 overview and quick start
-2. [log-skills.md](./log-skills.md) - Skills system fundamentals
-3. [CFN_LOOP_CHEATSHEET.md](./CFN_LOOP_CHEATSHEET.md) - Quick reference
-
-### Getting Started with CFN Loop
-1. [CFN_LOOP_CHEATSHEET.md](./CFN_LOOP_CHEATSHEET.md) - Quick reference
-2. [cfn-loop-modes.md](./cfn-loop-modes.md) - Mode selection
-3. [cfn-loop-flow-diagram.md](./cfn-loop-flow-diagram.md) - Visual flow
-
-### NPM Package Distribution & Publishing
-1. [npm-distribution-summary.md](./npm-distribution-summary.md) - Quick overview & status
-2. [installation-process.md](./installation-process.md) - User installation experience
-3. [command-naming.md](./command-naming.md) - Command naming strategy
-4. [CHANGELOG.md](./CHANGELOG.md) - Version history (include in package)
-5. [../PUBLISH.md](../PUBLISH.md) - Publishing checklist
-6. [../NPM_DISTRIBUTION_GUIDE.md](../NPM_DISTRIBUTION_GUIDE.md) - Complete guide
-
-### Skills Development
-1. [log-skills.md](./log-skills.md) - Complete skills guide
-2. [logs-cli-redis.md](./logs-cli-redis.md) - Redis coordination patterns
-3. [logs-hooks.md](./logs-hooks.md) - Hook pipeline integration
-
-### System Administration
-1. [logs-slash-commands.md](./logs-slash-commands.md) - CLI operations
-2. [logs-cli-redis.md](./logs-cli-redis.md) - Redis operations
-3. [additional-commands.md](./additional-commands.md) - Advanced commands
-4. [COMPONENT_NPM_STATUS.md](./COMPONENT_NPM_STATUS.md) - Package implementation verification
-
-### API Integration
-1. [logs-api.md](./logs-api.md) - REST/MCP/CLI APIs
-2. [logs-hooks.md](./logs-hooks.md) - Hook integration
-3. [logs-functions.md](./logs-functions.md) - Utility functions
-
-### Feature Discovery
-1. [logs-features.md](./logs-features.md) - Complete feature catalog
-2. [logs-documentation-index.md](./logs-documentation-index.md) - Documentation map
-3. [COMPONENT_INVENTORY_TABLE.md](./COMPONENT_INVENTORY_TABLE.md) - Complete system inventory
-4. [COMPONENT_NPM_STATUS.md](./COMPONENT_NPM_STATUS.md) - NPM package implementation status
-5. [CHANGELOG.md](./CHANGELOG.md) - Recent additions
-
-### Legacy Documentation
-1. [deprecated-logs-mcp.md](./deprecated-logs-mcp.md) - Historical MCP implementation
-2. [../legacy/readme-v1/](../legacy/readme-v1/) - Complete v1 documentation
-
-## Maintenance
-
-- **Version tracking** - update examples with API changes
-- **Deprecation notices** - clearly mark outdated information
-- **Testing** - verify code examples work
-- **Reviews** - regular accuracy checks
-
-## Related Resources
-
-- **Main Documentation**: [../CLAUDE.md](../CLAUDE.md) - Critical Rules and core workflows
-- **Planning Docs**: [../planning/](../planning/) - Epic configurations and CFN Loop strategies
-- **Reports**: [../reports/](../reports/) - Testing and security validation reports
-- **Configuration**: [../config/](../config/) - CFN Loop criteria and hook configurations
-- **Component Inventory**: [./COMPONENT_INVENTORY_TABLE.md](./COMPONENT_INVENTORY_TABLE.md) - Complete system component catalog
-- **Package Status**: [./COMPONENT_NPM_STATUS.md](./COMPONENT_NPM_STATUS.md) - NPM implementation verification
-
----
-
-*All documentation follows sparse, concise language philosophy: practical examples over theory, minimal direct explanations, code snippets for common operations.*