Sparc Methodology

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:

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:

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:

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:

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:

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:

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

// Basic mode executionmcp__claude-flow__sparc_mode {  mode: "<mode-name>",  task_description: "<task description>",  options: {    // mode-specific options  }}
// Initialize swarm for complex tasksmcp__claude-flow__swarm_init {  topology: "hierarchical",  // or "mesh", "ring", "star"  strategy: "auto",           // or "balanced", "specialized", "adaptive"  maxAgents: 8}
// Spawn specialized agentsmcp__claude-flow__agent_spawn {  type: "<agent-type>",  capabilities: ["<capability1>", "<capability2>"]}
// Monitor executionmcp__claude-flow__swarm_monitor {  swarmId: "current",  interval: 5000}

Method 2: NPX CLI (Fallback)

Best for: Terminal usage or when MCP tools unavailable

# Execute specific modenpx claude-flow sparc run <mode> "task description"
# Use alpha featuresnpx claude-flow@alpha sparc run <mode> "task description"
# List all available modesnpx claude-flow sparc modes
# Get help for specific modenpx claude-flow sparc help <mode>
# Run with optionsnpx claude-flow sparc run <mode> "task" --parallel --monitor
# Execute TDD workflownpx claude-flow sparc tdd "feature description"
# Batch executionnpx claude-flow sparc batch <mode1,mode2,mode3> "task"
# Pipeline executionnpx claude-flow sparc pipeline "task description"

Method 3: Local Installation

Best for: Projects with local claude-flow installation

# 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

// Initialize hierarchical swarmmcp__claude-flow__swarm_init {  topology: "hierarchical",  maxAgents: 12}
// Spawn coordinatormcp__claude-flow__agent_spawn {  type: "coordinator",  capabilities: ["planning", "delegation", "monitoring"]}
// Spawn specialized workersmcp__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

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)

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

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

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

TDD Workflows

Complete TDD Workflow

// Step 1: Initialize TDD swarmmcp__claude-flow__swarm_init {  topology: "hierarchical",  maxAgents: 8}
// Step 2: Research and planningmcp__claude-flow__sparc_mode {  mode: "researcher",  task_description: "research testing best practices for feature X"}
// Step 3: Architecture designmcp__claude-flow__sparc_mode {  mode: "architect",  task_description: "design testable architecture for feature X"}
// Step 4: TDD implementationmcp__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 reviewmcp__claude-flow__sparc_mode {  mode: "reviewer",  task_description: "review feature X implementation",  options: {    test_coverage_check: true,    security_check: true  }}
// Step 6: Optimizationmcp__claude-flow__sparc_mode {  mode: "optimizer",  task_description: "optimize feature X performance"}

Red-Green-Refactor Cycle

// RED: Write failing testmcp__claude-flow__sparc_mode {  mode: "tester",  task_description: "create failing test for shopping cart add item",  options: { expect_failure: true }}
// GREEN: Minimal implementationmcp__claude-flow__sparc_mode {  mode: "coder",  task_description: "implement minimal code to pass test",  options: { minimal: true }}
// REFACTOR: Improve code qualitymcp__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:

// Store architectural decisionsmcp__claude-flow__memory_usage {  action: "store",  namespace: "architecture",  key: "api-design-v1",  value: JSON.stringify(apiDesign),  ttl: 86400000  // 24 hours}
// Retrieve in subsequent agentsmcp__claude-flow__memory_usage {  action: "retrieve",  namespace: "architecture",  key: "api-design-v1"}

2. Parallel Operations

Batch all related operations in single message:

// ✅ 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 messagesMessage 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:

# Before worknpx claude-flow@alpha hooks pre-task --description "implement auth"
# During worknpx claude-flow@alpha hooks post-edit --file "auth.js"
# After worknpx 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

[Single Message - Parallel Agent Execution]:
// Initialize swarmmcp__claude-flow__swarm_init {  topology: "hierarchical",  maxAgents: 10}
// Architecture phasemcp__claude-flow__sparc_mode {  mode: "architect",  task_description: "design REST API with authentication",  options: { memory_enabled: true }}
// Research phasemcp__claude-flow__sparc_mode {  mode: "researcher",  task_description: "research authentication best practices"}
// Implementation phasemcp__claude-flow__sparc_mode {  mode: "coder",  task_description: "implement Express API with JWT auth",  options: { test_driven: true }}
// Testing phasemcp__claude-flow__sparc_mode {  mode: "tdd",  task_description: "comprehensive API tests",  options: { coverage_target: 90 }}
// Review phasemcp__claude-flow__sparc_mode {  mode: "reviewer",  task_description: "security and performance review",  options: { security_check: true }}
// Batch todosTodoWrite {  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

