Skip to content

CLAUDE.md

Latest commit

 

History

History
executable file
·
541 lines (403 loc) · 19 KB

CLAUDE.md

File metadata and controls

executable file
·
541 lines (403 loc) · 19 KB

Claude Code Configuration - Agentic QE Fleet

⚠️ CRITICAL POLICIES

Integrity Rule (ABSOLUTE)

  • ❌ NO shortcuts - do the work properly or don't do it
  • ❌ NO fake data - use real data, real tests, real results
  • ❌ NO false claims - only report what actually works and is verified
  • ✅ ALWAYS implement all code/tests with proper implementation
  • ✅ ALWAYS verify before claiming success
  • ✅ ALWAYS use real database queries, not mocks, for integration tests
  • ✅ ALWAYS run actual tests, not assume they pass

We value the quality we deliver to our users.

🤖 SENTINEL PROJECT - Agentic API Testing Platform

Project Overview

Sentinel is an AI-powered platform for automating the entire API testing lifecycle using specialized AI agents. The project combines Claude-Flow orchestration with Agentic QE Fleet for comprehensive testing.

Core Architecture

  • Frontend: React-based UI (Port 3000) with Redux state management
  • Backend Services: Python microservices with FastAPI (Ports 8000-8005, 8088)
    • API Gateway (8000), Auth (8005), Spec (8001), Orchestration (8002), Execution (8003), Data (8004)
  • Rust Core: High-performance agent core (8088) powered by ruv-swarm
  • Database: PostgreSQL with pgvector extension (Port 5432)
  • Message Broker: RabbitMQ for asynchronous task processing (Ports 5672/15672)
  • Observability: Prometheus (9090), Jaeger (16686)

Hybrid Python/Rust Agents

The platform implements both Python and Rust agents for optimal performance:

Functional Testing

  • Functional-Positive-Agent: Valid "happy path" tests (Python/Rust)
  • Functional-Negative-Agent: Boundary value analysis and negative tests (Python/Rust)
  • Functional-Stateful-Agent: Multi-step workflows with SODG graphs (Python/Rust)

Security Testing

  • Security-Auth-Agent: BOLA, authorization bypass (Python/Rust)
  • Security-Injection-Agent: SQL/NoSQL/Command/LLM injection (Python/Rust)

Performance Testing

  • Performance-Planner-Agent: k6/JMeter/Locust scripts (Python/Rust)

Data Generation

  • Data-Mocking-Agent: Schema-aware test data (Python/Rust)

Performance: Rust agents provide 18-21x faster execution with automatic fallback to Python for resilience.

Advanced AI Features

  • Consciousness Verification: Self-modifying test generation with pattern learning
  • Psycho-Symbolic Reasoning: Combines psychological models with symbolic logic
  • Temporal Consciousness: Nanosecond-precision scheduling
  • Knowledge Graph Integration: Semantic understanding of API relationships
  • Sublinear Solvers: O(log n) performance for large-scale optimization

Multi-LLM Provider Support

Supports multiple LLM providers with automatic fallback:

  • Anthropic (Default): Claude Opus 4.1/4, Sonnet 4, Haiku 3.5
  • OpenAI: GPT-4 Turbo, GPT-4, GPT-3.5 Turbo
  • Google: Gemini 2.5 Pro/Flash, Gemini 2.0 Flash
  • Mistral: Large, Small 3, Codestral
  • Ollama (Local): DeepSeek-R1, Llama 3.3, Qwen 2.5

Configure via: cd sentinel_backend/scripts && ./switch_llm.sh

Testing Infrastructure

  • 540+ comprehensive tests with 97.8% pass rate
  • 184 AI agent tests (Phase 1 complete)
  • 272 LLM provider tests (Phase 2 complete)
  • 45+ Playwright E2E tests for frontend
  • Performance testing: Load, stress, concurrent execution

Quick Start Commands

# Complete setup
make setup

# Start all services
make start

# Initialize/repair database
make init-db

# Check service status
make status

# Run tests in Docker
cd sentinel_backend && ./run_tests.sh -d

Release Workflow:

