claude-flow-novice 2.3.9 → 2.4.1

package/SYNC_USAGE.md

@@ -0,0 +1,191 @@
+# Claude Flow Novice - Sync Guide
+
+## Installation & Setup
+
+### 1. Install Package
+
+```bash
+npm install claude-flow-novice
+```
+
+### 2. Sync Agents, Commands, and Hooks
+
+After installation, sync the latest agents, slash commands, and validation hooks to your project:
+
+```bash
+# Sync everything with backup
+npx claude-flow-sync --backup
+
+# Or use the longer form
+node node_modules/claude-flow-novice/scripts/sync-from-package.js --backup
+```
+
+## Sync Options
+
+### Sync Everything (Recommended for first time)
+
+```bash
+npx claude-flow-sync --backup
+```
+
+This syncs:
+- `.claude/agents/` - All agent definitions (94 files)
+- `.claude/commands/` - Slash commands
+- `config/hooks/` - Validation hooks
+
+### Selective Sync
+
+```bash
+# Sync only agents
+npx claude-flow-sync --agents --backup
+
+# Sync only commands
+npx claude-flow-sync --commands --backup
+
+# Sync only hooks
+npx claude-flow-sync --hooks --backup
+
+# Combine multiple
+npx claude-flow-sync --agents --hooks --backup
+```
+
+### Force Overwrite
+
+Use `--force` to overwrite existing files without prompting:
+
+```bash
+npx claude-flow-sync --force --backup
+```
+
+**⚠️ Warning**: `--force` will overwrite your customizations. Always use `--backup` with `--force`.
+
+## Update Workflow
+
+### When Package Updates
+
+```bash
+# 1. Update package
+npm update claude-flow-novice
+
+# 2. Sync new changes (creates backup automatically)
+npx claude-flow-sync --backup
+
+# 3. Review changes
+git diff .claude/ config/
+
+# 4. Merge customizations if needed
+# Restore from .backup-YYYY-MM-DD if you need your custom changes
+```
+
+### Customizing Agents/Commands
+
+1. **Initial sync**:
+   ```bash
+   npx claude-flow-sync --backup
+   ```
+
+2. **Customize** your local copies in:
+   - `.claude/agents/`
+   - `.claude/commands/`
+   - `config/hooks/`
+
+3. **Update from package** (preserves your changes):
+   ```bash
+   # WITHOUT --force, you'll be warned about existing files
+   npx claude-flow-sync --backup
+   
+   # Review what changed in the package
+   diff -r .claude/agents/ .claude/agents.backup-YYYY-MM-DD/
+   
+   # Manually merge changes you want
+   ```
+
+## File Locations After Sync
+
+```
+your-project/
+├── .claude/
+│   ├── agents/           # ✅ Synced from package (94 files)
+│   └── commands/         # ✅ Synced from package
+├── config/
+│   └── hooks/            # ✅ Synced from package (13+ files)
+└── node_modules/
+    └── claude-flow-novice/
+        ├── .claude/      # Source (in npm package)
+        ├── config/       # Source (in npm package)
+        └── scripts/      # Source (in npm package)
+```
+
+## Backup Management
+
+Backups are created as:
+- `.claude/agents.backup-2025-10-17/`
+- `.claude/commands.backup-2025-10-17/`
+- `config/hooks.backup-2025-10-17/`
+
+### Restore from Backup
+
+```bash
+# If you need to restore
+rm -rf .claude/agents/
+mv .claude/agents.backup-2025-10-17/ .claude/agents/
+```
+
+## Examples
+
+### First-Time Setup
+```bash
+npm install claude-flow-novice
+npx claude-flow-sync --backup
+```
+
+### Regular Updates
+```bash
+npm update claude-flow-novice
+npx claude-flow-sync --backup
+# Review changes with: git diff
+```
+
+### Force Update Everything
+```bash
+npx claude-flow-sync --force --backup
+```
+
+### Update Only Hooks (Get Latest Validators)
+```bash
+npx claude-flow-sync --hooks --force --backup
+```
+
+## What Gets Synced
+
+| Directory | Files | Description |
+|-----------|-------|-------------|
+| `.claude/agents/` | 94 | Agent definitions (optimized, Phase 4) |
+| `.claude/commands/` | 50+ | Slash commands |
+| `config/hooks/` | 13+ | Validation hooks (post-edit, etc.) |
+
+## What Doesn't Get Synced
+
+- `scripts/` - Only package utilities, not project-specific scripts
+- `readme/` - Package documentation (not project-specific)
+- `src/` - Package source code (not for project use)
+
+## Troubleshooting
+
+### "Source directory not found"
+Your package might be outdated. Update it:
+```bash
+npm update claude-flow-novice
+```
+
+### "Destination exists" Warning
+Without `--force`, sync won't overwrite. Use:
+```bash
+npx claude-flow-sync --force --backup
+```
+
+### Lost Customizations
+Restore from backup:
+```bash
+mv .claude/agents.backup-YYYY-MM-DD/ .claude/agents/
+```

