claude-flow-novice 1.5.10 → 1.5.12

package/CLAUDE.md

@@ -1,78 +1,62 @@
-# Claude Code Configuration - react-typescript Development Environment
+# Claude Flow Novice - AI Agent Orchestration
 
-## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
+## Core Orchestration Patterns
+
+## 🚨 CRITICAL: MANDATORY AGENT-BASED EXECUTION
+
+**YOU MUST USE AGENTS FOR ALL NON-TRIVIAL WORK - NO EXCEPTIONS**
 
 **ABSOLUTE RULES**:
-1. ALL operations MUST be concurrent/parallel in a single message
-2. **NEVER save working files, text/mds and tests to the root folder**
-3. ALWAYS organize files in appropriate subdirectories
-4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
+1. **ALWAYS USE AGENTS** - Tasks requiring >3 steps MUST use agent coordination
+2. **ALWAYS INITIALIZE SWARM** - ANY multi-agent task requires swarm_init FIRST
+3. **ALWAYS RUN POST-EDIT HOOKS** - After EVERY file edit without exception
+4. **ALWAYS BATCH OPERATIONS** - 1 MESSAGE = ALL RELATED OPERATIONS
+5. **NEVER WORK SOLO** - Spawn multiple agents in parallel for ALL significant tasks
+6. **NEVER SAVE TO ROOT** - Organize files in appropriate subdirectories
+7. **USE CLAUDE CODE'S TASK TOOL** - For spawning agents concurrently, not just MCP
+
+### 🚫 WHEN YOU MUST USE AGENTS (MANDATORY)
+
+**TRIGGER CONDITIONS - If ANY apply, you MUST spawn agents:**
+- Task requires >3 distinct steps
+- Multiple files need to be created or modified
+- Need research + implementation + testing
+- Architecture or design decisions required
+- Code review or quality validation needed
+- Security, performance, or compliance concerns
+- Integration across multiple systems/components
+- Documentation generation needed
+- Refactoring or optimization work
+- ANY feature development (even "simple" ones)
+
+### Agent Requirements by Task Complexity
+
+| Task Size | Steps | Agent Count | Example Team Composition |
+|-----------|-------|-------------|--------------------------|
+| **Simple** | 3-5 | 2-3 agents | coder + tester + reviewer |
+| **Medium** | 6-10 | 4-6 agents | + researcher + architect + security-specialist |
+| **Complex** | 11-20 | 8-12 agents | Full specialist team with domain experts |
+| **Enterprise** | 20+ | 15-20 agents | + devops + api-docs + perf-analyzer + coordinators |
 
 ### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
 
 **MANDATORY PATTERNS:**
+- **Agent Spawning**: ALWAYS spawn ALL required agents in ONE message using Task tool
 - **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
 - **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
 - **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
 - **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
 - **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
 
-### 🎯 CRITICAL: Claude Code Task Tool for Agent Execution
-
-**Claude Code's Task tool is the PRIMARY way to spawn agents:**
-```javascript
-// ✅ CORRECT: Use Claude Code's Task tool for parallel agent execution
-[Single Message]:
-  Task("Research agent", "Analyze requirements and patterns...", "researcher")
-  Task("Coder agent", "Implement core features...", "coder")
-  Task("Tester agent", "Create comprehensive tests...", "tester")
-  Task("Reviewer agent", "Review code quality...", "reviewer")
-  Task("Architect agent", "Design system architecture...", "system-architect")
-```
-
-## Project Overview
-
-**Project Type**: react-typescript
-**Primary Language**: javascript
-**Primary Framework**: react
-**Package Manager**: npm
-**Build Tools**: none
-
-**Detected Languages**: javascript, typescript, rust, python
-**Detected Frameworks**: react, express, vue, django, flask, nextjs, angular, spring, fastapi
-**Project Directories**: src
-
-*Auto-generated on 2025-09-30*
-
-## 📁 File Organization Rules
-
-**NEVER save to root folder. Use these directories:**
-- `/src` - Source code files
-- `/tests` - Test files
-- `/docs` - Documentation and markdown files
-- `/config` - Configuration files
-- `/scripts` - Utility scripts
-- `/examples` - Example code
-
-## 🚀 Available Agent Types
-
-### Core Development
-`coder`, `reviewer`, `tester`, `planner`, `researcher`
-
-### Backend Development
-`backend-dev`, `api-docs`, `system-architect`, `code-analyzer`
-
-### Frontend Development
-`mobile-dev` (React Native), specialized frontend agents
-
-### Testing & Validation
-`tdd-london-swarm`, `production-validator`
+### ⚠️ PROHIBITED SOLO WORK
 
-### GitHub & Repository Management
-`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`
-
-### Performance & Optimization
-`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`
+**YOU ARE FORBIDDEN FROM:**
+- ❌ Working alone on multi-step tasks
+- ❌ Implementing features without agent coordination
+- ❌ Skipping agent spawning because "it's simple"
+- ❌ Writing code without a tester agent
+- ❌ Making architectural decisions without an architect agent
+- ❌ Deploying without security review from security-specialist agent
 
 ## 🎯 Claude Code vs MCP Tools
 
@@ -82,1909 +66,337 @@
 - Code generation and programming
 - Bash commands and system operations
 - Implementation work
+- Project navigation and analysis
+- TodoWrite and task management
+- Git operations
+- Package management
+- Testing and debugging
 
 ### MCP Tools ONLY COORDINATE:
 - Swarm initialization (topology setup)
 - Agent type definitions (coordination patterns)
 - Task orchestration (high-level planning)
 - Memory management
+- Neural features
 - Performance tracking
+- GitHub integration
 
 **KEY**: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.
 
-## 📋 Agent Coordination Protocol
-
-### Every Agent Spawned via Task Tool MUST:
+### Agent Coordination Framework
 
-**1️⃣ BEFORE Work:**
+#### Pre-Task Hooks (Setup & Validation)
 ```bash
-npx claude-flow@alpha hooks pre-task --description "[task]"
-npx claude-flow@alpha hooks session-restore --session-id "swarm-[id]"
-```
+# Validate safety and prepare resources
+npx claude-flow-novice hooks pre-command --command "[command]" --validate-safety true --prepare-resources true
 
-**2️⃣ DURING Work:**
-```bash
-npx claude-flow@alpha hooks post-edit --file "[file]" --memory-key "swarm/[agent]/[step]"
-npx claude-flow@alpha hooks notify --message "[what was done]"
+# Auto-assign agents and load context
+npx claude-flow-novice hooks pre-edit --file "[file]" --auto-assign-agents true --load-context true
 ```
 
-**3️⃣ AFTER Work:**
+#### Post-Task Hooks (Validation & Quality)
 ```bash
-npx claude-flow@alpha hooks post-task --task-id "[task]"
-npx claude-flow@alpha hooks session-end --export-metrics true
-```
+# Track metrics and store results
+npx claude-flow-novice hooks post-command --command "[command]" --track-metrics true --store-results true
 
-## Build & Development Commands
+# Enhanced post-edit pipeline with comprehensive TDD validation
+npx enhanced-hooks post-edit "[file]" --memory-key "swarm/[agent]/[step]" --minimum-coverage 80 --structured
 
-```bash
-# Package management
-npm install
-npm run build
-npm run test
-npm run lint
-
-# Claude Flow commands
-npx claude-flow@alpha init
-npx claude-flow@alpha hooks setup
-npx claude-flow@alpha memory store
-```
-
-## Javascript Configuration
-
-### JavaScript Development Patterns
-
-**Code Style & Standards:**
-- Use ES6+ features (arrow functions, destructuring, modules)
-- Prefer `const`/`let` over `var`
-- Use async/await over Promise chains
-- Implement proper error boundaries
-- Follow ESLint/Prettier configurations
-
-**Concurrent Agent Execution:**
-```javascript
-// ✅ CORRECT: JavaScript development with concurrent agents
-[Single Message]:
-  Task("Frontend Developer", "Build responsive UI with modern JavaScript", "coder")
-  Task("API Developer", "Create REST endpoints with Express/Fastify", "backend-dev")
-  Task("Test Engineer", "Write Jest/Vitest tests with >85% coverage", "tester")
-  Task("Build Engineer", "Configure Webpack/Vite build system", "system-architect")
-  Task("Quality Reviewer", "Review code quality and performance", "reviewer")
-
-  // Batch all file operations
-  Write("src/app.js")
-  Write("src/api/routes.js")
-  Write("tests/app.test.js")
-  Write("webpack.config.js")
-
-  // Batch todos for tracking
-  TodoWrite({ todos: [
-    {content: "Set up project structure", status: "in_progress", activeForm: "Setting up project structure"},
-    {content: "Implement core modules", status: "pending", activeForm: "Implementing core modules"},
-    {content: "Add error handling", status: "pending", activeForm: "Adding error handling"},
-    {content: "Write comprehensive tests", status: "pending", activeForm: "Writing comprehensive tests"},
-    {content: "Configure build pipeline", status: "pending", activeForm: "Configuring build pipeline"}
-  ]})
-```
+# Manual hook execution (guaranteed working)
+node src/hooks/enhanced-hooks-cli.js post-edit "[file]" --memory-key "[key]" --structured
 