git checkout -b release/vX.X.X    # 1. Create branch
# Update all version files above    # 2. Update versions
npm run test:fast                   # 3. Run tests
git commit -m "chore(release): bump version to vX.X.X"
git push -u origin release/vX.X.X  # 4. Push branch
gh pr create                        # 5. Create PR to main
# Wait for CI and review            # 6. Review
# Merge PR                          # 7. Merge
git tag vX.X.X && git push origin vX.X.X  # 8. Tag
gh release create vX.X.X            # 9. GitHub release
npm publish --access public         # 10. npm publish

🤖 Agentic QE Fleet Quick Reference

19 QE Agents: Test generation, coverage analysis, performance, security, flaky detection, QX analysis 11 QE Subagents: TDD specialists, code reviewers, integration testers 41 QE Skills: agentic-quality-engineering, tdd-london-chicago, api-testing-patterns, six-thinking-hats, brutal-honesty-review, sherlock-review, cicd-pipeline-qe-orchestrator, accessibility-testing, shift-left-testing, testability-scoring (contributed by @fndlalit) 8 Slash Commands: /aqe-execute, /aqe-generate, /aqe-coverage, /aqe-quality

📚 Complete Documentation

🎯 Quick Start

Spawn agents:

Task("Generate tests", "Create test suite for UserService", "qe-test-generator")
Task("Analyze coverage", "Find gaps using O(log n)", "qe-coverage-analyzer")

Check learning status:

aqe learn status --agent test-gen
aqe patterns list --framework jest

💡 Key Principles

  • Use Task tool for agent execution (not just MCP)
  • Batch all operations in single messages (TodoWrite, file ops, etc.)
  • Test with actual databases, not mocks
  • Document only what actually works

Claude Flow Integration (Preserved from original CLAUDE.md)

🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT

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

⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"

MANDATORY PATTERNS:

  • 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 Claude Flow Agent Execution

Claude Code's Task tool is the PRIMARY way to spawn Claude Flow agents:

// ✅ 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")

Claude Flow MCP tools are ONLY for coordination setup:

  • mcp__claude-flow__swarm_init - Initialize coordination topology
  • mcp__claude-flow__agent_spawn - Define agent types for coordination
  • mcp__claude-flow__task_orchestrate - Orchestrate high-level workflows

📁 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

Project Overview

This project uses SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology with Claude-Flow orchestration for systematic Test-Driven Development.

SPARC Commands

Core Commands

  • npx claude-flow sparc modes - List available modes
  • npx claude-flow sparc run <mode> "<task>" - Execute specific mode
  • npx claude-flow sparc tdd "<feature>" - Run complete TDD workflow
  • npx claude-flow sparc info <mode> - Get mode details

Batchtools Commands

  • npx claude-flow sparc batch <modes> "<task>" - Parallel execution
  • npx claude-flow sparc pipeline "<task>" - Full pipeline processing
  • npx claude-flow sparc concurrent <mode> "<tasks-file>" - Multi-task processing

Build Commands

  • npm run build - Build project
  • npm run test - Run tests
  • npm run lint - Linting
  • npm run typecheck - Type checking

SPARC Workflow Phases

  1. Specification - Requirements analysis (sparc run spec-pseudocode)
  2. Pseudocode - Algorithm design (sparc run spec-pseudocode)
  3. Architecture - System design (sparc run architect)
  4. Refinement - TDD implementation (sparc tdd)
  5. Completion - Integration (sparc run integration)

Code Style & Best Practices

  • Modular Design: Files under 500 lines
  • Environment Safety: Never hardcode secrets
  • Test-First: Write tests before implementation
  • Clean Architecture: Separate concerns
  • Documentation: Keep updated

🚀 Claude Flow Available Agents (54 Total)

Core Development

coder, reviewer, tester, planner, researcher

Swarm Coordination

hierarchical-coordinator, mesh-coordinator, adaptive-coordinator, collective-intelligence-coordinator, swarm-memory-manager

Consensus & Distributed

byzantine-coordinator, raft-manager, gossip-coordinator, consensus-builder, crdt-synchronizer, quorum-manager, security-manager

Performance & Optimization