// Research phasemcp__claude-flow__sparc_mode {  mode: "researcher",  task_description: "research AI-powered search implementations",  options: {    depth: "comprehensive",    sources: ["academic", "industry"]  }}
// Innovation phasemcp__claude-flow__sparc_mode {  mode: "innovator",  task_description: "propose novel search algorithm",  options: { memory_enabled: true }}
// Architecture phasemcp__claude-flow__sparc_mode {  mode: "architect",  task_description: "design scalable search system"}
// Implementation phasemcp__claude-flow__sparc_mode {  mode: "coder",  task_description: "implement search algorithm",  options: { test_driven: true }}
// Documentation phasemcp__claude-flow__sparc_mode {  mode: "documenter",  task_description: "document search system architecture and API"}

Example 3: Legacy Code Refactoring

// Analysis phasemcp__claude-flow__sparc_mode {  mode: "analyzer",  task_description: "analyze legacy codebase dependencies"}
// Planning phasemcp__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 phasemcp__claude-flow__sparc_mode {  mode: "coder",  task_description: "refactor module X with modern patterns",  options: { maintain_tests: true }}
// Review phasemcp__claude-flow__sparc_mode {  mode: "reviewer",  task_description: "validate refactoring maintains functionality"}

Common Workflows

Workflow 1: Feature Development

# Step 1: Research and planningnpx claude-flow sparc run researcher "authentication patterns"
# Step 2: Architecture designnpx claude-flow sparc run architect "design auth system"
# Step 3: TDD implementationnpx claude-flow sparc tdd "user authentication feature"
# Step 4: Code reviewnpx claude-flow sparc run reviewer "review auth implementation"
# Step 5: Documentationnpx claude-flow sparc run documenter "document auth API"

Workflow 2: Bug Investigation

# Step 1: Analyze issuenpx claude-flow sparc run analyzer "investigate bug #456"
# Step 2: Debug systematicallynpx claude-flow sparc run debugger "fix memory leak in service X"
# Step 3: Create testsnpx claude-flow sparc run tester "regression tests for bug #456"
# Step 4: Review fixnpx claude-flow sparc run reviewer "validate bug fix"

Workflow 3: Performance Optimization

# Step 1: Profile performancenpx claude-flow sparc run analyzer "profile API response times"
# Step 2: Identify bottlenecksnpx claude-flow sparc run optimizer "optimize database queries"
# Step 3: Implement improvementsnpx claude-flow sparc run coder "implement caching layer"
# Step 4: Benchmark resultsnpx claude-flow sparc run tester "performance benchmarks"

Workflow 4: Complete Pipeline

# Execute full development pipelinenpx claude-flow 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

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

Cross-Session Memory

// Save session statemcp__claude-flow__memory_persist {  sessionId: "feature-auth-v1"}
// Restore in new sessionmcp__claude-flow__context_restore {  snapshotId: "feature-auth-v1"}

GitHub Integration

// Analyze repositorymcp__claude-flow__github_repo_analyze {  repo: "owner/repo",  analysis_type: "code_quality"}
// Manage pull requestsmcp__claude-flow__github_pr_manage {  repo: "owner/repo",  pr_number: 123,  action: "review"}

Performance Monitoring

// Real-time swarm monitoringmcp__claude-flow__swarm_monitor {  swarmId: "current",  interval: 5000}
// Bottleneck analysismcp__claude-flow__bottleneck_analyze {  component: "api-layer",  metrics: ["latency", "throughput", "errors"]}
// Token usage trackingmcp__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

# List modesnpx claude-flow sparc modes
# Run specific modenpx claude-flow sparc run <mode> "task"
# TDD workflownpx claude-flow sparc tdd "feature"
# Full pipelinenpx claude-flow sparc pipeline "task"
# Batch executionnpx claude-flow sparc batch <modes> "task"

Most Common MCP Calls

// Initialize swarmmcp__claude-flow__swarm_init { topology: "hierarchical" }
// Execute modemcp__claude-flow__sparc_mode { mode: "coder", task_description: "..." }
// Monitor progressmcp__claude-flow__swarm_monitor { interval: 5000 }
// Store in memorymcp__claude-flow__memory_usage { action: "store", key: "...", value: "..." }

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