-**Module Organization:**
-```javascript
-// Preferred module structure
-src/
-  components/         # Reusable components
-  utils/             # Helper functions
-  services/          # API and business logic
-  config/            # Configuration files
-  hooks/             # Custom hooks (if React)
-  types/             # Type definitions (if TypeScript)
+# Validates: formatting, linting, type checking, dependencies, security, tests, TDD compliance
+# Progressive validation: graceful degradation when dependencies missing (beginner-friendly)
 ```
 
-**Testing Patterns:**
-```javascript
-import { jest } from '@jest/globals';
+## 🎯 **Enhanced Post-Edit Hook System**
 
-describe('Module Tests', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
+### **🚨 MANDATORY: Manual Hook Execution After Every File Edit**
 
-  test('handles async operations correctly', async () => {
-    const mockFn = jest.fn().mockResolvedValue({ success: true });
-    const result = await asyncOperation(mockFn);
+**CRITICAL RULE**: After **EVERY** file edit operation, you **MUST** run the enhanced post-edit hook:
 
-    expect(result).toEqual({ success: true });
-    expect(mockFn).toHaveBeenCalledTimes(1);
-  });
+```bash
+# After editing any file, IMMEDIATELY run:
+npx enhanced-hooks post-edit "[FILE_PATH]" --memory-key "swarm/[AGENT]/[STEP]" --minimum-coverage 80 --structured
+
+# Or via slash command:
+/hooks post-edit [FILE_PATH] --memory-key "[CONTEXT]" --structured
+```
+
+**⚠️ NO EXCEPTIONS**: This applies to:
+- All JavaScript/TypeScript files
+- All Rust files
+- All Python files
+- All configuration files
+- ALL file modifications
+
+### **Enhanced Post-Edit Pipeline Features:**
+- **🧪 TDD Testing**: Single-file testing without full system compilation
+- **📊 Real-time Coverage**: Coverage analysis with configurable thresholds (default: 80%)
+- **🌐 Multi-Language Support**:
+  - **JavaScript/TypeScript**: Jest, Mocha, Prettier, ESLint integration
+  - **Rust**: cargo check, cargo test, cargo-tarpaulin, rustfmt
+  - **Python**: pytest, unittest, black, pylint
+  - **Go**: go test, go fmt, go vet
+  - **Java**: JUnit, TestNG, google-java-format
+  - **C/C++**: GTest, Catch2, clang-format
+- **🎨 Formatting**: Prettier, Black, RustFmt, GoFmt with diff preview
+- **🔒 Security Analysis**: XSS, eval(), hardcoded credentials, SQL injection detection
+- **✅ TDD Compliance**: Red-Green-Refactor phase detection and enforcement
+- **🔍 Framework Detection**: Automatic test framework identification
+- **🤖 Agent Feedback**: Structured JSON with actionable recommendations
+- **💾 Memory Coordination**: Cross-agent state sharing and enhanced persistence
+- **🚫 Blocking Mechanisms**: Quality gates for critical validation failures
+
+### **Usage Examples:**
+```bash
+# For JavaScript/TypeScript files
+npx enhanced-hooks post-edit "src/components/Button.tsx" --memory-key "frontend/button" --structured
 
-  test('handles errors gracefully', async () => {
-    const mockFn = jest.fn().mockRejectedValue(new Error('Test error'));
+# For Rust files (full cargo integration)
+npx enhanced-hooks post-edit "src/lib.rs" --memory-key "backend/rust" --minimum-coverage 90 --structured
 
-    await expect(asyncOperation(mockFn)).rejects.toThrow('Test error');
-  });
-});
+# Via slash commands in Claude Code
+/hooks post-edit your-file.js --memory-key "agent-memory-key" --structured
 ```
 
-**Performance Best Practices:**
-- Use code splitting for large applications
-- Implement lazy loading for routes/components
-- Minimize bundle size with tree shaking
-- Use Web Workers for heavy computations
-- Implement proper caching strategies
-
-**Error Handling:**
-```javascript
-// Global error handler
-process.on('unhandledRejection', (reason, promise) => {
-  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-  // Application specific logging logic here
-});
-
-// Async error wrapper
-const asyncHandler = (fn) => (req, res, next) => {
-  Promise.resolve(fn(req, res, next)).catch(next);
-};
-```
-
-**Environment Configuration:**
-```javascript
-// config/index.js
-const config = {
-  development: {
-    api: {
-      baseURL: 'http://localhost:3000',
-      timeout: 5000
-    }
-  },
-  production: {
-    api: {
-      baseURL: process.env.API_BASE_URL,
-      timeout: 10000
-    }
-  }
-};
-
-export default config[process.env.NODE_ENV || 'development'];
-```
-
-## Typescript Configuration
-
-### TypeScript Configuration & Patterns
-
-**Type Safety & Standards:**
-- Use strict TypeScript configuration
-- Prefer interfaces over types for object shapes
-- Use utility types (Partial, Pick, Omit, Record)
-- Implement proper generic constraints
-- Avoid `any` type - use `unknown` when necessary
-
-**TypeScript Config (tsconfig.json):**
+### **Response Structure:**
 ```json
 {
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "strict": true,
-    "noImplicitReturns": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "exactOptionalPropertyTypes": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "node",
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "noEmit": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "build"]
+  "success": true,
+  "file": "src/component.js",
+  "validation": { "passed": true, "issues": [], "coverage": "advanced" },
+  "formatting": { "needed": true, "changes": 12, "formatter": "prettier" },
+  "testing": { "executed": true, "framework": "jest", "results": {...} },
+  "tddCompliance": { "hasTests": true, "coverage": 85, "recommendations": [...] },
+  "recommendations": [
+    { "type": "security", "priority": "high", "message": "...", "action": "..." },
+    { "type": "formatting", "priority": "medium", "action": "prettier file.js" }
+  ],
+  "memory": { "stored": true, "enhancedStore": true }
 }
 ```
 
-**Concurrent Agent Execution:**
-```typescript
-// ✅ CORRECT: TypeScript development with strict typing
-[Single Message]:
-  Task("TypeScript Developer", "Build type-safe modules with generics", "coder")
-  Task("Interface Designer", "Design comprehensive type definitions", "system-architect")
-  Task("Test Engineer", "Write typed tests with Jest and @types", "tester")
-  Task("Build Engineer", "Configure TypeScript compilation pipeline", "backend-dev")
-  Task("Type Reviewer", "Review type safety and consistency", "reviewer")
-
-  // Batch file operations with TypeScript focus
-  Write("src/types/api.ts")
-  Write("src/services/ApiService.ts")
-  Write("src/utils/validators.ts")
-  Write("tests/ApiService.test.ts")
-
-  // TypeScript-specific todos
-  TodoWrite({ todos: [
-    {content: "Define core type interfaces", status: "in_progress", activeForm: "Defining core type interfaces"},
-    {content: "Implement generic utility functions", status: "pending", activeForm: "Implementing generic utility functions"},
-    {content: "Add runtime type validation", status: "pending", activeForm: "Adding runtime type validation"},
-    {content: "Configure path mapping aliases", status: "pending", activeForm: "Configuring path mapping aliases"},
-    {content: "Setup strict linting rules", status: "pending", activeForm: "Setting up strict linting rules"}
-  ]})
+#### Session Management
+```bash
+# Generate summaries and persist state
+npx claude-flow-novice hooks session-end --generate-summary true --persist-state true --export-metrics true
 ```
+### 🎯 Swarm Initialization (MANDATORY for ALL Multi-Agent Tasks)
 
