SPARC Methodology - Comprehensive Development Framework

Overview

SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) is a systematic development methodology integrated with Claude Flow's multi-agent orchestration capabilities. It provides 17 specialized modes for comprehensive software development, from initial research through deployment and monitoring.

Table of Contents

1. Core Philosophy
2. Development Phases
3. Available Modes
4. Activation Methods
5. Orchestration Patterns
6. TDD Workflows
7. Best Practices
8. Integration Examples
9. Common Workflows

Core Philosophy

SPARC methodology emphasizes:

• Systematic Approach: Structured phases from specification to completion
• Test-Driven Development: Tests written before implementation
• Parallel Execution: Concurrent agent coordination for 2.8-4.4x speed improvements
• Memory Integration: Persistent knowledge sharing across agents and sessions
• Quality First: Comprehensive reviews, testing, and validation
• Modular Design: Clean separation of concerns with clear interfaces

Key Principles

1. Specification Before Code: Define requirements and constraints clearly
2. Design Before Implementation: Plan architecture and components
3. Tests Before Features: Write failing tests, then make them pass
4. Review Everything: Code quality, security, and performance checks
5. Document Continuously: Maintain current documentation throughout

Development Phases

Phase 1: Specification

Goal: Define requirements, constraints, and success criteria

• Requirements analysis
• User story mapping
• Constraint identification
• Success metrics definition
• Pseudocode planning

Key Modes: researcher, analyzer, memory-manager

Phase 2: Architecture

Goal: Design system structure and component interfaces

• System architecture design
• Component interface definition
• Database schema planning
• API contract specification
• Infrastructure planning

Key Modes: architect, designer, orchestrator

Phase 3: Refinement (TDD Implementation)

Goal: Implement features with test-first approach

• Write failing tests
• Implement minimum viable code
• Make tests pass
• Refactor for quality
• Iterate until complete

Key Modes: tdd, coder, tester

Phase 4: Review

Goal: Ensure code quality, security, and performance

• Code quality assessment
• Security vulnerability scanning
• Performance profiling
• Best practices validation
• Documentation review

Key Modes: reviewer, optimizer, debugger

Phase 5: Completion

Goal: Integration, deployment, and monitoring

• System integration
• Deployment automation
• Monitoring setup
• Documentation finalization
• Knowledge capture

Key Modes: workflow-manager, documenter, memory-manager

Available Modes

Core Orchestration Modes

orchestrator

Multi-agent task orchestration with TodoWrite/Task/Memory coordination.

Capabilities:

• Task decomposition into manageable units
• Agent coordination and resource allocation
• Progress tracking and result synthesis
• Adaptive strategy selection
• Cross-agent communication

Usage:

javascript
mcp__claude-flow__sparc_mode {
  mode: "orchestrator",
  task_description: "coordinate feature development",
  options: { parallel: true, monitor: true }
}

swarm-coordinator

Specialized swarm management for complex multi-agent workflows.

Capabilities:

• Topology optimization (mesh, hierarchical, ring, star)
• Agent lifecycle management
• Dynamic scaling based on workload
• Fault tolerance and recovery
• Performance monitoring

workflow-manager

Process automation and workflow orchestration.

Capabilities:

• Workflow definition and execution
• Event-driven triggers
• Sequential and parallel pipelines
• State management
• Error handling and retry logic

batch-executor

Parallel task execution for high-throughput operations.

Capabilities:

• Concurrent file operations
• Batch processing optimization
• Resource pooling
• Load balancing
• Progress aggregation

Development Modes

coder

Autonomous code generation with batch file operations.

Capabilities:

• Feature implementation
• Code refactoring
• Bug fixes and patches
• API development
• Algorithm implementation

Quality Standards:

• ES2022+ standards
• TypeScript type safety
• Comprehensive error handling
• Performance optimization
• Security best practices

Usage:

javascript
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement user authentication with JWT",
  options: {
    test_driven: true,
    parallel_edits: true,
    typescript: true
  }
}

architect

System design with Memory-based coordination.

Capabilities:

• Microservices architecture
• Event-driven design
• Domain-driven design (DDD)
• Hexagonal architecture
• CQRS and Event Sourcing

Memory Integration:

• Store architectural decisions
• Share component specifications
• Maintain design consistency
• Track architectural evolution

Design Patterns:

• Layered architecture
• Microservices patterns
• Event-driven patterns
• Domain modeling
• Infrastructure as Code

Usage:

javascript
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design scalable e-commerce platform",
  options: {
    detailed: true,
    memory_enabled: true,
    patterns: ["microservices", "event-driven"]
  }
}

