SPARC Methodology - Comprehensive Development Framework

Overview

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

In agent-studio:

When the

mcp__claude-flow__*

or

npx claude-flow

examples below are not available, use the Task tool to spawn agents (e.g. planner, developer, qa, architect) and follow the workflows in

.claude/workflows/

and router-decision.md instead.

Table of Contents

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

:

""

,

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

:

""

,

capabilities

:

[

""

,

""

]

}

// 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,mode 3

"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" } TaskCreate { tasks : [ 8 - 10 tasks ] } // ❌ WRONG: Multiple messages Message 1 : mcp__claude - flow__agent_spawn { type : "researcher" } Message 2 : mcp__claude - flow__agent_spawn { type : "coder" } Message 3 : TaskCreate { tasks : [ ... ] } 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 task creation TaskCreate { tasks : [ { 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 : "..." } Iron Laws NEVER write implementation code before completing the Specification phase ALWAYS write failing tests before any implementation in the Refinement phase NEVER advance to the next SPARC phase without completing all review gates of the current phase ALWAYS decompose complex tasks into subtasks with explicit dependencies before spawning agents NEVER claim phase completion without documented evidence of passing quality gates Anti-Patterns Anti-Pattern Why It Fails Correct Approach Skipping Specification phase Implementation targets wrong requirements Define requirements, user stories, and constraints before any code Implementing before tests No way to verify correctness; regressions slip through Write failing tests in Refinement before writing any feature code Phase-skipping under time pressure Quality gates missed; downstream phases fail Complete all review gates before advancing; gates exist for good reasons Spawning agents without dependency mapping Agents block each other or duplicate work Map task dependencies and parallel groups before spawning agents Marking phases complete without evidence Incomplete work propagates to later phases Require explicit gate evidence (test results, review sign-off) per phase Memory Protocol (MANDATORY) Before starting: Read .claude/context/memory/learnings.md After completing: New pattern -> .claude/context/memory/learnings.md Issue found -> .claude/context/memory/issues.md Decision made -> .claude/context/memory/decisions.md ASSUME INTERRUPTION: If it's not in memory, it didn't happen. Remember: SPARC = Systematic, Parallel, Agile, Refined, Complete