package/config/hooks/post-edit-pipeline.js

@@ -1480,6 +1480,43 @@ class UnifiedPostEditPipeline {
         }
 
         const projectDir = this.findProjectRoot(filePath);
+
+        // TypeScript incremental type checking (single-file mode)
+        if (language === 'typescript' && tool === 'tsc') {
+            const tsArgs = [...args, '--skipLibCheck', filePath];
+
+            try {
+                const result = await this.runCommand(tool, tsArgs, projectDir);
+
+                // Parse TypeScript error output from both stdout and stderr
+                const allOutput = result.stdout + result.stderr;
+                const errorLines = allOutput.split('\n').filter(line => line.includes('error TS'));
+                const errorCount = errorLines.length;
+
+                return {
+                    success: result.code === 0 && errorCount === 0,
+                    message: result.code === 0 ? 'TypeScript compilation passed' : `${errorCount} TypeScript error(s)`,
+                    output: allOutput,
+                    errors: errorCount > 0 ? errorLines.join('\n') : '',
+                    errorCount,
+                    errorLines: errorLines.slice(0, 10), // First 10 errors for feedback
+                    wasmAccelerated
+                };
+            } catch (error) {
+                // Handle TypeScript compiler crashes gracefully
+                return {
+                    success: false,
+                    message: 'TypeScript compiler error',
+                    output: error.message || error.stderr || '',
+                    errors: error.message || 'TypeScript compilation failed',
+                    errorCount: 1,
+                    errorLines: [(error.message || 'Unknown compiler error')],
+                    wasmAccelerated
+                };
+            }
+        }
+
+        // Standard type checking for other languages
         const result = await this.runCommand(tool, args, projectDir);
 
         return {
@@ -2126,6 +2163,18 @@ class UnifiedPostEditPipeline {
         if (!results.steps.typeCheck.success) {
             results.summary.errors.push(`Type errors in ${path.basename(filePath)}`);
             results.summary.success = false;
+
+            // Send TYPE_ERROR feedback to agent
+            await this.sendAgentFeedback({
+                type: 'TYPE_ERROR',
+                file: filePath,
+                severity: 'error',
+                language,
+                errorCount: results.steps.typeCheck.errorCount || 0,
+                errorLines: results.steps.typeCheck.errorLines || [],
+                errors: results.steps.typeCheck.errors,
+                message: `${results.steps.typeCheck.errorCount || 'Unknown'} TypeScript error(s) in ${path.basename(filePath)}`
+            });
         }
 
         // Step 4: Rust Quality Enforcement (if Rust and strict mode)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow-novice",
-  "version": "2.3.9",
+  "version": "2.4.1",
   "description": "AI Agent Orchestration CLI",
   "main": "src/index.ts",
   "bin": {
@@ -12,6 +12,7 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
+    "SYNC_USAGE.md",
     "config",
     "scripts",
     ".claude",
@@ -22,6 +23,8 @@
     "clean": "rimraf dist",
     "lint": "eslint . --ext .ts",
     "typecheck": "tsc --noEmit",
+    "type-coverage": "type-coverage --detail --ignore-files 'src/__tests__/**' --ignore-files '**/*.test.ts'",
+    "type-coverage:ci": "type-coverage --at-least 80 --ignore-files 'src/__tests__/**' --ignore-files '**/*.test.ts'",
     "test": "jest",
     "test:coverage": "jest --coverage",
     "prepublish-checks": "node scripts/prepublish-checks.js",
@@ -29,7 +32,8 @@
     "security-scan": "snyk test && npm audit --audit-level=high",
     "bundle-size-check": "bundlesize",
     "smoke-test": "npm pack && node scripts/smoke-test.js",
-    "changelog": "standard-version"
+    "changelog": "standard-version",
+    "create:component": "node scripts/create-component.js"
   },
   "keywords": [
     "ai",
@@ -54,15 +58,19 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "jest": "^29.0.0",
+    "bundlesize": "^0.18.1",
     "eslint": "^8.0.0",
-    "rollup": "^3.0.0",
+    "husky": "^8.0.0",
+    "jest": "^29.0.0",
     "rimraf": "^5.0.0",
-    "bundlesize": "^0.18.1",
-    "snyk": "^1.0.0",
+    "rollup": "^3.0.0",
     "semantic-release": "^21.0.0",
+    "snyk": "^1.0.0",
     "standard-version": "^9.0.0",
-    "husky": "^8.0.0"
+    "type-coverage": "^2.29.7",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "ioredis": "^5.8.1"
   }
 }

package/scripts/create-component.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * Component Template Generator
+ * Creates TypeScript components with proper type declarations and tests
+ *
+ * Usage:
+ *   node scripts/create-component.js <ComponentName> <directory>
+ *
+ * Example:
+ *   node scripts/create-component.js SwarmCoordinator src/coordination
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const [, , componentName, componentDir] = process.argv;
+
+if (!componentName || !componentDir) {
+  console.log(`
+🔧 Component Template Generator
+
+Usage: node scripts/create-component.js <ComponentName> <directory>
+
+Arguments:
+  ComponentName    Name of the component (PascalCase)
+  directory        Target directory (e.g., src/coordination)
+
+Examples:
+  node scripts/create-component.js SwarmCoordinator src/coordination
+  node scripts/create-component.js TaskValidator src/validation
+  node scripts/create-component.js RedisClient src/services
+
+Generated files:
+  ✅ <directory>/<ComponentName>.ts        - Main implementation
+  ✅ <directory>/<ComponentName>.test.ts   - Test file with basic setup
+  ✅ <directory>/types.ts                  - Type definitions (if doesn't exist)
+  `);
+  process.exit(1);
+}
+
+const projectRoot = path.resolve(__dirname, '..');
+
+// Validate component name (PascalCase)
+if (!/^[A-Z][a-zA-Z0-9]*$/.test(componentName)) {
+  console.error(`❌ Error: Component name must be PascalCase (e.g., SwarmCoordinator, not swarm-coordinator)`);
+  process.exit(1);
+}
+
+// Create directory if it doesn't exist
+const targetDir = path.join(projectRoot, componentDir);
+if (!fs.existsSync(targetDir)) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  console.log(`📁 Created directory: ${componentDir}/`);
+}
+
+// Component file template
+const componentTemplate = `/**
+ * ${componentName}
+ *
+ * TODO: Add component description
+ */
+
+export interface ${componentName}Options {
+  // TODO: Define configuration options
+}
+
+export class ${componentName} {
+  private options: ${componentName}Options;
+
+  constructor(options: ${componentName}Options) {
+    this.options = options;
+  }
+
+  // TODO: Implement methods
+  async initialize(): Promise<void> {
+    // Initialization logic
+  }
+
+  async execute(): Promise<void> {
+    // Main execution logic
+  }
+
+  async cleanup(): Promise<void> {
+    // Cleanup logic
+  }
+}
+`;
+
+// Test file template
+const testTemplate = `import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { ${componentName} } from './${componentName}';
+
+describe('${componentName}', () => {
+  let component: ${componentName};
+
+  beforeEach(() => {
+    component = new ${componentName}({
+      // TODO: Add test configuration
+    });
+  });
+
+  afterEach(async () => {
+    await component.cleanup();
+  });
+
+  describe('initialization', () => {
+    it('should initialize successfully', async () => {
+      await component.initialize();
+      // TODO: Add assertions
+      expect(component).toBeDefined();
+    });
+  });
+
+  describe('execution', () => {
+    it('should execute successfully', async () => {
+      await component.initialize();
+      await component.execute();
+      // TODO: Add assertions
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle errors gracefully', async () => {
+      // TODO: Test error scenarios
+    });
+  });
+});
+`;
+
+// Types file template (only create if doesn't exist)
+const typesTemplate = `/**
+ * Type definitions for ${componentDir}
+ */
+
+export interface BaseOptions {
+  enabled?: boolean;
+  debug?: boolean;
+}
+
+// Add shared types here
+`;
+
+// Write component file
+const componentPath = path.join(targetDir, `${componentName}.ts`);
+if (fs.existsSync(componentPath)) {
+  console.error(`❌ Error: Component file already exists: ${componentPath}`);
+  process.exit(1);
+}
+fs.writeFileSync(componentPath, componentTemplate);
+console.log(`✅ Created: ${path.relative(projectRoot, componentPath)}`);
+
+// Write test file
+const testPath = path.join(targetDir, `${componentName}.test.ts`);
+if (fs.existsSync(testPath)) {
+  console.warn(`⚠️  Warning: Test file already exists: ${testPath} (skipping)`);
+} else {
+  fs.writeFileSync(testPath, testTemplate);
+  console.log(`✅ Created: ${path.relative(projectRoot, testPath)}`);
+}
+
+// Create types file if doesn't exist
+const typesPath = path.join(targetDir, 'types.ts');
+if (!fs.existsSync(typesPath)) {
+  fs.writeFileSync(typesPath, typesTemplate);
+  console.log(`✅ Created: ${path.relative(projectRoot, typesPath)}`);
+} else {
+  console.log(`ℹ️  Types file exists: ${path.relative(projectRoot, typesPath)} (not modified)`);
+}
+
+// Create index.ts barrel export if doesn't exist
+const indexPath = path.join(targetDir, 'index.ts');
+const exportLine = `export * from './${componentName}';\n`;
+
+if (fs.existsSync(indexPath)) {
+  const content = fs.readFileSync(indexPath, 'utf8');
+  if (!content.includes(`from './${componentName}'`)) {
+    fs.appendFileSync(indexPath, exportLine);
+    console.log(`✅ Added export to: ${path.relative(projectRoot, indexPath)}`);
+  } else {
+    console.log(`ℹ️  Export already exists in: ${path.relative(projectRoot, indexPath)}`);
+  }
+} else {
+  fs.writeFileSync(indexPath, `export * from './types';\n${exportLine}`);
+  console.log(`✅ Created: ${path.relative(projectRoot, indexPath)}`);
+}
+
+console.log(`
+✨ Component generated successfully!
+
+Next steps:
+  1. Implement ${componentName} logic in ${componentPath}
+  2. Write tests in ${testPath}
+  3. Run tests: npm test -- ${componentName}
+  4. Run type check: npm run typecheck
+`);

