sparc-methodology

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.

1. [Core Philosophy](#core-philosophy)
2. [Development Phases](#development-phases)
3. [Available Modes](#available-modes)
4. [Activation Methods](#activation-methods)
5. [Orchestration Patterns](#orchestration-patterns)
6. [TDD Workflows](#tdd-workflows)
7. [Best Practices](#best-practices)
8. [Integration Examples](#integration-examples)
9. [Common Workflows](#common-workflows)

---

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

---

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

---

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

---

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: "",

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

```bash

# Execute specific mode

npx claude-flow sparc run "task description"

# Use alpha features

npx claude-flow@alpha sparc run "task description"

# List all available modes

npx claude-flow sparc modes

# Get help for specific mode

npx claude-flow sparc help

# Run with options

npx claude-flow sparc run "task" --parallel --monitor

# Execute TDD workflow

npx claude-flow sparc tdd "feature description"

# Batch execution

npx claude-flow sparc batch "task"

# Pipeline execution

npx claude-flow 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 "task description"

```

---

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

}

```

---

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 }

}

```

---

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

```

---

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"

}

```

---

Workflow 1: Feature Development

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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

```

---

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"

}

```

---

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

---

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

---

Most Common Commands

```bash

# List modes

npx claude-flow sparc modes

# Run specific mode

npx claude-flow sparc run "task"

# TDD workflow

npx claude-flow sparc tdd "feature"

# Full pipeline

npx claude-flow sparc pipeline "task"

# Batch execution

npx claude-flow sparc batch "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