-**Type Definitions Pattern:**
-```typescript
-// types/api.ts
-export interface ApiResponse<T = unknown> {
-  data: T;
-  message: string;
-  status: 'success' | 'error';
-  timestamp: string;
-}
-
-export interface PaginatedResponse<T> extends ApiResponse<T[]> {
-  pagination: {
-    page: number;
-    limit: number;
-    total: number;
-    hasNext: boolean;
-  };
-}
+**CRITICAL**: You MUST initialize swarm BEFORE spawning ANY multiple agents:
 
-// Generic service interface
-export interface CRUDService<T, CreateT = Partial<T>, UpdateT = Partial<T>> {
-  getAll(): Promise<ApiResponse<T[]>>;
-  getById(id: string): Promise<ApiResponse<T>>;
-  create(data: CreateT): Promise<ApiResponse<T>>;
-  update(id: string, data: UpdateT): Promise<ApiResponse<T>>;
-  delete(id: string): Promise<ApiResponse<void>>;
-}
-```
+```javascript
+[Single Message]:
+  // Step 1: ALWAYS initialize swarm first
+  mcp__claude-flow-novice__swarm_init({
+    topology: "mesh",          // mesh (2-7 agents), hierarchical (8+)
+    maxAgents: 3,              // Match your actual agent count
+    strategy: "balanced"       // ensures agents coordinate and stay consistent
+  })
 
-**Advanced TypeScript Patterns:**
-```typescript
-// Utility types for better type inference
-type NonNullable<T> = T extends null | undefined ? never : T;
-
-// Conditional types for API responses
-type ApiResult<T> = T extends string
-  ? ApiResponse<string>
-  : T extends number
-  ? ApiResponse<number>
-  : ApiResponse<T>;
-
-// Template literal types for routes
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
-type ApiRoute<T extends string> = `/api/${T}`;
-
-// Branded types for stronger type safety
-type UserId = string & { readonly __brand: unique symbol };
-type Email = string & { readonly __brand: unique symbol };
-
-// Factory function with proper typing
-function createUserId(value: string): UserId {
-  // Runtime validation here
-  return value as UserId;
-}
+  // Step 2: Spawn working agents via Task tool
+  Task("Agent 1", "Specific instructions...", "type")
+  Task("Agent 2", "Specific instructions...", "type")
+  Task("Agent 3", "Specific instructions...", "type")
 ```
 
-**Testing with TypeScript:**
-```typescript
-import { describe, it, expect, jest, beforeEach } from '@jest/globals';
-
-interface MockApiService {
-  fetchUser: jest.MockedFunction<(id: string) => Promise<User>>;
-}
-
-describe('UserService', () => {
-  let mockApi: MockApiService;
-  let userService: UserService;
-
-  beforeEach(() => {
-    mockApi = {
-      fetchUser: jest.fn()
-    };
-    userService = new UserService(mockApi);
-  });
+**WHY THIS MATTERS:**
+- ✅ **Prevents inconsistency**: Without swarm, 3 agents fixing JWT secrets will use 3 different methods
+- ✅ **Ensures coordination**: Agents share findings and agree on approach
+- ✅ **Memory coordination**: Agents access shared context via SwarmMemory
+- ✅ **Byzantine consensus**: Final validation ensures all agents agree
 
-  it('should fetch user with proper typing', async () => {
-    const mockUser: User = {
-      id: 'user-123',
-      name: 'Test User',
-      email: 'test@example.com'
-    };
+**TOPOLOGY SELECTION:**
+- **2-7 agents**: Use `topology: "mesh"` (peer-to-peer, equal collaboration)
+- **8+ agents**: Use `topology: "hierarchical"` (coordinator-led structure)
 
-    mockApi.fetchUser.mockResolvedValue(mockUser);
+**MCP Integration Tools:**
+- `mcp__claude-flow-novice__swarm_init` - Initialize swarm topology (REQUIRED for ALL multi-agent tasks)
+- `mcp__claude-flow-novice__agent_spawn` - Spawn coordination agents (recommended for consistency)
+- `mcp__claude-flow-novice__task_orchestrate` - Orchestrate high-level workflows
+- **Monitoring**: `swarm_status`, `agent_metrics`, `task_results`
+- **Memory**: `memory_usage`, `memory_search`
 
-    const result = await userService.getUser('user-123');
+---
 
-    expect(result).toEqual(mockUser);
-    expect(mockApi.fetchUser).toHaveBeenCalledWith('user-123');
-  });
-});
-```
+## 📋 AGENT COORDINATION RULES
 
-**Error Handling with Types:**
-```typescript
-// Result pattern for better error handling
-type Result<T, E = Error> =
-  | { success: true; data: T }
-  | { success: false; error: E };
-
-class ApiService {
-  async fetchData<T>(url: string): Promise<Result<T, ApiError>> {
-    try {
-      const response = await fetch(url);
-      if (!response.ok) {
-        return { success: false, error: new ApiError(response.statusText) };
-      }
-      const data = await response.json() as T;
-      return { success: true, data };
-    } catch (error) {
-      return { success: false, error: error as ApiError };
-    }
-  }
-}
+### Universal Agent Spawning Pattern
 
-// Usage with proper type checking
-const result = await apiService.fetchData<User>('/api/users/123');
-if (result.success) {
-  console.log(result.data.name); // TypeScript knows this is User
-} else {
-  console.error(result.error.message); // TypeScript knows this is ApiError
-}
-```
+**EVERY multi-agent task follows this structure:**
 
-**Module Organization:**
-```
-src/
-  types/
-    api.ts          # API response types
-    domain.ts       # Business domain types
-    utils.ts        # Utility types
-  services/
-    BaseService.ts  # Generic base service
-    UserService.ts  # Concrete implementations
-  utils/
-    validators.ts   # Runtime type validation
-    typeGuards.ts   # Type guard functions
-  hooks/           # Custom hooks (if React)
-    useApi.ts      # Generic API hook
-```
-
-## React Framework Configuration
-
-### React Development Patterns
-
-**Component Architecture:**
-- Use functional components with hooks
-- Implement proper component composition
-- Follow single responsibility principle
-- Use TypeScript for better type safety
-- Implement proper error boundaries
-
-**Concurrent Agent Execution:**
-```jsx
-// ✅ CORRECT: React development with specialized agents
+```javascript
 [Single Message]:
-  Task("React Developer", "Build reusable components with hooks and context", "coder")
-  Task("State Manager", "Implement Redux Toolkit/Zustand state management", "system-architect")
-  Task("UI Designer", "Create responsive layouts with CSS-in-JS/Tailwind", "coder")
-  Task("Test Engineer", "Write React Testing Library tests with coverage", "tester")
-  Task("Performance Engineer", "Optimize renders and bundle size", "perf-analyzer")
-
-  // Batch React file operations
-  Write("src/components/App.jsx")
-  Write("src/hooks/useApi.js")
-  Write("src/context/AppContext.jsx")
-  Write("src/styles/globals.css")
-  Write("tests/components/App.test.jsx")
-
-  // React-specific todos
-  TodoWrite({ todos: [
-    {content: "Setup component library structure", status: "in_progress", activeForm: "Setting up component library structure"},
-    {content: "Implement custom hooks for data fetching", status: "pending", activeForm: "Implementing custom hooks for data fetching"},
-    {content: "Add error boundaries and loading states", status: "pending", activeForm: "Adding error boundaries and loading states"},
-    {content: "Configure routing with React Router", status: "pending", activeForm: "Configuring routing with React Router"},
-    {content: "Optimize performance with memoization", status: "pending", activeForm: "Optimizing performance with memoization"}
-  ]})
-```
-
-**Project Structure:**
-```
-src/
-  components/
-    common/           # Reusable UI components
-      Button.jsx
-      Modal.jsx
-      Input.jsx
-    layout/           # Layout components
-      Header.jsx
-      Sidebar.jsx
-      Footer.jsx
-    pages/            # Page-level components
-      HomePage.jsx
-      UserProfile.jsx
-  hooks/              # Custom hooks
-    useApi.js
-    useLocalStorage.js
-    useAuth.js
-  context/            # React context providers
-    AuthContext.jsx
-    ThemeContext.jsx
-  services/           # API services
-    api.js
-    auth.js
-  utils/              # Helper functions
-    validators.js
-    formatters.js
-  styles/             # Global styles
-    globals.css
-    variables.css
-```
-
-**Component Patterns:**
-```jsx
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
-import PropTypes from 'prop-types';
-
-// Functional component with hooks
-const UserProfile = ({ userId, onUpdate }) => {
-  const [user, setUser] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  // Memoized expensive calculations
-  const userStats = useMemo(() => {
-    if (!user) return null;
-    return {
-      totalPosts: user.posts?.length || 0,
-      joinedDate: new Date(user.createdAt).toLocaleDateString()
-    };
-  }, [user]);
-
-  // Memoized callbacks to prevent unnecessary re-renders
-  const handleUpdateUser = useCallback(async (updates) => {
-    try {
-      const updatedUser = await updateUser(userId, updates);
-      setUser(updatedUser);
-      onUpdate?.(updatedUser);
-    } catch (err) {
-      setError(err.message);
-    }
-  }, [userId, onUpdate]);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    const fetchUser = async () => {
-      try {
-        setLoading(true);
-        const userData = await getUserById(userId);
-        if (!cancelled) {
-          setUser(userData);
-        }
-      } catch (err) {
-        if (!cancelled) {
-          setError(err.message);
-        }
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    };
-
-    fetchUser();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [userId]);
-
-  if (loading) return <LoadingSpinner />;
-  if (error) return <ErrorMessage message={error} />;
-  if (!user) return <NotFound />;
-
-  return (
-    <div className="user-profile">
-      <ProfileHeader user={user} stats={userStats} />
-      <ProfileContent user={user} onUpdate={handleUpdateUser} />
-    </div>
-  );
-};
-
-UserProfile.propTypes = {
-  userId: PropTypes.string.isRequired,
-  onUpdate: PropTypes.func
-};
-
-export default React.memo(UserProfile);
-```
+  // Step 1: ALWAYS initialize swarm first
+  mcp__claude-flow-novice__swarm_init({
+    topology: "mesh",          // or "hierarchical" for 8+ agents
+    maxAgents: X,              // match your actual agent count
+    strategy: "balanced"       // or "adaptive" for complex tasks
+  })
 