tdd

Test-driven development with comprehensive testing.

Capabilities:

• Test-first development
• Red-green-refactor cycle
• Test suite design
• Coverage optimization (target: 90%+)
• Continuous testing

TDD Workflow:

1. Write failing test (RED)
2. Implement minimum code
3. Make test pass (GREEN)
4. Refactor for quality (REFACTOR)
5. Repeat cycle

Testing Strategies:

• Unit testing (Jest, Mocha, Vitest)
• Integration testing
• End-to-end testing (Playwright, Cypress)
• Performance testing
• Security testing

Usage:

javascript
mcp__claude-flow__sparc_mode {
  mode: "tdd",
  task_description: "shopping cart feature with payment integration",
  options: {
    coverage_target: 90,
    test_framework: "jest",
    e2e_framework: "playwright"
  }
}

reviewer

Code review using batch file analysis.

Capabilities:

• Code quality assessment
• Security vulnerability detection
• Performance analysis
• Best practices validation
• Documentation review

Review Criteria:

• Code correctness and logic
• Design pattern adherence
• Comprehensive error handling
• Test coverage adequacy
• Maintainability and readability
• Security vulnerabilities
• Performance bottlenecks

Batch Analysis:

• Parallel file review
• Pattern detection
• Dependency checking
• Consistency validation
• Automated reporting

Usage:

javascript
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "review authentication module PR #123",
  options: {
    security_check: true,
    performance_check: true,
    test_coverage_check: true
  }
}

Analysis and Research Modes

researcher

Deep research with parallel WebSearch/WebFetch and Memory coordination.

Capabilities:

• Comprehensive information gathering
• Source credibility evaluation
• Trend analysis and forecasting
• Competitive research
• Technology assessment

Research Methods:

• Parallel web searches
• Academic paper analysis
• Industry report synthesis
• Expert opinion gathering
• Statistical data compilation

Memory Integration:

• Store research findings with citations
• Build knowledge graphs
• Track information sources
• Cross-reference insights
• Maintain research history

Usage:

javascript
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research microservices best practices 2024",
  options: {
    depth: "comprehensive",
    sources: ["academic", "industry", "news"],
    citations: true
  }
}

analyzer

Code and data analysis with pattern recognition.

Capabilities:

• Static code analysis
• Dependency analysis
• Performance profiling
• Security scanning
• Data pattern recognition

optimizer

Performance optimization and bottleneck resolution.

Capabilities:

• Algorithm optimization
• Database query tuning
• Caching strategy design
• Bundle size reduction
• Memory leak detection

Creative and Support Modes

designer

UI/UX design with accessibility focus.

Capabilities:

• Interface design
• User experience optimization
• Accessibility compliance (WCAG 2.1)
• Design system creation
• Responsive layout design

innovator

Creative problem-solving and novel solutions.

Capabilities:

• Brainstorming and ideation
• Alternative approach generation
• Technology evaluation
• Proof of concept development
• Innovation feasibility analysis

documenter

Comprehensive documentation generation.

Capabilities:

• API documentation (OpenAPI/Swagger)
• Architecture diagrams
• User guides and tutorials
• Code comments and JSDoc
• README and changelog maintenance

debugger

Systematic debugging and issue resolution.

Capabilities:

• Bug reproduction
• Root cause analysis
• Fix implementation
• Regression prevention
• Debug logging optimization

tester

Comprehensive testing beyond TDD.

Capabilities:

• Test suite expansion
• Edge case identification
• Performance testing
• Load testing
• Chaos engineering

memory-manager

Knowledge management and context preservation.

Capabilities:

• Cross-session memory persistence
• Knowledge graph construction
• Context restoration
• Learning pattern extraction
• Decision tracking

Activation Methods

Method 1: MCP Tools (Preferred in Claude Code)

Best for: Integrated Claude Code workflows with full orchestration capabilities

javascript
// Basic mode execution
mcp__claude-flow__sparc_mode {
  mode: "<mode-name>",
  task_description: "<task description>",
  options: {
    // mode-specific options
  }
}

// Initialize swarm for complex tasks
mcp__claude-flow__swarm_init {
  topology: "hierarchical",  // or "mesh", "ring", "star"
  strategy: "auto",           // or "balanced", "specialized", "adaptive"
  maxAgents: 8
}

// Spawn specialized agents
mcp__claude-flow__agent_spawn {
  type: "<agent-type>",
  capabilities: ["<capability1>", "<capability2>"]
}