perf-analyzer, performance-benchmarker, task-orchestrator, memory-coordinator, smart-agent

GitHub & Repository

github-modes, pr-manager, code-review-swarm, issue-tracker, release-manager, workflow-automation, project-board-sync, repo-architect, multi-repo-swarm

SPARC Methodology

sparc-coord, sparc-coder, specification, pseudocode, architecture, refinement

Specialized Development

backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs, system-architect, code-analyzer, base-template-generator

Claude Flow Testing & Validation

tdd-london-swarm, production-validator

Migration & Planning

migration-planner, swarm-init

🎯 Claude Code vs MCP Tools

Claude Code Handles ALL EXECUTION:

  • Task tool: Spawn and run agents concurrently for actual work
  • File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
  • 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.

🚀 Quick Setup

# Add MCP servers (Claude Flow required, others optional)
claude mcp add claude-flow npx claude-flow@alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional: Enhanced coordination

MCP Tool Categories

Coordination

swarm_init, agent_spawn, task_orchestrate

Monitoring

swarm_status, agent_list, agent_metrics, task_status, task_results

Memory & Neural

memory_usage, neural_status, neural_train, neural_patterns

GitHub Integration

github_swarm, repo_analyze, pr_enhance, issue_triage, code_review

System

benchmark_run, features_detect, swarm_monitor

🚀 Agent Execution Flow with Claude Code

The Correct Pattern:

  1. Optional: Use MCP tools to set up coordination topology
  2. REQUIRED: Use Claude Code's Task tool to spawn agents that do actual work
  3. REQUIRED: Each agent runs hooks for coordination
  4. REQUIRED: Batch all operations in single messages

Example Full-Stack Development:

// Single message with all agent spawning via Claude Code's Task tool
[Parallel Agent Execution]:
  Task("Backend Developer", "Build REST API with Express. Use hooks for coordination.", "backend-dev")
  Task("Frontend Developer", "Create React UI. Coordinate with backend via memory.", "coder")
  Task("Database Architect", "Design PostgreSQL schema. Store schema in memory.", "code-analyzer")
  Task("Test Engineer", "Write Jest tests. Check memory for API contracts.", "tester")
  Task("DevOps Engineer", "Setup Docker and CI/CD. Document in memory.", "cicd-engineer")
  Task("Security Auditor", "Review authentication. Report findings via hooks.", "reviewer")
  
  // All todos batched together
  TodoWrite { todos: [...8-10 todos...] }
  
  // All file operations together
  Write "backend/server.js"
  Write "frontend/App.jsx"
  Write "database/schema.sql"

📋 Claude Flow Agent Coordination Protocol

Every Claude Flow Agent Spawned via Task Tool MUST:

1️⃣ BEFORE Work:

npx claude-flow@alpha hooks pre-task --description "[task]"
npx claude-flow@alpha hooks session-restore --session-id "swarm-[id]"

2️⃣ DURING Work:

npx claude-flow@alpha hooks post-edit --file "[file]" --memory-key "swarm/[agent]/[step]"
npx claude-flow@alpha hooks notify --message "[what was done]"

3️⃣ AFTER Work:

npx claude-flow@alpha hooks post-task --task-id "[task]"
npx claude-flow@alpha hooks session-end --export-metrics true

🎯 Claude Flow Concurrent Execution Examples

✅ Claude Flow CORRECT WORKFLOW: MCP Coordinates, Claude Code Executes

// Step 1: MCP tools set up coordination (optional, for complex tasks)
[Single Message - Coordination Setup]:
  mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 6 }
  mcp__claude-flow__agent_spawn { type: "researcher" }
  mcp__claude-flow__agent_spawn { type: "coder" }
  mcp__claude-flow__agent_spawn { type: "tester" }

