From 1ba1a6fb60a9e031898ae01076924c7d94e6b6fa Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Feb 2026 17:22:07 +0000 Subject: [PATCH 1/5] Add CLAUDE.md generated by claude-flow v3 init https://claude.ai/code/session_01QurwDjgvwVJJ4oeZdXPDXN --- CLAUDE.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..27c6e8f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,188 @@ +# Claude Code Configuration - Claude Flow V3 + +## Behavioral Rules (Always Enforced) + +- Do what has been asked; nothing more, nothing less +- NEVER create files unless they're absolutely necessary for achieving your goal +- ALWAYS prefer editing an existing file to creating a new one +- NEVER proactively create documentation files (*.md) or README files unless explicitly requested +- NEVER save working files, text/mds, or tests to the root folder +- Never continuously check status after spawning a swarm — wait for results +- ALWAYS read a file before editing it +- NEVER commit secrets, credentials, or .env files + +## File Organization + +- NEVER save to root folder — use the directories below +- Use `/src` for source code files +- Use `/tests` for test files +- Use `/docs` for documentation and markdown files +- Use `/config` for configuration files +- Use `/scripts` for utility scripts +- Use `/examples` for example code + +## Project Architecture + +- Follow Domain-Driven Design with bounded contexts +- Keep files under 500 lines +- Use typed interfaces for all public APIs +- Prefer TDD London School (mock-first) for new code +- Use event sourcing for state changes +- Ensure input validation at system boundaries + +### Project Config + +- **Topology**: hierarchical-mesh +- **Max Agents**: 15 +- **Memory**: hybrid +- **HNSW**: Enabled +- **Neural**: Enabled + +## Build & Test + +```bash +# Build +npm run build + +# Test +npm test + +# Lint +npm run lint +``` + +- ALWAYS run tests after making code changes +- ALWAYS verify build succeeds before committing + +## Security Rules + +- NEVER hardcode API keys, secrets, or credentials in source files +- NEVER commit .env files or any file containing secrets +- Always validate user input at system boundaries +- Always sanitize file paths to prevent directory traversal +- Run `npx @claude-flow/cli@latest security scan` after security-related changes + +## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS + +- All operations MUST be concurrent/parallel in a single message +- Use Claude Code's Task tool for spawning agents, not just MCP +- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum) +- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool +- ALWAYS batch ALL file reads/writes/edits in ONE message +- ALWAYS batch ALL Bash commands in ONE message + +## Swarm Orchestration + +- MUST initialize the swarm using CLI tools when starting complex tasks +- MUST spawn concurrent agents using Claude Code's Task tool +- Never use CLI tools alone for execution — Task tool agents do the actual work +- MUST call CLI tools AND Task tool in ONE message for complex work + +### 3-Tier Model Routing (ADR-026) + +| Tier | Handler | Latency | Cost | Use Cases | +|------|---------|---------|------|-----------| +| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms (var→const, add types) — Skip LLM | +| **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) | +| **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) | + +- Always check for `[AGENT_BOOSTER_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents +- Use Edit tool directly when `[AGENT_BOOSTER_AVAILABLE]` + +## Swarm Configuration & Anti-Drift + +- ALWAYS use hierarchical topology for coding swarms +- Keep maxAgents at 6-8 for tight coordination +- Use specialized strategy for clear role boundaries +- Use `raft` consensus for hive-mind (leader maintains authoritative state) +- Run frequent checkpoints via `post-task` hooks +- Keep shared memory namespace for all agents + +```bash +npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized +``` + +## Swarm Execution Rules + +- ALWAYS use `run_in_background: true` for all agent Task calls +- ALWAYS put ALL agent Task calls in ONE message for parallel execution +- After spawning, STOP — do NOT add more tool calls or check status +- Never poll TaskOutput or check swarm status — trust agents to return +- When agent results arrive, review ALL results before proceeding + +## V3 CLI Commands + +### Core Commands + +| Command | Subcommands | Description | +|---------|-------------|-------------| +| `init` | 4 | Project initialization | +| `agent` | 8 | Agent lifecycle management | +| `swarm` | 6 | Multi-agent swarm coordination | +| `memory` | 11 | AgentDB memory with HNSW search | +| `task` | 6 | Task creation and lifecycle | +| `session` | 7 | Session state management | +| `hooks` | 17 | Self-learning hooks + 12 workers | +| `hive-mind` | 6 | Byzantine fault-tolerant consensus | + +### Quick CLI Examples + +```bash +npx @claude-flow/cli@latest init --wizard +npx @claude-flow/cli@latest agent spawn -t coder --name my-coder +npx @claude-flow/cli@latest swarm init --v3-mode +npx @claude-flow/cli@latest memory search --query "authentication patterns" +npx @claude-flow/cli@latest doctor --fix +``` + +## Available Agents (60+ Types) + +### Core Development +`coder`, `reviewer`, `tester`, `planner`, `researcher` + +### Specialized +`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer` + +### Swarm Coordination +`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator` + +### GitHub & Repository +`pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager` + +### SPARC Methodology +`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture` + +## Memory Commands Reference + +```bash +# Store (REQUIRED: --key, --value; OPTIONAL: --namespace, --ttl, --tags) +npx @claude-flow/cli@latest memory store --key "pattern-auth" --value "JWT with refresh" --namespace patterns + +# Search (REQUIRED: --query; OPTIONAL: --namespace, --limit, --threshold) +npx @claude-flow/cli@latest memory search --query "authentication patterns" + +# List (OPTIONAL: --namespace, --limit) +npx @claude-flow/cli@latest memory list --namespace patterns --limit 10 + +# Retrieve (REQUIRED: --key; OPTIONAL: --namespace) +npx @claude-flow/cli@latest memory retrieve --key "pattern-auth" --namespace patterns +``` + +## Quick Setup + +```bash +claude mcp add claude-flow -- npx -y @claude-flow/cli@latest +npx @claude-flow/cli@latest daemon start +npx @claude-flow/cli@latest doctor --fix +``` + +## Claude Code vs CLI Tools + +- Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git +- CLI tools handle coordination via Bash: swarm init, memory, hooks, routing +- NEVER use CLI tools as a substitute for Task tool agents + +## Support + +- Documentation: https://github.com/ruvnet/claude-flow +- Issues: https://github.com/ruvnet/claude-flow/issues From 656d51572d353fa220e62c3a383c2ae83dd30160 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Feb 2026 17:42:40 +0000 Subject: [PATCH 2/5] Add Agentic QE v3 initialization Appends QE v3 section to CLAUDE.md with MCP tools, critical policies, and quick reference. Includes .agentic-qe/ database and config. https://claude.ai/code/session_01QurwDjgvwVJJ4oeZdXPDXN --- .agentic-qe/config.yaml | 79 ++++++++ .agentic-qe/data/learning-config.json | 13 ++ .agentic-qe/data/patterns/index.json | 5 + .agentic-qe/memory.db-shm | Bin 0 -> 32768 bytes .agentic-qe/workers/daemon.pid | 1 + .agentic-qe/workers/pattern-consolidator.json | 8 + .agentic-qe/workers/registry.json | 15 ++ .agentic-qe/workers/start-daemon.cjs | 56 ++++++ .agentic-qe/workers/stop-daemon.cjs | 23 +++ CLAUDE.md | 164 +++++++++++++++ CLAUDE.md.backup | 188 ++++++++++++++++++ 11 files changed, 552 insertions(+) create mode 100644 .agentic-qe/config.yaml create mode 100644 .agentic-qe/data/learning-config.json create mode 100644 .agentic-qe/data/patterns/index.json create mode 100644 .agentic-qe/memory.db-shm create mode 100644 .agentic-qe/workers/daemon.pid create mode 100644 .agentic-qe/workers/pattern-consolidator.json create mode 100644 .agentic-qe/workers/registry.json create mode 100644 .agentic-qe/workers/start-daemon.cjs create mode 100644 .agentic-qe/workers/stop-daemon.cjs create mode 100644 CLAUDE.md.backup diff --git a/.agentic-qe/config.yaml b/.agentic-qe/config.yaml new file mode 100644 index 0000000..b2cd779 --- /dev/null +++ b/.agentic-qe/config.yaml @@ -0,0 +1,79 @@ +# Agentic QE v3 Configuration +# Generated by aqe init +# 2026-02-19T17:38:27.216Z +# +# NOTE: Your customizations are PRESERVED when you run "aqe init" again. +# You do NOT need to re-run "aqe init" after editing this file - changes +# take effect immediately. The following settings are merged on reinstall: +# - domains.enabled (custom domains like visual-accessibility) +# - domains.disabled +# - learning.enabled +# - hooks.* preferences +# - workers.enabled +# - agents.maxConcurrent and defaultTimeout + +version: "3.6.13" + +project: + name: "cf-devpod" + root: "/home/user/cf-devpod" + type: "single" + +learning: + enabled: true + embeddingModel: "transformer" + hnswConfig: + M: 8 + efConstruction: 100 + efSearch: 50 + qualityThreshold: 0.5 + promotionThreshold: 2 + pretrainedPatterns: true + +routing: + mode: "ml" + confidenceThreshold: 0.7 + feedbackEnabled: true + +workers: + enabled: + - "pattern-consolidator" + intervals: + pattern-consolidator: 1800000 + coverage-gap-scanner: 3600000 + flaky-test-detector: 7200000 + routing-accuracy-monitor: 900000 + maxConcurrent: 2 + daemonAutoStart: true + +hooks: + claudeCode: true + preCommit: false + ciIntegration: false + +skills: + install: true + installV2: true + installV3: true + overwrite: false + +domains: + enabled: + - "test-generation" + - "test-execution" + - "coverage-analysis" + - "quality-assessment" + - "defect-intelligence" + - "requirements-validation" + - "code-intelligence" + - "security-compliance" + - "contract-testing" + - "visual-accessibility" + - "chaos-resilience" + - "learning-optimization" + - "enterprise-integration" + disabled: + +agents: + maxConcurrent: 5 + defaultTimeout: 60000 diff --git a/.agentic-qe/data/learning-config.json b/.agentic-qe/data/learning-config.json new file mode 100644 index 0000000..d371d2e --- /dev/null +++ b/.agentic-qe/data/learning-config.json @@ -0,0 +1,13 @@ +{ + "embeddingModel": "transformer", + "hnswConfig": { + "M": 8, + "efConstruction": 100, + "efSearch": 50 + }, + "qualityThreshold": 0.5, + "promotionThreshold": 2, + "databasePath": "/home/user/cf-devpod/.agentic-qe/data/memory.db", + "hnswIndexPath": "/home/user/cf-devpod/.agentic-qe/data/hnsw/index.bin", + "initialized": "2026-02-19T17:38:24.021Z" +} \ No newline at end of file diff --git a/.agentic-qe/data/patterns/index.json b/.agentic-qe/data/patterns/index.json new file mode 100644 index 0000000..091a3c0 --- /dev/null +++ b/.agentic-qe/data/patterns/index.json @@ -0,0 +1,5 @@ +{ + "version": "3.6.13", + "domains": [], + "loadedAt": "2026-02-19T17:38:24.022Z" +} \ No newline at end of file diff --git a/.agentic-qe/memory.db-shm b/.agentic-qe/memory.db-shm new file mode 100644 index 0000000000000000000000000000000000000000..f01640df3094288d31cf82851ea4918565af1892 GIT binary patch literal 32768 zcmeI)KTbkH5C`A^9)BK!VnV?Q>})uI@dU=k%93~zV+@7o@fIF}gpg2i1Dz!lmRgei ze#z|HY&LH*-vMT^xs8%;RwrV1mEZTQ_F?$7-My`stGlP0kNL~zx&Yhb?nRO=w2oR`8piI{k0t5&U yAV7cs0RjXF5FkK+009C72oNAZfB*pk1PBlyK!5-N0t5&UAV7cs0RjZhQQ!y0IVCFq literal 0 HcmV?d00001 diff --git a/.agentic-qe/workers/daemon.pid b/.agentic-qe/workers/daemon.pid new file mode 100644 index 0000000..673bb65 --- /dev/null +++ b/.agentic-qe/workers/daemon.pid @@ -0,0 +1 @@ +2575 \ No newline at end of file diff --git a/.agentic-qe/workers/pattern-consolidator.json b/.agentic-qe/workers/pattern-consolidator.json new file mode 100644 index 0000000..b96a347 --- /dev/null +++ b/.agentic-qe/workers/pattern-consolidator.json @@ -0,0 +1,8 @@ +{ + "name": "pattern-consolidator", + "enabled": true, + "interval": 1800000, + "projectRoot": "/home/user/cf-devpod", + "dataDir": "/home/user/cf-devpod/.agentic-qe/data", + "createdAt": "2026-02-19T17:38:25.645Z" +} \ No newline at end of file diff --git a/.agentic-qe/workers/registry.json b/.agentic-qe/workers/registry.json new file mode 100644 index 0000000..33bf1e4 --- /dev/null +++ b/.agentic-qe/workers/registry.json @@ -0,0 +1,15 @@ +{ + "version": "3.6.13", + "maxConcurrent": 2, + "workers": { + "pattern-consolidator": { + "name": "pattern-consolidator", + "enabled": true, + "interval": 1800000, + "lastRun": null, + "status": "pending" + } + }, + "createdAt": "2026-02-19T17:38:25.645Z", + "daemonPid": null +} \ No newline at end of file diff --git a/.agentic-qe/workers/start-daemon.cjs b/.agentic-qe/workers/start-daemon.cjs new file mode 100644 index 0000000..198907b --- /dev/null +++ b/.agentic-qe/workers/start-daemon.cjs @@ -0,0 +1,56 @@ +#!/usr/bin/env node +// AQE v3 Worker Daemon Startup Script (cross-platform) +// Generated by aqe init +// Starts the MCP server with background workers enabled + +const { existsSync, readFileSync, writeFileSync, appendFileSync } = require('fs'); +const { join } = require('path'); +const { spawn } = require('child_process'); + +const projectRoot = join(__dirname, '..', '..'); +const workersDir = join(projectRoot, '.agentic-qe', 'workers'); +const pidFile = join(workersDir, 'daemon.pid'); +const logFile = join(workersDir, 'daemon.log'); + +// Check if already running +if (existsSync(pidFile)) { + const pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10); + try { process.kill(pid, 0); console.log('Daemon already running (PID: ' + pid + ')'); process.exit(0); } catch {} +} + +const ts = new Date().toISOString(); +appendFileSync(logFile, '[' + ts + '] Starting AQE v3 Worker Daemon...\n'); + +// Find the best way to run aqe-mcp +const candidates = [ + join(projectRoot, 'node_modules', '.bin', 'aqe-mcp'), + join(projectRoot, 'node_modules', 'agentic-qe', 'v3', 'dist', 'mcp', 'bundle.js'), +]; + +let mcpCmd, mcpArgs; +const binCandidate = candidates.find(c => existsSync(c)); + +if (binCandidate && binCandidate.endsWith('bundle.js')) { + mcpCmd = process.execPath; + mcpArgs = [binCandidate]; +} else if (binCandidate) { + mcpCmd = binCandidate; + mcpArgs = []; +} else { + mcpCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx'; + mcpArgs = ['--yes', 'agentic-qe', 'mcp']; +} + +appendFileSync(logFile, '[' + ts + '] Using: ' + mcpCmd + ' ' + mcpArgs.join(' ') + '\n'); + +const env = { ...process.env, AQE_PROJECT_ROOT: projectRoot, AQE_LEARNING_ENABLED: 'true', AQE_WORKERS_ENABLED: 'true', AQE_HTTP_PORT: '0' }; +const child = spawn(mcpCmd, mcpArgs, { cwd: projectRoot, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] }); +child.stdout.on('data', d => appendFileSync(logFile, d)); +child.stderr.on('data', d => appendFileSync(logFile, d)); +child.unref(); + +writeFileSync(pidFile, String(child.pid)); +appendFileSync(logFile, '[' + ts + '] Daemon started with PID: ' + child.pid + '\n'); +console.log('AQE v3 Worker Daemon started (PID: ' + child.pid + ')'); +console.log('Log file: ' + logFile); +console.log('To stop: node ' + join(workersDir, 'stop-daemon.cjs')); diff --git a/.agentic-qe/workers/stop-daemon.cjs b/.agentic-qe/workers/stop-daemon.cjs new file mode 100644 index 0000000..fcc303e --- /dev/null +++ b/.agentic-qe/workers/stop-daemon.cjs @@ -0,0 +1,23 @@ +#!/usr/bin/env node +// AQE v3 Worker Daemon Stop Script (cross-platform) +// Generated by aqe init + +const { existsSync, readFileSync, unlinkSync } = require('fs'); +const { join } = require('path'); + +const workersDir = join(__dirname); +const pidFile = join(workersDir, 'daemon.pid'); + +if (!existsSync(pidFile)) { console.log('No PID file found - daemon may not be running'); process.exit(0); } + +const pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10); +try { + process.kill(pid, 0); // Check if alive + console.log('Stopping daemon (PID: ' + pid + ')...'); + process.kill(pid, 'SIGTERM'); + try { unlinkSync(pidFile); } catch {} + console.log('Daemon stopped'); +} catch { + console.log('Daemon not running (stale PID file)'); + try { unlinkSync(pidFile); } catch {} +} diff --git a/CLAUDE.md b/CLAUDE.md index 27c6e8f..804b92c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -186,3 +186,167 @@ npx @claude-flow/cli@latest doctor --fix - Documentation: https://github.com/ruvnet/claude-flow - Issues: https://github.com/ruvnet/claude-flow/issues + + +## Agentic QE v3 + +This project uses **Agentic QE v3** - a Domain-Driven Quality Engineering platform with 13 bounded contexts, ReasoningBank learning, HNSW vector search, and Agent Teams coordination (ADR-064). + +--- + +### CRITICAL POLICIES + +#### Integrity Rule (ABSOLUTE) +- NO shortcuts, fake data, or false claims +- ALWAYS implement properly, verify before claiming success +- ALWAYS use real database queries for integration tests +- ALWAYS run actual tests, not assume they pass + +**We value the quality we deliver to our users.** + +#### Test Execution +- NEVER run `npm test` without `--run` flag (watch mode risk) +- Use: `npm test -- --run`, `npm run test:unit`, `npm run test:integration` when available + +#### Data Protection +- NEVER run `rm -f` on `.agentic-qe/` or `*.db` files without confirmation +- ALWAYS backup before database operations + +#### Git Operations +- NEVER auto-commit/push without explicit user request +- ALWAYS wait for user confirmation before git operations + +--- + +### Quick Reference + +```bash +# Run tests +npm test -- --run + +# Check quality +aqe quality assess + +# Generate tests +aqe test generate + +# Coverage analysis +aqe coverage +``` + +### Using AQE MCP Tools + +AQE exposes tools via MCP with the `mcp__agentic-qe__` prefix. You MUST call `fleet_init` before any other tool. + +#### 1. Initialize the Fleet (required first step) + +```typescript +mcp__agentic-qe__fleet_init({ + topology: "hierarchical", + maxAgents: 15, + memoryBackend: "hybrid" +}) +``` + +#### 2. Generate Tests + +```typescript +mcp__agentic-qe__test_generate_enhanced({ + targetPath: "src/services/auth.ts", + framework: "vitest", + strategy: "boundary-value" +}) +``` + +#### 3. Analyze Coverage + +```typescript +mcp__agentic-qe__coverage_analyze_sublinear({ + paths: ["src/"], + threshold: 80 +}) +``` + +#### 4. Assess Quality + +```typescript +mcp__agentic-qe__quality_assess({ + scope: "full", + includeMetrics: true +}) +``` + +#### 5. Store and Query Patterns (with learning persistence) + +```typescript +// Store a learned pattern +mcp__agentic-qe__memory_store({ + key: "patterns/coverage-gap/{timestamp}", + namespace: "learning", + value: { + pattern: "...", + confidence: 0.95, + type: "coverage-gap", + metadata: { /* domain-specific */ } + }, + persist: true +}) + +// Query stored patterns +mcp__agentic-qe__memory_query({ + pattern: "patterns/*", + namespace: "learning", + limit: 10 +}) +``` + +#### 6. Orchestrate Multi-Agent Tasks + +```typescript +mcp__agentic-qe__task_orchestrate({ + task: "Full quality assessment of auth module", + domains: ["test-generation", "coverage-analysis", "security-compliance"], + parallel: true +}) +``` + +### MCP Tool Reference + +| Tool | Description | +|------|-------------| +| `fleet_init` | Initialize QE fleet (MUST call first) | +| `fleet_status` | Get fleet health and agent status | +| `agent_spawn` | Spawn specialized QE agent | +| `test_generate_enhanced` | AI-powered test generation | +| `test_execute_parallel` | Parallel test execution with retry | +| `task_orchestrate` | Orchestrate multi-agent QE tasks | +| `coverage_analyze_sublinear` | O(log n) coverage analysis | +| `quality_assess` | Quality gate evaluation | +| `memory_store` | Store patterns with namespace + persist | +| `memory_query` | Query patterns by namespace/pattern | +| `security_scan_comprehensive` | SAST/DAST scanning | + +### Configuration + +- **Enabled Domains**: test-generation, test-execution, coverage-analysis, quality-assessment, defect-intelligence, requirements-validation (+7 more) +- **Learning**: Enabled (transformer embeddings) +- **Max Concurrent Agents**: 5 +- **Background Workers**: pattern-consolidator + +### V3 QE Agents + +V3 QE agents are in `.claude/agents/v3/`. Use with Task tool: + +```javascript +Task({ prompt: "Generate tests", subagent_type: "qe-test-architect", run_in_background: true }) +Task({ prompt: "Find coverage gaps", subagent_type: "qe-coverage-specialist", run_in_background: true }) +Task({ prompt: "Security audit", subagent_type: "qe-security-scanner", run_in_background: true }) +``` + +### Data Storage + +- **Memory Backend**: `.agentic-qe/memory.db` (SQLite) +- **Configuration**: `.agentic-qe/config.yaml` + +--- +*Generated by AQE v3 init - 2026-02-19T17:38:27.211Z* diff --git a/CLAUDE.md.backup b/CLAUDE.md.backup new file mode 100644 index 0000000..27c6e8f --- /dev/null +++ b/CLAUDE.md.backup @@ -0,0 +1,188 @@ +# Claude Code Configuration - Claude Flow V3 + +## Behavioral Rules (Always Enforced) + +- Do what has been asked; nothing more, nothing less +- NEVER create files unless they're absolutely necessary for achieving your goal +- ALWAYS prefer editing an existing file to creating a new one +- NEVER proactively create documentation files (*.md) or README files unless explicitly requested +- NEVER save working files, text/mds, or tests to the root folder +- Never continuously check status after spawning a swarm — wait for results +- ALWAYS read a file before editing it +- NEVER commit secrets, credentials, or .env files + +## File Organization + +- NEVER save to root folder — use the directories below +- Use `/src` for source code files +- Use `/tests` for test files +- Use `/docs` for documentation and markdown files +- Use `/config` for configuration files +- Use `/scripts` for utility scripts +- Use `/examples` for example code + +## Project Architecture + +- Follow Domain-Driven Design with bounded contexts +- Keep files under 500 lines +- Use typed interfaces for all public APIs +- Prefer TDD London School (mock-first) for new code +- Use event sourcing for state changes +- Ensure input validation at system boundaries + +### Project Config + +- **Topology**: hierarchical-mesh +- **Max Agents**: 15 +- **Memory**: hybrid +- **HNSW**: Enabled +- **Neural**: Enabled + +## Build & Test + +```bash +# Build +npm run build + +# Test +npm test + +# Lint +npm run lint +``` + +- ALWAYS run tests after making code changes +- ALWAYS verify build succeeds before committing + +## Security Rules + +- NEVER hardcode API keys, secrets, or credentials in source files +- NEVER commit .env files or any file containing secrets +- Always validate user input at system boundaries +- Always sanitize file paths to prevent directory traversal +- Run `npx @claude-flow/cli@latest security scan` after security-related changes + +## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS + +- All operations MUST be concurrent/parallel in a single message +- Use Claude Code's Task tool for spawning agents, not just MCP +- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum) +- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool +- ALWAYS batch ALL file reads/writes/edits in ONE message +- ALWAYS batch ALL Bash commands in ONE message + +## Swarm Orchestration + +- MUST initialize the swarm using CLI tools when starting complex tasks +- MUST spawn concurrent agents using Claude Code's Task tool +- Never use CLI tools alone for execution — Task tool agents do the actual work +- MUST call CLI tools AND Task tool in ONE message for complex work + +### 3-Tier Model Routing (ADR-026) + +| Tier | Handler | Latency | Cost | Use Cases | +|------|---------|---------|------|-----------| +| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms (var→const, add types) — Skip LLM | +| **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) | +| **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) | + +- Always check for `[AGENT_BOOSTER_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents +- Use Edit tool directly when `[AGENT_BOOSTER_AVAILABLE]` + +## Swarm Configuration & Anti-Drift + +- ALWAYS use hierarchical topology for coding swarms +- Keep maxAgents at 6-8 for tight coordination +- Use specialized strategy for clear role boundaries +- Use `raft` consensus for hive-mind (leader maintains authoritative state) +- Run frequent checkpoints via `post-task` hooks +- Keep shared memory namespace for all agents + +```bash +npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized +``` + +## Swarm Execution Rules + +- ALWAYS use `run_in_background: true` for all agent Task calls +- ALWAYS put ALL agent Task calls in ONE message for parallel execution +- After spawning, STOP — do NOT add more tool calls or check status +- Never poll TaskOutput or check swarm status — trust agents to return +- When agent results arrive, review ALL results before proceeding + +## V3 CLI Commands + +### Core Commands + +| Command | Subcommands | Description | +|---------|-------------|-------------| +| `init` | 4 | Project initialization | +| `agent` | 8 | Agent lifecycle management | +| `swarm` | 6 | Multi-agent swarm coordination | +| `memory` | 11 | AgentDB memory with HNSW search | +| `task` | 6 | Task creation and lifecycle | +| `session` | 7 | Session state management | +| `hooks` | 17 | Self-learning hooks + 12 workers | +| `hive-mind` | 6 | Byzantine fault-tolerant consensus | + +### Quick CLI Examples + +```bash +npx @claude-flow/cli@latest init --wizard +npx @claude-flow/cli@latest agent spawn -t coder --name my-coder +npx @claude-flow/cli@latest swarm init --v3-mode +npx @claude-flow/cli@latest memory search --query "authentication patterns" +npx @claude-flow/cli@latest doctor --fix +``` + +## Available Agents (60+ Types) + +### Core Development +`coder`, `reviewer`, `tester`, `planner`, `researcher` + +### Specialized +`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer` + +### Swarm Coordination +`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator` + +### GitHub & Repository +`pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager` + +### SPARC Methodology +`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture` + +## Memory Commands Reference + +```bash +# Store (REQUIRED: --key, --value; OPTIONAL: --namespace, --ttl, --tags) +npx @claude-flow/cli@latest memory store --key "pattern-auth" --value "JWT with refresh" --namespace patterns + +# Search (REQUIRED: --query; OPTIONAL: --namespace, --limit, --threshold) +npx @claude-flow/cli@latest memory search --query "authentication patterns" + +# List (OPTIONAL: --namespace, --limit) +npx @claude-flow/cli@latest memory list --namespace patterns --limit 10 + +# Retrieve (REQUIRED: --key; OPTIONAL: --namespace) +npx @claude-flow/cli@latest memory retrieve --key "pattern-auth" --namespace patterns +``` + +## Quick Setup + +```bash +claude mcp add claude-flow -- npx -y @claude-flow/cli@latest +npx @claude-flow/cli@latest daemon start +npx @claude-flow/cli@latest doctor --fix +``` + +## Claude Code vs CLI Tools + +- Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git +- CLI tools handle coordination via Bash: swarm init, memory, hooks, routing +- NEVER use CLI tools as a substitute for Task tool agents + +## Support + +- Documentation: https://github.com/ruvnet/claude-flow +- Issues: https://github.com/ruvnet/claude-flow/issues From b8ef95b1811528c25488e0f43080cbf79da3503b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Feb 2026 17:44:19 +0000 Subject: [PATCH 3/5] Update agentic-qe memory database shared memory file https://claude.ai/code/session_01QurwDjgvwVJJ4oeZdXPDXN --- .agentic-qe/memory.db-shm | Bin 32768 -> 32768 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/.agentic-qe/memory.db-shm b/.agentic-qe/memory.db-shm index f01640df3094288d31cf82851ea4918565af1892..c16dffc0bcf6c200c146cf581c858ac346e8c615 100644 GIT binary patch delta 249 zcmZo@U}|V!s+V}A%K!q55G)`Mq}zd5r8DbT6z8jEqhz~KwO)}_&koTyv8GP%NmUOt z3Jhd`2}KtG delta 195 zcmZo@U}|V!s+V}A%K!pQK+MR%Aixi#+ku$VkNw=!=dGPa$#$V?y&|d6A6_wRcL)$9 zRXxxsFyH}_|B(Pxn2CXNVx#kB7RFzWlLZ(ZHve;CVcX2a_>GC3m4SnSn}KgLBja}_ bb~Xl11|9}}Am=N~=1;*QN}B~3e{li;b51pb From fb9af2677107d8613d653b03b4efd630052c69d6 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Mar 2026 20:46:32 +0000 Subject: [PATCH 4/5] Update agentic-qe runtime files (memory shm, brain state) https://claude.ai/code/session_01QurwDjgvwVJJ4oeZdXPDXN --- .agentic-qe/brain.rvf | Bin 0 -> 162 bytes .agentic-qe/brain.rvf.lock | Bin 0 -> 104 bytes .agentic-qe/memory.db-shm | Bin 32768 -> 32768 bytes 3 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 .agentic-qe/brain.rvf create mode 100644 .agentic-qe/brain.rvf.lock diff --git a/.agentic-qe/brain.rvf b/.agentic-qe/brain.rvf new file mode 100644 index 0000000000000000000000000000000000000000..ffe344683843021805947fca9925f0cf455257a1 GIT binary patch literal 162 zcmWG`3kzaoWnf@rfPf?@jZPg~#Ajp#B=~>?ka-MQz5%8gS&+fg#na6u_o2|i-DTHB QqEhvf9_K7UQ9vXI08L*JqyPW_ literal 0 HcmV?d00001 diff --git a/.agentic-qe/brain.rvf.lock b/.agentic-qe/brain.rvf.lock new file mode 100644 index 0000000000000000000000000000000000000000..31c55aa30b5326f3d883dce1b3e1bb1e7315129d GIT binary patch literal 104 xcmZ?s2@6`o#y~MpX4#XvJAbCc>U}a>$}TLkIK3@d_|ELB%8WphH*h?!1pu?T5AXm0 literal 0 HcmV?d00001 diff --git a/.agentic-qe/memory.db-shm b/.agentic-qe/memory.db-shm index c16dffc0bcf6c200c146cf581c858ac346e8c615..566f3a73b4cce2a7c42ed207dbc4b0676f7e919a 100644 GIT binary patch literal 32768 zcmeI5b#N6)5Qo1X1a}Ya?!hg%ySux)yK8WFcXvN`;auR96X4uA=Vk*`U8RyMLLSu1 zrKjpwHLu@J&&=1oyMJv@;MKx-O}CZ&qU$Vn{nOWPTnbKcvwu+c;FftpQumzSI{US_ zLoZ(mjO6v6Z?BzmesBG&-L~Ggdwp;I=}xnqVmk#m#ff5nq8mTSX|mH4r^x!f*YS7P zKF7^*w?EhQb2#O6D&SPmsgP56wp`Ah+sTVW5vQU~#hjvgZFC*<0G>!n=5j$jVMnRgp(tl?OtQ?U)OqbM&u{N{kPC5yl2?| z!JfzMEw59MlgGjPozE%1llNRN?&SUFJ^#Ju{@wf4! zT+Sx;a)`4$&5OLvRj%;^e-TSb6sXL~rxGfw>T05v>Y_v5=bP4yz#Rf|brwqSI1SWS z`}{gL%2Szow4@z9>BmUMG1Gllyn@Z_<1puVhL?DUPq@yH{7q~nReEJnew9=?)lgHl zQdhs;pQWS`h?qb%8q$%0OmyGauVx#^xX7!#$5-4Wo>D4@3agUpsGWLhfQD8t?NpzY<@mlv70%th#EiUK*$o8mB3mr3G55)!L}-ezu#Kl3)J4&p5;< z5lKlwYBG|A?5?^?L05h1tSuVbyc@=yXtI3U6neo{+&Oy znlzycLzvgb;orFrG+$yFjs;`dfqrn=b37V!kTBzk(tIgW!XS?wy zvbGlgCve#E*XKd4g~hYJ0~N$kW9nn3<}SJrD8(_${^$}cTc?i+Jj-#* zejhV6chQBwbG*#Ee98@e;uZl)rVPre0xG5Qs;LupXGE7k+B)xpKr^*gH=VRBzYlgc z#6Jm?rUJESN-Mh3i=m8SDhpV`dUmm&Q#?V#JNZ7u^4>o~Xsfz!0%fR3ZJN=VZuDjt zqnSnsOWD9~4se<$d7d}F!PFYqzywKQ8 z51c?%8qk3OOmOGLtzs)jxxg!2;Y)rYu2Lww3aO%MtF3ydzlLdyCTWJ|X|Yyny|(JK z-472uMmE8NBCuQgEq@;rT=VPa1ol|&`#eHvL(jDHxm$DSa{>n}`+d$dUFhkKK6h&l zeNNz@Wxvmv28Nzx>T|c|(B}loQi(b=rw!fd!*Is96Vn&6jE(H!AZK`r7kG=0`JC_h j6DhIMDU Date: Tue, 3 Mar 2026 20:58:32 +0000 Subject: [PATCH 5/5] Update agentic-qe runtime state files https://claude.ai/code/session_01QurwDjgvwVJJ4oeZdXPDXN --- .agentic-qe/brain.rvf.lock | Bin 104 -> 104 bytes .agentic-qe/memory.db-shm | Bin 32768 -> 32768 bytes 2 files changed, 0 insertions(+), 0 deletions(-) diff --git a/.agentic-qe/brain.rvf.lock b/.agentic-qe/brain.rvf.lock index 31c55aa30b5326f3d883dce1b3e1bb1e7315129d..579c91038ab78839f108b2e1228908ef6f68619d 100644 GIT binary patch literal 104 wcmZ?s2@6`q%|J0oi)NHdE|@9Na?N5(W6PE{<(JC2S)SZ$7=b4H^Y2y%0FD|BAOHXW literal 104 xcmZ?s2@6`o#y~MpX4#XvJAbCc>U}a>$}TLkIK3@d_|ELB%8WphH*h?!1pu?T5AXm0 diff --git a/.agentic-qe/memory.db-shm b/.agentic-qe/memory.db-shm index 566f3a73b4cce2a7c42ed207dbc4b0676f7e919a..8b4d0a809963b827b2f18ae31a1e0b9c1e6f42ad 100644 GIT binary patch delta 241 zcmZo@U}|V!s+V}A%K!q55G-&S$d~|RS4j#T4twO4Zj@{ns@5x#n$dOi#FM4JR+Fk8 zWHtz#0Gj(B2|z>{m>5oMZ2ZqQ@q)?b2KH|jn^!sHaIo%YJjQr(@?08Nnpz)b4P_=WK{m>70%Z2Zr*c?