-**Custom Hooks Pattern:**
-```jsx
-import { useState, useEffect, useCallback } from 'react';
-
-// Generic API hook
-export const useApi = (url, options = {}) => {
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  const fetchData = useCallback(async () => {
-    try {
-      setLoading(true);
-      setError(null);
-      const response = await fetch(url, options);
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
-      const result = await response.json();
-      setData(result);
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setLoading(false);
-    }
-  }, [url, options]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  const refetch = useCallback(() => {
-    fetchData();
-  }, [fetchData]);
-
-  return { data, loading, error, refetch };
-};
-
-// Local storage hook
-export const useLocalStorage = (key, initialValue) => {
-  const [storedValue, setStoredValue] = useState(() => {
-    try {
-      const item = window.localStorage.getItem(key);
-      return item ? JSON.parse(item) : initialValue;
-    } catch (error) {
-      console.error(`Error reading localStorage key "${key}":`, error);
-      return initialValue;
-    }
-  });
-
-  const setValue = useCallback((value) => {
-    try {
-      const valueToStore = value instanceof Function ? value(storedValue) : value;
-      setStoredValue(valueToStore);
-      window.localStorage.setItem(key, JSON.stringify(valueToStore));
-    } catch (error) {
-      console.error(`Error setting localStorage key "${key}":`, error);
-    }
-  }, [key, storedValue]);
-
-  return [storedValue, setValue];
-};
+  // Step 2: Spawn ALL agents concurrently
+  Task("Agent Name", "Specific task instructions", "agent-type")
+  Task("Agent Name", "Specific task instructions", "agent-type")
+  Task("Agent Name", "Specific task instructions", "agent-type")
+  // ... continue for all agents
 ```
 