// Monitor execution
mcp__claude-flow__swarm_monitor {
  swarmId: "current",
  interval: 5000
}

Method 2: NPX CLI (Fallback)

Best for: Terminal usage or when MCP tools unavailable

bash
# Execute specific mode
npx @claude-flow/cli@latest sparc run <mode> "task description"

# Use alpha features
npx claude-flow@alpha sparc run <mode> "task description"

# List all available modes
npx @claude-flow/cli@latest sparc modes

# Get help for specific mode
npx @claude-flow/cli@latest sparc help <mode>

# Run with options
npx @claude-flow/cli@latest sparc run <mode> "task" --parallel --monitor

# Execute TDD workflow
npx @claude-flow/cli@latest sparc tdd "feature description"

# Batch execution
npx @claude-flow/cli@latest sparc batch <mode1,mode2,mode3> "task"

# Pipeline execution
npx @claude-flow/cli@latest sparc pipeline "task description"

Method 3: Local Installation

Best for: Projects with local claude-flow installation

bash
# If claude-flow is installed locally
./claude-flow sparc run <mode> "task description"

Orchestration Patterns

Pattern 1: Hierarchical Coordination

Best for: Complex projects with clear delegation hierarchy

javascript
// Initialize hierarchical swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 12
}

// Spawn coordinator
mcp__claude-flow__agent_spawn {
  type: "coordinator",
  capabilities: ["planning", "delegation", "monitoring"]
}

// Spawn specialized workers
mcp__claude-flow__agent_spawn { type: "architect" }
mcp__claude-flow__agent_spawn { type: "coder" }
mcp__claude-flow__agent_spawn { type: "tester" }
mcp__claude-flow__agent_spawn { type: "reviewer" }

Pattern 2: Mesh Coordination

Best for: Collaborative tasks requiring peer-to-peer communication

javascript
mcp__claude-flow__swarm_init {
  topology: "mesh",
  strategy: "balanced",
  maxAgents: 6
}

Pattern 3: Sequential Pipeline

Best for: Ordered workflow execution (spec → design → code → test → review)

javascript
mcp__claude-flow__workflow_create {
  name: "development-pipeline",
  steps: [
    { mode: "researcher", task: "gather requirements" },
    { mode: "architect", task: "design system" },
    { mode: "coder", task: "implement features" },
    { mode: "tdd", task: "create tests" },
    { mode: "reviewer", task: "review code" }
  ],
  triggers: ["on_step_complete"]
}

Pattern 4: Parallel Execution

Best for: Independent tasks that can run concurrently

javascript
mcp__claude-flow__task_orchestrate {
  task: "build full-stack application",
  strategy: "parallel",
  dependencies: {
    backend: [],
    frontend: [],
    database: [],
    tests: ["backend", "frontend"]
  }
}

Pattern 5: Adaptive Strategy

Best for: Dynamic workloads with changing requirements

javascript
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  strategy: "adaptive",  // Auto-adjusts based on workload
  maxAgents: 20
}

TDD Workflows

Complete TDD Workflow

javascript
// Step 1: Initialize TDD swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 8
}

// Step 2: Research and planning
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research testing best practices for feature X"
}

// Step 3: Architecture design
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design testable architecture for feature X"
}

// Step 4: TDD implementation
mcp__claude-flow__sparc_mode {
  mode: "tdd",
  task_description: "implement feature X with 90% coverage",
  options: {
    coverage_target: 90,
    test_framework: "jest",
    parallel_tests: true
  }
}

// Step 5: Code review
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "review feature X implementation",
  options: {
    test_coverage_check: true,
    security_check: true
  }
}

// Step 6: Optimization
mcp__claude-flow__sparc_mode {
  mode: "optimizer",
  task_description: "optimize feature X performance"
}

Red-Green-Refactor Cycle

javascript
// RED: Write failing test
mcp__claude-flow__sparc_mode {
  mode: "tester",
  task_description: "create failing test for shopping cart add item",
  options: { expect_failure: true }
}

// GREEN: Minimal implementation
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement minimal code to pass test",
  options: { minimal: true }
}

// REFACTOR: Improve code quality
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "refactor shopping cart implementation",
  options: { maintain_tests: true }
}

Best Practices

1. Memory Integration

Always use Memory for cross-agent coordination:

javascript
// Store architectural decisions
mcp__claude-flow__memory_usage {
  action: "store",
  namespace: "architecture",
  key: "api-design-v1",
  value: JSON.stringify(apiDesign),
  ttl: 86400000  // 24 hours
}