// Step 2: Claude Code Task tool spawns ACTUAL agents that do the work
[Single Message - Parallel Agent Execution]:
  // Claude Code's Task tool spawns real agents concurrently
  Task("Research agent", "Analyze API requirements and best practices. Check memory for prior decisions.", "researcher")
  Task("Coder agent", "Implement REST endpoints with authentication. Coordinate via hooks.", "coder")
  Task("Database agent", "Design and implement database schema. Store decisions in memory.", "code-analyzer")
  Task("Tester agent", "Create comprehensive test suite with 90% coverage.", "tester")
  Task("Reviewer agent", "Review code quality and security. Document findings.", "reviewer")
  
  // Batch ALL todos in ONE call
  TodoWrite { todos: [
    {id: "1", content: "Research API patterns", status: "in_progress", priority: "high"},
    {id: "2", content: "Design database schema", status: "in_progress", priority: "high"},
    {id: "3", content: "Implement authentication", status: "pending", priority: "high"},
    {id: "4", content: "Build REST endpoints", status: "pending", priority: "high"},
    {id: "5", content: "Write unit tests", status: "pending", priority: "medium"},
    {id: "6", content: "Integration tests", status: "pending", priority: "medium"},
    {id: "7", content: "API documentation", status: "pending", priority: "low"},
    {id: "8", content: "Performance optimization", status: "pending", priority: "low"}
  ]}
  
  // Parallel file operations
  Bash "mkdir -p app/{src,tests,docs,config}"
  Write "app/package.json"
  Write "app/src/server.js"
  Write "app/tests/server.test.js"
  Write "app/docs/API.md"

❌ WRONG (Multiple Messages):

Message 1: mcp__claude-flow__swarm_init
Message 2: Task("agent 1")
Message 3: TodoWrite { todos: [single todo] }
Message 4: Write "file.js"
// This breaks parallel coordination!

Hooks Integration

Pre-Operation

  • Auto-assign agents by file type
  • Validate commands for safety
  • Prepare resources automatically
  • Optimize topology by complexity
  • Cache searches

Post-Operation

  • Auto-format code
  • Train neural patterns
  • Update memory
  • Analyze performance
  • Track token usage

Session Management

  • Generate summaries
  • Persist state
  • Track metrics
  • Restore context
  • Export workflows

📊 Visualization Dashboard

Agent activity is automatically visualized in real-time when services are running.

Starting the Visualization

# Terminal 1: Start backend services (WebSocket + REST API)
npx tsx scripts/start-visualization-services.ts

# Terminal 2: Start frontend dashboard
cd frontend && npm run dev

Then open http://localhost:3000 to view the dashboard.

Auto-Emit Events (Hook Integration)

Task agents automatically emit visualization events via Claude Code hooks:

  • PreToolUse hook: Emits agent:spawned and agent:started events when Task tool is invoked
  • PostToolUse hook: Emits agent:completed or agent:error events when Task completes

No manual action required - just use the Task tool and agents appear in the visualization!

Manual Event Emission

For custom workflows or debugging:

# Emit spawn event with agent type
npx tsx scripts/emit-agent-event.ts spawn <agentId> <agentType>

# Emit start event
npx tsx scripts/emit-agent-event.ts start <agentId>

# Emit completion event with duration (ms)
npx tsx scripts/emit-agent-event.ts complete <agentId> [duration]

# Emit error event
npx tsx scripts/emit-agent-event.ts error <agentId> "Error message"

Programmatic API

import { emitAgentSpawn, emitAgentComplete, emitAgentError } from './src/visualization';

// Emit events in your code
await emitAgentSpawn('my-agent', 'researcher');
await emitAgentComplete('my-agent', 5000);
await emitAgentError('my-agent', 'Something went wrong');

Event Types

Event Status When
agent:spawned idle Agent created
agent:started running Agent begins work
agent:completed completed Agent finishes
agent:error error Agent fails

Integration Tips

  1. Start with basic swarm init
  2. Scale agents gradually
  3. Use memory for context
  4. Monitor progress regularly
  5. Train patterns from success
  6. Enable hooks automation
  7. Use GitHub tools first

Support

Remember: Claude Flow coordinates, Claude Code creates!

important-instruction-reminders

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. Only create documentation files if explicitly requested by the User. Never save working files, text/mds and tests to the root folder.

Generated by: Agentic QE Fleet v2.3.0 Initialization Date: 2025-12-08T13:48:54.968Z Fleet Topology: hierarchical

  • We always implement all the code/tests, with proper implementation. We value the quality we deliver to our users.