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

• 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