// Retrieve in subsequent agents
mcp__claude-flow__memory_usage {
  action: "retrieve",
  namespace: "architecture",
  key: "api-design-v1"
}

2. Parallel Operations

Batch all related operations in single message:

javascript
// ✅ CORRECT: All operations together
[Single Message]:
  mcp__claude-flow__agent_spawn { type: "researcher" }
  mcp__claude-flow__agent_spawn { type: "coder" }
  mcp__claude-flow__agent_spawn { type: "tester" }
  TodoWrite { todos: [8-10 todos] }

// ❌ WRONG: Multiple messages
Message 1: mcp__claude-flow__agent_spawn { type: "researcher" }
Message 2: mcp__claude-flow__agent_spawn { type: "coder" }
Message 3: TodoWrite { todos: [...] }

3. Hook Integration

Every SPARC mode should use hooks:

bash
# Before work
npx claude-flow@alpha hooks pre-task --description "implement auth"

# During work
npx claude-flow@alpha hooks post-edit --file "auth.js"

# After work
npx claude-flow@alpha hooks post-task --task-id "task-123"

4. Test Coverage

Maintain minimum 90% coverage:

• Unit tests for all functions
• Integration tests for APIs
• E2E tests for critical flows
• Edge case coverage
• Error path testing

5. Documentation

Document as you build:

• API documentation (OpenAPI)
• Architecture decision records (ADR)
• Code comments for complex logic
• README with setup instructions
• Changelog for version tracking

6. File Organization

Never save to root folder:

project/
├── src/           # Source code
├── tests/         # Test files
├── docs/          # Documentation
├── config/        # Configuration
├── scripts/       # Utility scripts
└── examples/      # Example code

Integration Examples

Example 1: Full-Stack Development

javascript
[Single Message - Parallel Agent Execution]:

// Initialize swarm
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 10
}

// Architecture phase
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design REST API with authentication",
  options: { memory_enabled: true }
}

// Research phase
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research authentication best practices"
}

// Implementation phase
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement Express API with JWT auth",
  options: { test_driven: true }
}

// Testing phase
mcp__claude-flow__sparc_mode {
  mode: "tdd",
  task_description: "comprehensive API tests",
  options: { coverage_target: 90 }
}

// Review phase
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "security and performance review",
  options: { security_check: true }
}

// Batch todos
TodoWrite {
  todos: [
    {content: "Design API schema", status: "completed"},
    {content: "Research JWT implementation", status: "completed"},
    {content: "Implement authentication", status: "in_progress"},
    {content: "Write API tests", status: "pending"},
    {content: "Security review", status: "pending"},
    {content: "Performance optimization", status: "pending"},
    {content: "API documentation", status: "pending"},
    {content: "Deployment setup", status: "pending"}
  ]
}

Example 2: Research-Driven Innovation

javascript
// Research phase
mcp__claude-flow__sparc_mode {
  mode: "researcher",
  task_description: "research AI-powered search implementations",
  options: {
    depth: "comprehensive",
    sources: ["academic", "industry"]
  }
}

// Innovation phase
mcp__claude-flow__sparc_mode {
  mode: "innovator",
  task_description: "propose novel search algorithm",
  options: { memory_enabled: true }
}

// Architecture phase
mcp__claude-flow__sparc_mode {
  mode: "architect",
  task_description: "design scalable search system"
}

// Implementation phase
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "implement search algorithm",
  options: { test_driven: true }
}

// Documentation phase
mcp__claude-flow__sparc_mode {
  mode: "documenter",
  task_description: "document search system architecture and API"
}

Example 3: Legacy Code Refactoring

javascript
// Analysis phase
mcp__claude-flow__sparc_mode {
  mode: "analyzer",
  task_description: "analyze legacy codebase dependencies"
}

// Planning phase
mcp__claude-flow__sparc_mode {
  mode: "orchestrator",
  task_description: "plan incremental refactoring strategy"
}

// Testing phase (create safety net)
mcp__claude-flow__sparc_mode {
  mode: "tester",
  task_description: "create comprehensive test suite for legacy code",
  options: { coverage_target: 80 }
}

// Refactoring phase
mcp__claude-flow__sparc_mode {
  mode: "coder",
  task_description: "refactor module X with modern patterns",
  options: { maintain_tests: true }
}

// Review phase
mcp__claude-flow__sparc_mode {
  mode: "reviewer",
  task_description: "validate refactoring maintains functionality"
}

Common Workflows

Workflow 1: Feature Development

bash
# Step 1: Research and planning
npx @claude-flow/cli@latest sparc run researcher "authentication patterns"

