Skip to content

AGENTS.md

Latest commit

 

History

History
executable file
·
265 lines (202 loc) · 7.8 KB

AGENTS.md

File metadata and controls

executable file
·
265 lines (202 loc) · 7.8 KB
Raw

Claude Code Configuration - SPARC Development Environment

🚨 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

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

MANDATORY PATTERNS:

  • TodoWrite: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
  • Task tool: 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

📁 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

🚀 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

Testing & Validation

tdd-london-swarm, production-validator

Migration & Planning

migration-planner, swarm-init

🎯 Claude Code vs MCP Tools

Claude Code Handles ALL:

  • 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:

  • Coordination and planning
  • Memory management
  • Neural features
  • Performance tracking
  • Swarm orchestration
  • GitHub integration

KEY: MCP coordinates, Claude Code executes.

🚀 Quick Setup

# Add Claude Flow MCP server
claude mcp add claude-flow npx claude-flow@alpha mcp start

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 Coordination Protocol

Every Agent 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

🎯 Concurrent Execution Examples

✅ CORRECT (Single Message):

[BatchTool]:
  // Initialize swarm
  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" }
  
  // Spawn agents with Task tool
  Task("Research agent: Analyze requirements...")
  Task("Coder agent: Implement features...")
  Task("Tester agent: Create test suite...")
  
  // Batch todos
  TodoWrite { todos: [
    {id: "1", content: "Research", status: "in_progress", priority: "high"},
    {id: "2", content: "Design", status: "pending", priority: "high"},
    {id: "3", content: "Implement", status: "pending", priority: "high"},
    {id: "4", content: "Test", status: "pending", priority: "medium"},
    {id: "5", content: "Document", status: "pending", priority: "low"}
  ]}
  
  // File operations
  Bash "mkdir -p app/{src,tests,docs}"
  Write "app/src/index.js"
  Write "app/tests/index.test.js"
  Write "app/docs/README.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!

Performance Benefits

  • 84.8% SWE-Bench solve rate
  • 32.3% token reduction
  • 2.8-4.4x speed improvement
  • 27+ neural models

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

Advanced Features (v2.0.0)

  • 🚀 Automatic Topology Selection
  • ⚡ Parallel Execution (2.8-4.4x speed)
  • 🧠 Neural Training
  • 📊 Bottleneck Analysis
  • 🤖 Smart Auto-Spawning
  • 🛡️ Self-Healing Workflows
  • 💾 Cross-Session Memory
  • 🔗 GitHub Integration

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!