-**Context Pattern:**
-```jsx
-import React, { createContext, useContext, useReducer, useCallback } from 'react';
-
-// State and actions
-const initialState = {
-  user: null,
-  isAuthenticated: false,
-  loading: false,
-  error: null
-};
-
-const authReducer = (state, action) => {
-  switch (action.type) {
-    case 'LOGIN_START':
-      return { ...state, loading: true, error: null };
-    case 'LOGIN_SUCCESS':
-      return {
-        ...state,
-        user: action.payload,
-        isAuthenticated: true,
-        loading: false,
-        error: null
-      };
-    case 'LOGIN_FAILURE':
-      return {
-        ...state,
-        user: null,
-        isAuthenticated: false,
-        loading: false,
-        error: action.payload
-      };
-    case 'LOGOUT':
-      return initialState;
-    default:
-      return state;
-  }
-};
-
-// Context creation
-const AuthContext = createContext();
-
-// Provider component
-export const AuthProvider = ({ children }) => {
-  const [state, dispatch] = useReducer(authReducer, initialState);
-
-  const login = useCallback(async (credentials) => {
-    dispatch({ type: 'LOGIN_START' });
-    try {
-      const user = await authService.login(credentials);
-      dispatch({ type: 'LOGIN_SUCCESS', payload: user });
-      return user;
-    } catch (error) {
-      dispatch({ type: 'LOGIN_FAILURE', payload: error.message });
-      throw error;
-    }
-  }, []);
-
-  const logout = useCallback(() => {
-    authService.logout();
-    dispatch({ type: 'LOGOUT' });
-  }, []);
-
-  const value = {
-    ...state,
-    login,
-    logout
-  };
-
-  return (
-    <AuthContext.Provider value={value}>
-      {children}
-    </AuthContext.Provider>
-  );
-};
-
-// Custom hook for using auth context
-export const useAuth = () => {
-  const context = useContext(AuthContext);
-  if (!context) {
-    throw new Error('useAuth must be used within an AuthProvider');
-  }
-  return context;
-};
-```
-
-**Testing with React Testing Library:**
-```jsx
-import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { jest } from '@jest/globals';
-import UserProfile from '../UserProfile';
-import * as api from '../../services/api';
-
-// Mock the API module
-jest.mock('../../services/api');
-
-describe('UserProfile', () => {
-  const mockUser = {
-    id: '123',
-    name: 'John Doe',
-    email: 'john@example.com',
-    posts: [{ id: 1, title: 'Test Post' }]
-  };
+### Coordination Checklist
 
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
+**Before spawning agents, ensure:**
+- ✅ Task analyzed and complexity assessed (Simple/Medium/Complex/Enterprise)
+- ✅ Agent count determined from requirements table
+- ✅ Agent types selected for specific needs (not generic roles)
+- ✅ Topology chosen: mesh (2-7) or hierarchical (8+)
+- ✅ All agents will spawn in SINGLE message
+- ✅ Each agent has specific, non-overlapping instructions
 
-  test('renders user profile after loading', async () => {
-    api.getUserById.mockResolvedValue(mockUser);
+**During execution:**
+- ✅ Agents coordinate through SwarmMemory
+- ✅ Self-validation runs before consensus
+- ✅ Each agent runs Post-edit hooks execute after file changes
 
-    render(<UserProfile userId="123" />);
+**After completion:**
+- ✅ Consensus validation achieved (≥90% agreement)
+- ✅ Results stored in memory
+- ✅ Next steps provided with claude code continuing to the next documented phase or next steps provided to user if no todos left
 
-    // Check loading state
-    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
+### Agent Selection Guide
 
-    // Wait for user data to load
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
+**Core Development**: coder, tester, reviewer
+**Backend**: backend-dev, api-docs, system-architect
+**Frontend**: coder (specialized), mobile-dev
+**Quality**: tester, reviewer, security-specialist, perf-analyzer
+**Planning**: researcher, planner, architect
+**Operations**: devops-engineer, cicd-engineer
+**Documentation**: api-docs, researcher
 
-    expect(screen.getByText('john@example.com')).toBeInTheDocument();
-    expect(screen.getByText('1 Posts')).toBeInTheDocument();
-  });
+**Select agents based on actual task needs, not predefined patterns.**
 
-  test('handles update user interaction', async () => {
-    const user = userEvent.setup();
-    const onUpdate = jest.fn();
+---
 
-    api.getUserById.mockResolvedValue(mockUser);
-    api.updateUser.mockResolvedValue({ ...mockUser, name: 'Jane Doe' });
+### ⚠️ Real-World Example: Why Swarm Coordination Matters
 
-    render(<UserProfile userId="123" onUpdate={onUpdate} />);
-
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
-
-    const editButton = screen.getByRole('button', { name: /edit/i });
-    await user.click(editButton);
-
-    const nameInput = screen.getByDisplayValue('John Doe');
-    await user.clear(nameInput);
-    await user.type(nameInput, 'Jane Doe');
-
-    const saveButton = screen.getByRole('button', { name: /save/i });
-    await user.click(saveButton);
-
-    await waitFor(() => {
-      expect(onUpdate).toHaveBeenCalledWith({ ...mockUser, name: 'Jane Doe' });
-    });
-  });
-
-  test('displays error message on API failure', async () => {
-    api.getUserById.mockRejectedValue(new Error('Network error'));
-
-    render(<UserProfile userId="123" />);
-
-    await waitFor(() => {
-      expect(screen.getByText(/network error/i)).toBeInTheDocument();
-    });
-  });
-});
-```
-
-**Performance Optimization:**
-```jsx
-import React, { memo, lazy, Suspense } from 'react';
-
-// Lazy loading for code splitting
-const LazyUserProfile = lazy(() => import('./UserProfile'));
-const LazyUserSettings = lazy(() => import('./UserSettings'));
-
-// Memoized component to prevent unnecessary re-renders
-const UserCard = memo(({ user, onUpdate }) => {
-  return (
-    <div className="user-card">
-      <h3>{user.name}</h3>
-      <p>{user.email}</p>
-      <button onClick={() => onUpdate(user.id)}>
-        Update
-      </button>
-    </div>
-  );
-});
-
-// Main app with lazy loading
-const App = () => {
-  return (
-    <div className="app">
-      <Suspense fallback={<div>Loading...</div>}>
-        <Routes>
-          <Route path="/profile" element={<LazyUserProfile />} />
-          <Route path="/settings" element={<LazyUserSettings />} />
-        </Routes>
-      </Suspense>
-    </div>
-  );
-};
-```
-
-**State Management with Zustand:**
-```jsx
-import { create } from 'zustand';
-import { devtools, persist } from 'zustand/middleware';
-
-const useUserStore = create(
-  devtools(
-    persist(
-      (set, get) => ({
-        users: [],
-        currentUser: null,
-        loading: false,
-
-        fetchUsers: async () => {
-          set({ loading: true });
-          try {
-            const users = await api.getUsers();
-            set({ users, loading: false });
-          } catch (error) {
-            set({ loading: false });
-            throw error;
-          }
-        },
-
-        setCurrentUser: (user) => set({ currentUser: user }),
-
-        updateUser: async (userId, updates) => {
-          const updatedUser = await api.updateUser(userId, updates);
-          set((state) => ({
-            users: state.users.map((user) =>
-              user.id === userId ? updatedUser : user
-            ),
-            currentUser: state.currentUser?.id === userId ? updatedUser : state.currentUser
-          }));
-          return updatedUser;
-        }
-      }),
-      { name: 'user-store' }
-    )
-  )
-);
-
-// Usage in component
-const UserList = () => {
-  const { users, loading, fetchUsers } = useUserStore();
-
-  useEffect(() => {
-    fetchUsers();
-  }, [fetchUsers]);
-
-  if (loading) return <LoadingSpinner />;
-
-  return (
-    <div>
-      {users.map((user) => (
-        <UserCard key={user.id} user={user} />
-      ))}
-    </div>
-  );
-};
-```
-
-## 🚀 Concurrent Execution Patterns
-
-### JavaScript/TypeScript Patterns
-
-```javascript
-// ✅ CORRECT: Batch all operations in single message
-[Single Message]:
-  Task("Frontend Developer", "Build React components with hooks", "coder")
-  Task("Backend Developer", "Create Express API endpoints", "backend-dev")
-  Task("Test Engineer", "Write Jest tests with >80% coverage", "tester")
-  
-  // Batch file operations
-  Write("src/components/App.jsx")
-  Write("src/api/server.js")
-  Write("tests/App.test.js")
-```
-
-### Python Patterns
-
-```python
-# ✅ CORRECT: Parallel agent execution
-[Single Message]:
-  Task("Django Developer", "Build models and views with DRF", "backend-dev")
-  Task("Frontend Developer", "Create React frontend with API integration", "coder")
-  Task("Test Engineer", "Write pytest tests with fixtures", "tester")
-  
-  # Batch Python operations
-  Write("apps/models.py")
-  Write("apps/views.py")
-  Write("tests/test_models.py")
-```
-
-### React Development Patterns
-
-```javascript
-// React-specific concurrent patterns
-[Single Message]:
-  Task("Component Developer", "Build reusable components with TypeScript", "coder")
-  Task("State Manager", "Implement Redux/Context state management", "coder")
-  Task("Test Engineer", "Write React Testing Library tests", "tester")
-  Task("Style Developer", "Create responsive CSS/Styled Components", "coder")
-```
-
-### API Development Patterns
-
-```bash
-# API-focused concurrent execution
-[Single Message]:
-  Task("API Developer", "Build RESTful endpoints with validation", "backend-dev")
-  Task("Database Designer", "Design schema and migrations", "code-analyzer")
-  Task("Security Engineer", "Implement authentication and authorization", "reviewer")
-  Task("API Tester", "Create integration and unit tests", "tester")
-  Task("Documentation Writer", "Generate OpenAPI/Swagger docs", "researcher")
-```
-
-
-
-## 📋 Best Practices
-
-### General Development
-- **Modular Design**: Keep files under 500 lines
-- **Environment Safety**: Never hardcode secrets
-- **Test-First**: Write tests before implementation
-- **Clean Architecture**: Separate concerns
-- **Documentation**: Keep updated
-
-### JavaScript/TypeScript
-- **ES6+ Features**: Use modern JavaScript syntax
-- **Type Safety**: Prefer TypeScript for larger projects
-- **Async/Await**: Use async/await over Promise chains
-- **Error Handling**: Implement proper error boundaries
-- **Code Splitting**: Lazy load components and routes
-
-### Python
-- **PEP 8**: Follow Python style guidelines
-- **Type Hints**: Use type annotations for clarity
-- **Virtual Environments**: Always use venv or conda
-- **Docstrings**: Document all functions and classes
-- **Error Handling**: Use specific exception types
-
-
-
-## 🧪 Testing Patterns
-
-### React Testing
-
-```javascript
-import { render, screen, fireEvent } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-
-// Component testing pattern
-describe('Component', () => {
-  test('renders and handles interaction', async () => {
-    const user = userEvent.setup();
-    render(<Component />);
-    
-    const button = screen.getByRole('button');
-    await user.click(button);
-    
-    expect(screen.getByText(/result/i)).toBeInTheDocument();
-  });
-});
-```
-
-### Python Testing
-
-```python
-import pytest
-from unittest.mock import patch, MagicMock
-
-class TestAPI:
-    @pytest.fixture
-    def client(self):
-        return TestClient()
-
-    def test_endpoint(self, client):
-        response = client.get("/api/endpoint")
-        assert response.status_code == 200
-        assert response.json()["status"] == "success"
-```
-
-
-
-## Custom Configuration
-
-<!-- Preserved from existing CLAUDE.md -->
-  hooks/             # Custom hooks (if React)
-  types/             # Type definitions (if TypeScript)
-```
-
-**Testing Patterns:**
+**WITHOUT swarm_init (problematic):**
 ```javascript
-import { jest } from '@jest/globals';
-
-describe('Module Tests', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  test('handles async operations correctly', async () => {
-    const mockFn = jest.fn().mockResolvedValue({ success: true });
-    const result = await asyncOperation(mockFn);
-
-    expect(result).toEqual({ success: true });
-    expect(mockFn).toHaveBeenCalledTimes(1);
-  });
-
-  test('handles errors gracefully', async () => {
-    const mockFn = jest.fn().mockRejectedValue(new Error('Test error'));
-
-    await expect(asyncOperation(mockFn)).rejects.toThrow('Test error');
-  });
-});
-```
-
-**Performance Best Practices:**
-- Use code splitting for large applications
-- Implement lazy loading for routes/components
-- Minimize bundle size with tree shaking
-- Use Web Workers for heavy computations
-- Implement proper caching strategies
+// ❌ BAD: Agents work independently with no coordination
+[Single Message]:
+  Task("Agent 1", "Fix JWT secret issue", "coder")
+  Task("Agent 2", "Fix JWT secret issue", "coder")
+  Task("Agent 3", "Fix JWT secret issue", "coder")
 
-**Error Handling:**
-```javascript
-// Global error handler
-process.on('unhandledRejection', (reason, promise) => {
-  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-  // Application specific logging logic here
-});
-
-// Async error wrapper
-const asyncHandler = (fn) => (req, res, next) => {
-  Promise.resolve(fn(req, res, next)).catch(next);
-};
+// Result: 3 different solutions - environment variable, config file, hardcoded
+// Problem: Inconsistent approach, wasted effort, integration conflicts
 ```
 
-**Environment Configuration:**
+**WITH swarm_init (correct):**
 ```javascript
