name	sparc-methodology
description	SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) comprehensive development methodology with multi-agent orchestration
version	2.7.0
category	development
tags	["sparc","tdd","architecture","orchestration","methodology","multi-agent"]
author	Claude Flow

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.

Core Philosophy
Development Phases
Available Modes
Activation Methods
Orchestration Patterns
TDD Workflows
Best Practices
Integration Examples
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

Specification Before Code: Define requirements and constraints clearly
Design Before Implementation: Plan architecture and components
Tests Before Features: Write failing tests, then make them pass
Review Everything: Code quality, security, and performance checks
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:

Write failing test (RED)
Implement minimum code
Make test pass (GREEN)
Refactor for quality (REFACTOR)
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 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

# Execute specific mode
npx claude-flow sparc run <mode> "task description"

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

# List all available modes
npx claude-flow sparc modes

# Get help for specific mode
npx claude-flow sparc help <mode>

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

# Execute TDD workflow
npx claude-flow sparc tdd "feature description"

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

# Pipeline execution
npx 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 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

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

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

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

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

# 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

[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

// 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

// 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

# Step 1: Research and planning
npx claude-flow sparc run researcher "authentication patterns"

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

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

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

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

Workflow 2: Bug Investigation

# Step 1: Analyze issue
npx claude-flow sparc run analyzer "investigate bug #456"

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

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

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

Workflow 3: Performance Optimization

# Step 1: Profile performance
npx claude-flow sparc run analyzer "profile API response times"

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

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

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

Workflow 4: Complete Pipeline

# Execute full development pipeline
npx 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 workflows
mcp__claude-flow__neural_train {
  pattern_type: "coordination",
  training_data: "successful_tdd_workflow.json",
  epochs: 50
}

Cross-Session Memory

// 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

// 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

// 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

# List modes
npx claude-flow sparc modes

# Run specific mode
npx claude-flow sparc run <mode> "task"

# TDD workflow
npx claude-flow sparc tdd "feature"

# Full pipeline
npx claude-flow sparc pipeline "task"

# Batch execution
npx claude-flow sparc batch <modes> "task"

Most Common MCP Calls

// 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

name	sparc-methodology
description	SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) comprehensive development methodology with multi-agent orchestration
version	2.7.0
category	development
tags	["sparc","tdd","architecture","orchestration","methodology","multi-agent"]
author	Claude Flow