Claude Code Configuration - SPARC Development Environment

🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT

ABSOLUTE RULES:

ALL operations MUST be concurrent/parallel in a single message
NEVER save working files, text/mds and tests to the root folder
ALWAYS organize files in appropriate subdirectories
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 Agent Execution

Claude Code's Task tool is the PRIMARY way to spawn 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")

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

Specification - Requirements analysis (sparc run spec-pseudocode)
Pseudocode - Algorithm design (sparc run spec-pseudocode)
Architecture - System design (sparc run architect)
Refinement - TDD implementation (sparc tdd)
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 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
claude mcp add flow-nexus npx flow-nexus@latest mcp start  # Optional: Cloud features

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

Flow-Nexus MCP Tools (Optional Advanced Features)

Flow-Nexus extends MCP capabilities with 70+ cloud-based orchestration tools:

Key MCP Tool Categories:

Swarm & Agents: swarm_init, swarm_scale, agent_spawn, task_orchestrate
Sandboxes: sandbox_create, sandbox_execute, sandbox_upload (cloud execution)
Templates: template_list, template_deploy (pre-built project templates)
Neural AI: neural_train, neural_patterns, seraphina_chat (AI assistant)
GitHub: github_repo_analyze, github_pr_manage (repository management)
Real-time: execution_stream_subscribe, realtime_subscribe (live monitoring)
Storage: storage_upload, storage_list (cloud file management)

Authentication Required:

Register: mcp__flow-nexus__user_register or npx flow-nexus@latest register
Login: mcp__flow-nexus__user_login or npx flow-nexus@latest login
Access 70+ specialized MCP tools for advanced orchestration

🚀 Agent Execution Flow with Claude Code

The Correct Pattern:

Optional: Use MCP tools to set up coordination topology
REQUIRED: Use Claude Code's Task tool to spawn agents that do actual work
REQUIRED: Each agent runs hooks for coordination
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"

📋 Agent Coordination Protocol

Every 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

🎯 Concurrent Execution Examples

✅ 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!

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

Start with basic swarm init
Scale agents gradually
Use memory for context
Monitor progress regularly
Train patterns from success
Enable hooks automation
Use GitHub tools first

Support

Documentation: https://github.com/ruvnet/claude-flow
Issues: https://github.com/ruvnet/claude-flow/issues
Flow-Nexus Platform: https://flow-nexus.ruv.io (registration required for cloud features)

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.

📋 Spec-Based Development (MANDATORY)

CRITICAL RULE: Always build to spec. No implementation changes unless outlined in specification documents.

Core Development Principles

These principles are NON-NEGOTIABLE and apply to ALL work:

SPEC-FIRST DEVELOPMENT
- Update or create specs FIRST in docs/specs/ before ANY implementation
- Specs are the single source of truth
- Never implement unspecified behavior
ADR FOR ARCHITECTURE
- Create/modify ADRs for architecturally significant changes
- ALWAYS follow ADR Implementation Spec
- Save ADRs to docs/adr/
- Reference ADR template: docs/adr/000-adr-template.md
DRY (Don't Repeat Yourself)
- Identify reusable patterns and abstractions
- Extract common logic into shared utilities
- If you write it twice, refactor it once
NO MOCKS - PRODUCTION READY CODE ONLY
- Write real, production-ready implementations
- No mock objects, fake data, or stub implementations
- If external dependencies are needed, use proper integration patterns
TDD (Test-Driven Development)
- Write tests FIRST, then implement
- Tests define the expected behavior
- All code must have corresponding tests
DOCUMENTATION UPDATES
- Review and update ALL relevant docs with every change:
  - README.md
  - User guide (docs/user-guide.md)
  - CLI spec (docs/specs/09-cli-interface-spec.md)
  - Any affected specification documents

Use /plan Mode for All Planning

MANDATORY: When any task requires planning (new features, refactors, multi-file changes, architectural decisions), you MUST use /plan mode. Do not skip planning and jump straight to implementation.

Specification-First Workflow

Before implementing ANY feature:
- Check if feature is defined in /docs/specs/
- If NOT defined → Create/update the spec first, then implement
- If defined → Implement exactly as specified

Specification Documents (in order of dependency):

Spec	Document	Purpose
01	Puzzle Engine	Sudoku generation, validation, rules
02	Memory System	AgentDB integration & persistence
03	GRASP Loop	Generate, Review, Absorb, Synthesize, Persist
04	Attention Mechanism	Focus and priority system
05	Dreaming Pipeline	5-phase consolidation
06	Benchmarking Framework	Performance testing
07	Integration Orchestration	System orchestration
08	AgentDB Integration	Native AgentDB features
09	CLI Interface	Command-line interface
10	Terminal UI	Interactive TUI with Ink
11	LLM Integration	AI model Sudoku player
12	Puzzle Generation	Seeded random puzzles
13	Profile Management	AI model connection profiles
14	Console Menu	TUI console & help system
15	Batch Testing	A/B testing & iterative learning scripts
16	AISP Mode	AI Sudoku Protocol validation
17	ADR Implementation	Architecture Decision Records
18	Algorithm Versioning	Versioned algorithm system
19	Failure Learning	Learning from failures

When specs conflict with implementation ideas:
- Specs are authoritative
- Propose spec updates if needed
- Never implement unspecified behavior
Verification Checklist (before any PR):
- All new types defined in specs
- All event types registered in Spec 07
- All CLI commands match Spec 09
- All TUI screens match Spec 10
- Tests verify spec compliance
- ADR created for architectural changes (per Spec 17)
- Documentation updated (README, user guide, CLI spec)
- No mock implementations - production code only

Why Spec-Based Development?

Consistency: All components follow the same contracts
Traceability: Every feature maps to a specification
Reviewability: Changes are validated against specs
Maintainability: Specs serve as living documentation
Quality: TDD + no mocks = production-ready from day one

FilesExpand file tree

CLAUDE.md

Latest commit

History