-// config/index.js
-const config = {
-  development: {
-    api: {
-      baseURL: 'http://localhost:3000',
-      timeout: 5000
-    }
-  },
-  production: {
-    api: {
-      baseURL: process.env.API_BASE_URL,
-      timeout: 10000
-    }
-  }
-};
-
-export default config[process.env.NODE_ENV || 'development'];
-```
-
-
-  hooks/           # Custom hooks (if React)
-    useApi.ts      # Generic API hook
-```
-
-
-  hooks/              # Custom hooks
-    useApi.js
-    useLocalStorage.js
-    useAuth.js
-  context/            # React context providers
-    AuthContext.jsx
-    ThemeContext.jsx
-  services/           # API services
-    api.js
-    auth.js
-  utils/              # Helper functions
-    validators.js
-    formatters.js
-  styles/             # Global styles
-    globals.css
-    variables.css
-```
-
-**Component Patterns:**
-```jsx
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
-import PropTypes from 'prop-types';
-
-// Functional component with hooks
-const UserProfile = ({ userId, onUpdate }) => {
-  const [user, setUser] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  // Memoized expensive calculations
-  const userStats = useMemo(() => {
-    if (!user) return null;
-    return {
-      totalPosts: user.posts?.length || 0,
-      joinedDate: new Date(user.createdAt).toLocaleDateString()
-    };
-  }, [user]);
-
-  // Memoized callbacks to prevent unnecessary re-renders
-  const handleUpdateUser = useCallback(async (updates) => {
-    try {
-      const updatedUser = await updateUser(userId, updates);
-      setUser(updatedUser);
-      onUpdate?.(updatedUser);
-    } catch (err) {
-      setError(err.message);
-    }
-  }, [userId, onUpdate]);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    const fetchUser = async () => {
-      try {
-        setLoading(true);
-        const userData = await getUserById(userId);
-        if (!cancelled) {
-          setUser(userData);
-        }
-      } catch (err) {
-        if (!cancelled) {
-          setError(err.message);
-        }
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    };
-
-    fetchUser();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [userId]);
-
-  if (loading) return <LoadingSpinner />;
-  if (error) return <ErrorMessage message={error} />;
-  if (!user) return <NotFound />;
-
-  return (
-    <div className="user-profile">
-      <ProfileHeader user={user} stats={userStats} />
-      <ProfileContent user={user} onUpdate={handleUpdateUser} />
-    </div>
-  );
-};
-
-UserProfile.propTypes = {
-  userId: PropTypes.string.isRequired,
-  onUpdate: PropTypes.func
-};
-
-export default React.memo(UserProfile);
-```
+// ✅ GOOD: Agents coordinate through swarm
+[Single Message]:
+  mcp__claude-flow-novice__swarm_init({
+    topology: "mesh",
+    maxAgents: 3,
+    strategy: "balanced"
+  })
 
-**Custom Hooks Pattern:**
-```jsx
-import { useState, useEffect, useCallback } from 'react';
-
-// Generic API hook
-export const useApi = (url, options = {}) => {
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  const fetchData = useCallback(async () => {
-    try {
-      setLoading(true);
-      setError(null);
-      const response = await fetch(url, options);
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
-      const result = await response.json();
-      setData(result);
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setLoading(false);
-    }
-  }, [url, options]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  const refetch = useCallback(() => {
-    fetchData();
-  }, [fetchData]);
-
-  return { data, loading, error, refetch };
-};
-
-// Local storage hook
-export const useLocalStorage = (key, initialValue) => {
-  const [storedValue, setStoredValue] = useState(() => {
-    try {
-      const item = window.localStorage.getItem(key);
-      return item ? JSON.parse(item) : initialValue;
-    } catch (error) {
-      console.error(`Error reading localStorage key "${key}":`, error);
-      return initialValue;
-    }
-  });
-
-  const setValue = useCallback((value) => {
-    try {
-      const valueToStore = value instanceof Function ? value(storedValue) : value;
-      setStoredValue(valueToStore);
-      window.localStorage.setItem(key, JSON.stringify(valueToStore));
-    } catch (error) {
-      console.error(`Error setting localStorage key "${key}":`, error);
-    }
-  }, [key, storedValue]);
-
-  return [storedValue, setValue];
-};
-```
+  Task("Agent 1", "Fix JWT secret issue", "coder")
+  Task("Agent 2", "Fix JWT secret issue", "coder")
+  Task("Agent 3", "Fix JWT secret issue", "coder")
 
-**Context Pattern:**
-```jsx
-import React, { createContext, useContext, useReducer, useCallback } from 'react';
-
-// State and actions
-const initialState = {
-  user: null,
-  isAuthenticated: false,
-  loading: false,
-  error: null
-};
-
-const authReducer = (state, action) => {
-  switch (action.type) {
-    case 'LOGIN_START':
-      return { ...state, loading: true, error: null };
-    case 'LOGIN_SUCCESS':
-      return {
-        ...state,
-        user: action.payload,
-        isAuthenticated: true,
-        loading: false,
-        error: null
-      };
-    case 'LOGIN_FAILURE':
-      return {
-        ...state,
-        user: null,
-        isAuthenticated: false,
-        loading: false,
-        error: action.payload
-      };
-    case 'LOGOUT':
-      return initialState;
-    default:
-      return state;
-  }
-};
-
-// Context creation
-const AuthContext = createContext();
-
-// Provider component
-export const AuthProvider = ({ children }) => {
-  const [state, dispatch] = useReducer(authReducer, initialState);
-
-  const login = useCallback(async (credentials) => {
-    dispatch({ type: 'LOGIN_START' });
-    try {
-      const user = await authService.login(credentials);
-      dispatch({ type: 'LOGIN_SUCCESS', payload: user });
-      return user;
-    } catch (error) {
-      dispatch({ type: 'LOGIN_FAILURE', payload: error.message });
-      throw error;
-    }
-  }, []);
-
-  const logout = useCallback(() => {
-    authService.logout();
-    dispatch({ type: 'LOGOUT' });
-  }, []);
-
-  const value = {
-    ...state,
-    login,
-    logout
-  };
-
-  return (
-    <AuthContext.Provider value={value}>
-      {children}
-    </AuthContext.Provider>
-  );
-};
-
-// Custom hook for using auth context
-export const useAuth = () => {
-  const context = useContext(AuthContext);
-  if (!context) {
-    throw new Error('useAuth must be used within an AuthProvider');
-  }
-  return context;
-};
+// Result: All 3 agents agree on environment variable approach
+// Benefit: Consistent solution, shared context, coordinated implementation
 ```
 
-**Testing with React Testing Library:**
-```jsx
-import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { jest } from '@jest/globals';
-import UserProfile from '../UserProfile';
-import * as api from '../../services/api';
-
-// Mock the API module
-jest.mock('../../services/api');
-
-describe('UserProfile', () => {
-  const mockUser = {
-    id: '123',
-    name: 'John Doe',
-    email: 'john@example.com',
-    posts: [{ id: 1, title: 'Test Post' }]
-  };
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  test('renders user profile after loading', async () => {
-    api.getUserById.mockResolvedValue(mockUser);
+## File Organization
+- **Never save working files to root**
 
-    render(<UserProfile userId="123" />);
+# Add MCP server
+claude mcp add claude-flow-novice npx claude-flow-novice mcp start
 
-    // Check loading state
-    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
 
-    // Wait for user data to load
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
+## Essential Commands
+- `npx claude-flow-novice status` - System health
+- `npx claude-flow-novice --help` - Available commands
+- `/fullstack "goal"` - Launch full-stack development team with consensus validation
+- `/swarm`, `/sparc`, `/hooks` - Other slash commands (auto-discovered)
 
-    expect(screen.getByText('john@example.com')).toBeInTheDocument();
-    expect(screen.getByText('1 Posts')).toBeInTheDocument();
-  });
+## 🔄 MANDATORY DEVELOPMENT FLOW LOOP
 
-  test('handles update user interaction', async () => {
-    const user = userEvent.setup();
-    const onUpdate = jest.fn();
+**YOU MUST FOLLOW THIS LOOP FOR ALL NON-TRIVIAL WORK:**
 
-    api.getUserById.mockResolvedValue(mockUser);
-    api.updateUser.mockResolvedValue({ ...mockUser, name: 'Jane Doe' });
-
-    render(<UserProfile userId="123" onUpdate={onUpdate} />);
-
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
-
-    const editButton = screen.getByRole('button', { name: /edit/i });
-    await user.click(editButton);
-
-    const nameInput = screen.getByDisplayValue('John Doe');
-    await user.clear(nameInput);
-    await user.type(nameInput, 'Jane Doe');
-
-    const saveButton = screen.getByRole('button', { name: /save/i });
-    await user.click(saveButton);
-
-    await waitFor(() => {
-      expect(onUpdate).toHaveBeenCalledWith({ ...mockUser, name: 'Jane Doe' });
-    });
-  });
-
-  test('displays error message on API failure', async () => {
-    api.getUserById.mockRejectedValue(new Error('Network error'));
-
-    render(<UserProfile userId="123" />);
-
-    await waitFor(() => {
-      expect(screen.getByText(/network error/i)).toBeInTheDocument();
-    });
-  });
-});
-```
+### Step 1: Initialize Swarm (ALWAYS for multi-agent tasks)
+```javascript
+[Single Message]:
+  // ALWAYS initialize swarm when spawning multiple agents
+  mcp__claude-flow-novice__swarm_init({
+    topology: "mesh",          // mesh for 2-7, hierarchical for 8+
+    maxAgents: 3,              // match your actual agent count
+    strategy: "balanced"       // ensures coordination and consistency
+  })
 
-**Performance Optimization:**
-```jsx
-import React, { memo, lazy, Suspense } from 'react';
-
-// Lazy loading for code splitting
-const LazyUserProfile = lazy(() => import('./UserProfile'));
-const LazyUserSettings = lazy(() => import('./UserSettings'));
-
-// Memoized component to prevent unnecessary re-renders
-const UserCard = memo(({ user, onUpdate }) => {
-  return (
-    <div className="user-card">
-      <h3>{user.name}</h3>
-      <p>{user.email}</p>
-      <button onClick={() => onUpdate(user.id)}>
-        Update
-      </button>
-    </div>
-  );
-});
-
-// Main app with lazy loading
-const App = () => {
-  return (
-    <div className="app">
-      <Suspense fallback={<div>Loading...</div>}>
-        <Routes>
-          <Route path="/profile" element={<LazyUserProfile />} />
-          <Route path="/settings" element={<LazyUserSettings />} />
-        </Routes>
-      </Suspense>
-    </div>
-  );
-};
+  // Then spawn all agents - they will coordinate via swarm
+  Task("Agent 1", "Specific instructions", "type")
+  Task("Agent 2", "Specific instructions", "type")
+  Task("Agent 3", "Specific instructions", "type")
 ```
 
-**State Management with Zustand:**
-```jsx
-import { create } from 'zustand';
-import { devtools, persist } from 'zustand/middleware';
-
-const useUserStore = create(
-  devtools(
-    persist(
-      (set, get) => ({
-        users: [],
-        currentUser: null,
-        loading: false,
-
-        fetchUsers: async () => {
-          set({ loading: true });
-          try {
-            const users = await api.getUsers();
-            set({ users, loading: false });
-          } catch (error) {
-            set({ loading: false });
-            throw error;
-          }
-        },
-
-        setCurrentUser: (user) => set({ currentUser: user }),
-
-        updateUser: async (userId, updates) => {
-          const updatedUser = await api.updateUser(userId, updates);
-          set((state) => ({
-            users: state.users.map((user) =>
-              user.id === userId ? updatedUser : user
-            ),
-            currentUser: state.currentUser?.id === userId ? updatedUser : state.currentUser
-          }));
-          return updatedUser;
-        }
-      }),
-      { name: 'user-store' }
-    )
-  )
-);
-
-// Usage in component
-const UserList = () => {
-  const { users, loading, fetchUsers } = useUserStore();
-
-  useEffect(() => {
-    fetchUsers();
-  }, [fetchUsers]);
-
-  if (loading) return <LoadingSpinner />;
-
-  return (
-    <div>
-      {users.map((user) => (
-        <UserCard key={user.id} user={user} />
-      ))}
-    </div>
-  );
-};
-```
-
-
-  hooks/              # Custom hooks
-    useApi.js
-    useLocalStorage.js
-    useAuth.js
-  context/            # React context providers
-    AuthContext.jsx
-    ThemeContext.jsx
-  services/           # API services
-    api.js
-    auth.js
-  utils/              # Helper functions
-    validators.js
-    formatters.js
-  styles/             # Global styles
-    globals.css
-    variables.css
-```
+**CRITICAL**: Without swarm_init, agents work independently and produce inconsistent results!
 
-**Component Patterns:**
-```jsx
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
-import PropTypes from 'prop-types';
-
-// Functional component with hooks
-const UserProfile = ({ userId, onUpdate }) => {
-  const [user, setUser] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  // Memoized expensive calculations
-  const userStats = useMemo(() => {
-    if (!user) return null;
-    return {
-      totalPosts: user.posts?.length || 0,
-      joinedDate: new Date(user.createdAt).toLocaleDateString()
-    };
-  }, [user]);
-
-  // Memoized callbacks to prevent unnecessary re-renders
-  const handleUpdateUser = useCallback(async (updates) => {
-    try {
-      const updatedUser = await updateUser(userId, updates);
-      setUser(updatedUser);
-      onUpdate?.(updatedUser);
-    } catch (err) {
-      setError(err.message);
-    }
-  }, [userId, onUpdate]);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    const fetchUser = async () => {
-      try {
-        setLoading(true);
-        const userData = await getUserById(userId);
-        if (!cancelled) {
-          setUser(userData);
-        }
-      } catch (err) {
-        if (!cancelled) {
-          setError(err.message);
-        }
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    };
-
-    fetchUser();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [userId]);
-
-  if (loading) return <LoadingSpinner />;
-  if (error) return <ErrorMessage message={error} />;
-  if (!user) return <NotFound />;
-
-  return (
-    <div className="user-profile">
-      <ProfileHeader user={user} stats={userStats} />
-      <ProfileContent user={user} onUpdate={handleUpdateUser} />
-    </div>
-  );
-};
-
-UserProfile.propTypes = {
-  userId: PropTypes.string.isRequired,
-  onUpdate: PropTypes.func
-};
-
-export default React.memo(UserProfile);
-```
+### Step 2: Execute - Primary Swarm (3-20 agents)
+- **Primary swarm** (3-8 agents minimum) produces deliverables with confidence scores
+- **Self-validation**: Each agent validates own work (confidence threshold: 0.75)
+- **Cross-agent coordination**: Agents share findings via SwarmMemory
 
-**Custom Hooks Pattern:**
-```jsx
-import { useState, useEffect, useCallback } from 'react';
-
-// Generic API hook
-export const useApi = (url, options = {}) => {
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  const fetchData = useCallback(async () => {
-    try {
-      setLoading(true);
-      setError(null);
-      const response = await fetch(url, options);
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
-      const result = await response.json();
-      setData(result);
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setLoading(false);
-    }
-  }, [url, options]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  const refetch = useCallback(() => {
-    fetchData();
-  }, [fetchData]);
-
-  return { data, loading, error, refetch };
-};
-
-// Local storage hook
-export const useLocalStorage = (key, initialValue) => {
-  const [storedValue, setStoredValue] = useState(() => {
-    try {
-      const item = window.localStorage.getItem(key);
-      return item ? JSON.parse(item) : initialValue;
-    } catch (error) {
-      console.error(`Error reading localStorage key "${key}":`, error);
-      return initialValue;
-    }
-  });
-
-  const setValue = useCallback((value) => {
-    try {
-      const valueToStore = value instanceof Function ? value(storedValue) : value;
-      setStoredValue(valueToStore);
-      window.localStorage.setItem(key, JSON.stringify(valueToStore));
-    } catch (error) {
-      console.error(`Error setting localStorage key "${key}":`, error);
-    }
-  }, [key, storedValue]);
-
-  return [storedValue, setValue];
-};
-```
+### Step 3: Self-Assessment Gate
+- **If confidence scores ≥75%** → Proceed to Step 4 (Consensus Verification)
+- **If confidence scores <75%** → Relaunch agents for Step 2 with feedback
+- **Maximum iterations**: 3 attempts before escalation
 
-**Context Pattern:**
-```jsx
-import React, { createContext, useContext, useReducer, useCallback } from 'react';
-
-// State and actions
-const initialState = {
-  user: null,
-  isAuthenticated: false,
-  loading: false,
-  error: null
-};
-
-const authReducer = (state, action) => {
-  switch (action.type) {
-    case 'LOGIN_START':
-      return { ...state, loading: true, error: null };
-    case 'LOGIN_SUCCESS':
-      return {
-        ...state,
-        user: action.payload,
-        isAuthenticated: true,
-        loading: false,
-        error: null
-      };
-    case 'LOGIN_FAILURE':
-      return {
-        ...state,
-        user: null,
-        isAuthenticated: false,
-        loading: false,
-        error: action.payload
-      };
-    case 'LOGOUT':
-      return initialState;
-    default:
-      return state;
-  }
-};
-
-// Context creation
-const AuthContext = createContext();
-
-// Provider component
-export const AuthProvider = ({ children }) => {
-  const [state, dispatch] = useReducer(authReducer, initialState);
-
-  const login = useCallback(async (credentials) => {
-    dispatch({ type: 'LOGIN_START' });
-    try {
-      const user = await authService.login(credentials);
-      dispatch({ type: 'LOGIN_SUCCESS', payload: user });
-      return user;
-    } catch (error) {
-      dispatch({ type: 'LOGIN_FAILURE', payload: error.message });
-      throw error;
-    }
-  }, []);
-
-  const logout = useCallback(() => {
-    authService.logout();
-    dispatch({ type: 'LOGOUT' });
-  }, []);
-
-  const value = {
-    ...state,
-    login,
-    logout
-  };
-
-  return (
-    <AuthContext.Provider value={value}>
-      {children}
-    </AuthContext.Provider>
-  );
-};
-
-// Custom hook for using auth context
-export const useAuth = () => {
-  const context = useContext(AuthContext);
-  if (!context) {
-    throw new Error('useAuth must be used within an AuthProvider');
-  }
-  return context;
-};
+### Step 4: Verify - Consensus Swarm (2-4 validators REQUIRED)
+```javascript
+// MANDATORY: Spawn consensus validation swarm
+[Single Message]:
+  Task("Validator 1", "Comprehensive quality review", "reviewer")
+  Task("Validator 2", "Security and performance audit", "security-specialist")
+  Task("Validator 3", "Architecture validation", "system-architect")
+  Task("Validator 4", "Integration testing", "tester")
 ```
+- **Byzantine consensus voting** across all validators
+- **Multi-dimensional checks**: quality, security, performance, tests, docs
 
-**Testing with React Testing Library:**
-```jsx
-import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { jest } from '@jest/globals';
-import UserProfile from '../UserProfile';
-import * as api from '../../services/api';
-
-// Mock the API module
-jest.mock('../../services/api');
-
-describe('UserProfile', () => {
-  const mockUser = {
-    id: '123',
-    name: 'John Doe',
-    email: 'john@example.com',
-    posts: [{ id: 1, title: 'Test Post' }]
-  };
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  test('renders user profile after loading', async () => {
-    api.getUserById.mockResolvedValue(mockUser);
-
-    render(<UserProfile userId="123" />);
-
-    // Check loading state
-    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
-
-    // Wait for user data to load
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
+### Step 5: Decision Gate
+- **PASS**: ≥90% validator agreement + all critical criteria met
+- **FAIL**: <90% agreement OR any critical criterion failed
 
-    expect(screen.getByText('john@example.com')).toBeInTheDocument();
-    expect(screen.getByText('1 Posts')).toBeInTheDocument();
-  });
+### Step 6: Action Based on Decision
+- **PASS** →
+  1. Store results in SwarmMemory
+  2. Update documentation
+  3. Update todos and move to next task
 
-  test('handles update user interaction', async () => {
-    const user = userEvent.setup();
-    const onUpdate = jest.fn();
+- **FAIL** →
+  1. Round counter++
+  2. If Round < 10: Inject validator feedback → Return to Step 2
+  3. If Round ≥ 10: Escalate to human with comprehensive report
 
-    api.getUserById.mockResolvedValue(mockUser);
-    api.updateUser.mockResolvedValue({ ...mockUser, name: 'Jane Doe' });
+### 🚨 ENFORCEMENT CHECKPOINTS
 
-    render(<UserProfile userId="123" onUpdate={onUpdate} />);
+**MANDATORY before proceeding:**
+1. ✅ Agents spawned
+2. ✅ Each file edit followed by enhanced post-edit hook
+3. ✅ Self-validation confidence scores recorded
+4. ✅ Consensus swarm spawned for verification
+5. ✅ Byzantine voting completed
+6. ✅ Results stored in SwarmMemory
 
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
+---
 
-    const editButton = screen.getByRole('button', { name: /edit/i });
-    await user.click(editButton);
+## 🎯 MANDATORY: NEXT STEPS GUIDANCE
 
-    const nameInput = screen.getByDisplayValue('John Doe');
-    await user.clear(nameInput);
-    await user.type(nameInput, 'Jane Doe');
-
-    const saveButton = screen.getByRole('button', { name: /save/i });
-    await user.click(saveButton);
-
-    await waitFor(() => {
-      expect(onUpdate).toHaveBeenCalledWith({ ...mockUser, name: 'Jane Doe' });
-    });
-  });
-
-  test('displays error message on API failure', async () => {
-    api.getUserById.mockRejectedValue(new Error('Network error'));
-
-    render(<UserProfile userId="123" />);
-
-    await waitFor(() => {
-      expect(screen.getByText(/network error/i)).toBeInTheDocument();
-    });
-  });
-});
-```
-
-**Performance Optimization:**
-```jsx
-import React, { memo, lazy, Suspense } from 'react';
-
-// Lazy loading for code splitting
-const LazyUserProfile = lazy(() => import('./UserProfile'));
-const LazyUserSettings = lazy(() => import('./UserSettings'));
-
-// Memoized component to prevent unnecessary re-renders
-const UserCard = memo(({ user, onUpdate }) => {
-  return (
-    <div className="user-card">
-      <h3>{user.name}</h3>
-      <p>{user.email}</p>
-      <button onClick={() => onUpdate(user.id)}>
-        Update
-      </button>
-    </div>
-  );
-});
-
-// Main app with lazy loading
-const App = () => {
-  return (
-    <div className="app">
-      <Suspense fallback={<div>Loading...</div>}>
-        <Routes>
-          <Route path="/profile" element={<LazyUserProfile />} />
-          <Route path="/settings" element={<LazyUserSettings />} />
-        </Routes>
-      </Suspense>
-    </div>
-  );
-};
-```
+**After completing ANY task, you MUST provide:**
 
-**State Management with Zustand:**
-```jsx
-import { create } from 'zustand';
-import { devtools, persist } from 'zustand/middleware';
-
-const useUserStore = create(
-  devtools(
-    persist(
-      (set, get) => ({
-        users: [],
-        currentUser: null,
-        loading: false,
-
-        fetchUsers: async () => {
-          set({ loading: true });
-          try {
-            const users = await api.getUsers();
-            set({ users, loading: false });
-          } catch (error) {
-            set({ loading: false });
-            throw error;
-          }
-        },
-
-        setCurrentUser: (user) => set({ currentUser: user }),
-
-        updateUser: async (userId, updates) => {
-          const updatedUser = await api.updateUser(userId, updates);
-          set((state) => ({
-            users: state.users.map((user) =>
-              user.id === userId ? updatedUser : user
-            ),
-            currentUser: state.currentUser?.id === userId ? updatedUser : state.currentUser
-          }));
-          return updatedUser;
-        }
-      }),
-      { name: 'user-store' }
-    )
-  )
-);
-
-// Usage in component
-const UserList = () => {
-  const { users, loading, fetchUsers } = useUserStore();
-
-  useEffect(() => {
-    fetchUsers();
-  }, [fetchUsers]);
-
-  if (loading) return <LoadingSpinner />;
-
-  return (
-    <div>
-      {users.map((user) => (
-        <UserCard key={user.id} user={user} />
-      ))}
-    </div>
-  );
-};
-```
+1. **✅ What was completed**: Brief summary of delivered work
+2. **📊 Validation results**: Confidence scores, test coverage, consensus approval
+3. **🔍 Identified issues**: Any technical debt, warnings, or concerns discovered
+4. **💡 Recommended next steps**: Prioritized suggestions for logical continuation