# Step 2: Architecture design
npx @claude-flow/cli@latest sparc run architect "design auth system"

# Step 3: TDD implementation
npx @claude-flow/cli@latest sparc tdd "user authentication feature"

# Step 4: Code review
npx @claude-flow/cli@latest sparc run reviewer "review auth implementation"

# Step 5: Documentation
npx @claude-flow/cli@latest sparc run documenter "document auth API"

Workflow 2: Bug Investigation

bash
# Step 1: Analyze issue
npx @claude-flow/cli@latest sparc run analyzer "investigate bug #456"

# Step 2: Debug systematically
npx @claude-flow/cli@latest sparc run debugger "fix memory leak in service X"

# Step 3: Create tests
npx @claude-flow/cli@latest sparc run tester "regression tests for bug #456"

# Step 4: Review fix
npx @claude-flow/cli@latest sparc run reviewer "validate bug fix"

Workflow 3: Performance Optimization

bash
# Step 1: Profile performance
npx @claude-flow/cli@latest sparc run analyzer "profile API response times"

# Step 2: Identify bottlenecks
npx @claude-flow/cli@latest sparc run optimizer "optimize database queries"

# Step 3: Implement improvements
npx @claude-flow/cli@latest sparc run coder "implement caching layer"

# Step 4: Benchmark results
npx @claude-flow/cli@latest sparc run tester "performance benchmarks"

Workflow 4: Complete Pipeline

bash
# Execute full development pipeline
npx @claude-flow/cli@latest sparc pipeline "e-commerce checkout feature"

# This automatically runs:
# 1. researcher - Gather requirements
# 2. architect - Design system
# 3. coder - Implement features
# 4. tdd - Create comprehensive tests
# 5. reviewer - Code quality review
# 6. optimizer - Performance tuning
# 7. documenter - Documentation

Advanced Features

Neural Pattern Training

javascript
// Train patterns from successful workflows
mcp__claude-flow__neural_train {
  pattern_type: "coordination",
  training_data: "successful_tdd_workflow.json",
  epochs: 50
}

Cross-Session Memory

javascript
// Save session state
mcp__claude-flow__memory_persist {
  sessionId: "feature-auth-v1"
}

// Restore in new session
mcp__claude-flow__context_restore {
  snapshotId: "feature-auth-v1"
}

GitHub Integration

javascript
// Analyze repository
mcp__claude-flow__github_repo_analyze {
  repo: "owner/repo",
  analysis_type: "code_quality"
}

// Manage pull requests
mcp__claude-flow__github_pr_manage {
  repo: "owner/repo",
  pr_number: 123,
  action: "review"
}

Performance Monitoring

javascript
// Real-time swarm monitoring
mcp__claude-flow__swarm_monitor {
  swarmId: "current",
  interval: 5000
}

// Bottleneck analysis
mcp__claude-flow__bottleneck_analyze {
  component: "api-layer",
  metrics: ["latency", "throughput", "errors"]
}

// Token usage tracking
mcp__claude-flow__token_usage {
  operation: "feature-development",
  timeframe: "24h"
}

Performance Benefits

Proven Results:

• 84.8% SWE-Bench solve rate
• 32.3% token reduction through optimizations
• 2.8-4.4x speed improvement with parallel execution
• 27+ neural models for pattern learning
• 90%+ test coverage standard

Support and Resources

• Documentation: https://github.com/ruvnet/claude-flow
• Issues: https://github.com/ruvnet/claude-flow/issues
• NPM Package: https://www.npmjs.com/package/claude-flow
• Community: Discord server (link in repository)

Quick Reference

Most Common Commands

bash
# List modes
npx @claude-flow/cli@latest sparc modes

# Run specific mode
npx @claude-flow/cli@latest sparc run <mode> "task"

# TDD workflow
npx @claude-flow/cli@latest sparc tdd "feature"

# Full pipeline
npx @claude-flow/cli@latest sparc pipeline "task"

# Batch execution
npx @claude-flow/cli@latest sparc batch <modes> "task"

Most Common MCP Calls

javascript
// Initialize swarm
mcp__claude-flow__swarm_init { topology: "hierarchical" }

// Execute mode
mcp__claude-flow__sparc_mode { mode: "coder", task_description: "..." }

// Monitor progress
mcp__claude-flow__swarm_monitor { interval: 5000 }

// Store in memory
mcp__claude-flow__memory_usage { action: "store", key: "...", value: "..." }

Remember: SPARC = Systematic, Parallel, Agile, Refined, Complete