package/src/cli/hybrid-routing/spawn-workers.js

@@ -923,7 +923,8 @@ Execute the task using available tools. Report confidence score (0.0-1.0) at the
       const MAX_TOOL_ITERATIONS = 1000; // Increased from 25 to allow comprehensive optimization tasks
       let content = '';
 
-      // Tool use loop
+      // Tool use loop with context window management
+      const MAX_CONTEXT_MESSAGES = 20; // Keep only last 20 messages
       while (toolUseCount < MAX_TOOL_ITERATIONS) {
         const response = await this.anthropic.createMessage({
           model: this.model,
@@ -979,6 +980,12 @@ Execute the task using available tools. Report confidence score (0.0-1.0) at the
         });
 
         toolUseCount++;
+
+        // Trim context window to prevent memory leak
+        if (messages.length > MAX_CONTEXT_MESSAGES) {
+          // Keep first message (initial task) + last N messages
+          messages = [messages[0], ...messages.slice(-MAX_CONTEXT_MESSAGES + 1)];
+        }
       }
 
       if (toolUseCount >= MAX_TOOL_ITERATIONS) {
@@ -1103,7 +1110,7 @@ Execute the task using available tools. Report confidence score (0.0-1.0) at the
   }
 
   /**
-   * Recursively scan directory for .md files
+   * Recursively scan directory for .md files (excludes node_modules)
    */
   async scanAgentFiles(dirPath, basePath) {
     const { promises: fs } = await import('fs');
@@ -1115,6 +1122,11 @@ Execute the task using available tools. Report confidence score (0.0-1.0) at the
       const entries = await fs.readdir(dirPath, { withFileTypes: true });
 
       for (const entry of entries) {
+        // Skip node_modules to prevent memory leak
+        if (entry.name === 'node_modules') {
+          continue;
+        }
+
         const fullPath = path.join(dirPath, entry.name);
 
         if (entry.isDirectory()) {

package/src/cli/simple-commands/init/templates/CLAUDE.md

@@ -1,5 +1,7 @@
 # Claude Flow Novice — AI Agent Orchestration
 
+**🚀 Production Status:** Redis coordination system fully deployed (Phase 7 - 2025-10-17)
+
 ---
 
 ## 1) Critical Rules (Single Source of Truth)
@@ -11,12 +13,13 @@
 * Agents communicate via Redis pub/sub with explicit dependencies (see `.claude/redis-agent-dependencies.md`)
 
 **Core Principles:**
-* Use agents for all non-trivial work (≥4 steps or multi-file/research/testing/architecture/security)
+* Use agents for all non-trivial work (≥3 steps or multi-file/research/testing/architecture/security)
 * **PRIMARY COORDINATOR: Use coordinator-hybrid for all multi-agent coordination** (cost-optimized CLI spawning with typed agents)
 * Initialize swarm before multi-agent work
 * Batch operations: spawn ALL agents (coordinator + workers) in single message
 * Run post-edit hook after every file edit
 * **REQUIRED: All CLI agent spawning must use explicit --agents flag with typed agents**
+* **Context continuity:** Redis/SQLite persistence enables unlimited continuation — never stop due to context/token concerns
 
 **Prohibited Patterns:**
 * Main chat orchestrating agents directly — spawn coordinator to handle orchestration
@@ -25,11 +28,12 @@
 * Using generic "coordinator" fallback when coordinator-hybrid available
 * Spawning agents without explicit --agents flag (must specify types from AVAILABLE-AGENTS.md)
 * Agent coordination without Redis pub/sub messaging — ALL agents must use Redis
-* Running tests inside agents — execute once; agents read results
+* Running tests inside agents — coordinator runs tests ONCE; workers read cached results from test-results.json
 * Concurrent test runs — terminate previous runs first
 * **Saving to project root — check `.artifacts/logs/post-edit-pipeline.log` after writes; move files if ROOT_WARNING**
 * Creating guides/summaries/reports unless explicitly asked
-* Asking permission to retry/advance when criteria/iterations allow. Instead relaunch agents
+* Asking permission to retry/advance when criteria/iterations allow — **relaunch agents immediately when consensus <threshold and iterations <max**
+* Stopping work due to context/token concerns — Redis/SQLite persistence handles continuation automatically
 
 **Communication:**
 * Use spartan language
@@ -121,15 +125,28 @@ If file created in root, hook returns `status: "ROOT_WARNING"` with `rootWarning
 
 ### 3.3 Safe Test Execution
 
+**Pattern: Coordinator runs tests ONCE before spawning workers**
+
 ```bash
-# Run once, save results
+# 1. Coordinator terminates any existing test runs
+pkill -f vitest; pkill -f "npm test"
+
+# 2. Coordinator runs tests once and caches results
 npm test -- --run --reporter=json > test-results.json 2>&1
-# Agents read results only
+
+# 3. Workers read cached results only (no test execution)
 cat test-results.json
-# Cleanup
+
+# 4. Cleanup after all work complete
 pkill -f vitest; pkill -f "npm test"
 ```
 
+**Rules:**
+* Coordinator executes tests before worker spawn
+* Workers ONLY read test-results.json (never run tests)
+* Single test execution prevents concurrent run conflicts
+* Cache results in test-results.json for worker consumption
+
 ### 3.4 Batching (One message = all related ops)
 
 * Spawn all agents with Task tool in one message
@@ -197,6 +214,47 @@ mv test.txt src/test.txt  # Move to suggested location
 
 **→ Pattern: `.claude/coordinator-feedback-pattern.md`**
 
+### 6.3 Dashboard Integration (Phase 5)
+
+**Real-time Dashboard:**
+- URL: http://localhost:3001 (RealtimeServer)
+- WebSocket: ws://localhost:3001/ws
+- Components: RedisCoordinationMonitor.tsx
+
+**REST API Endpoints:**
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| /api/redis/feedback | GET | Recent feedback (limit=100) |
+| /api/redis/metrics | GET | Current metrics snapshot |
+| /api/swarm/status | GET | Current swarm coordination status |
+
+**CLI Monitoring Commands:**
+```bash
+# Monitor feedback
+./scripts/monitor-swarm-redis.sh feedback
+
+# Monitor CFN Loop
+./scripts/monitor-swarm-redis.sh coordination
+
+# Realtime dashboard launch
+npx claude-flow-novice dashboard --port 3001
+```
+
+**Post-Spawn Validation:**
+```bash
+# Validate CLI agent
+node config/hooks/post-spawn-validation.js coder-1
+
+# Validate Task agent
+node config/hooks/post-spawn-validation.js task_abc123 --coordinator-id coordinator-cfn
+```
+
+**WebSocket Event Types:**
+- `swarm:coordination`
+- `agent:feedback`
+- `system:metrics`
+- `dashboard:status`
+
 ---
 
 ## 7) Commands & Setup

package/src/index.ts

@@ -27,10 +27,10 @@ export const AgentType = {
   API_DOCS: 'api-docs',
   BACKEND_DEV: 'backend-dev',
   FRONTEND_DEV: 'frontend-dev',
-  MOBILE_DEV: 'mobile-dev'
+  MOBILE_DEV: 'mobile-dev',
 } as const;
 
-export type AgentType = typeof AgentType[keyof typeof AgentType];
+export type AgentType = (typeof AgentType)[keyof typeof AgentType];
 
 // Version
 export const VERSION = '2.0.4';
@@ -41,6 +41,6 @@ export const defaultConfig = {
   strategy: 'development',
   mode: 'mesh',
   persistence: true,
-  consensusThreshold: 0.90,
-  gateThreshold: 0.75
+  consensusThreshold: 0.9,
+  gateThreshold: 0.75,
 };