sparc-methodology

name	sparc-methodology
description	SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) comprehensive development methodology with multi-agent orchestration

SPARC Methodology - Comprehensive Development Framework

Overview

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

Table of Contents

1. Core Philosophy
2. Development Phases
3. Available Modes
4. Activation Methods
5. Orchestration Patterns
6. TDD Workflows
7. Best Practices
8. Integration Examples
9. Common Workflows

---

Core Philosophy

SPARC methodology emphasizes:

• Systematic Approach: Structured phases from specification to completion
• Test-Driven Development: Tests written before implementation
• Parallel Execution: Concurrent agent coordination for 2.8-4.4x speed improvements
• Memory Integration: Persistent knowledge sharing across agents and sessions
• Quality First: Comprehensive reviews, testing, and validation
• Modular Design: Clean separation of concerns with clear interfaces

Key Principles

1. Specification Before Code: Define requirements and constraints clearly
2. Design Before Implementation: Plan architecture and components
3. Tests Before Features: Write failing tests, then make them pass
4. Review Everything: Code quality, security, and performance checks
5. Document Continuously: Maintain current documentation throughout

---

Development Phases

Phase 1: Specification

Goal: Define requirements, constraints, and success criteria

• Requirements analysis
• User story mapping
• Constraint identification
• Success metrics definition
• Pseudocode planning

Key Modes: researcher, analyzer, memory-manager

Phase 2: Architecture

Goal: Design system structure and component interfaces

• System architecture design
• Component interface definition
• Database schema planning
• API contract specification
• Infrastructure planning

Key Modes: architect, designer, orchestrator

Phase 3: Refinement (TDD Implementation)

Goal: Implement features with test-first approach

• Write failing tests
• Implement minimum viable code
• Make tests pass
• Refactor for quality
• Iterate until complete

Key Modes: tdd, coder, tester

Phase 4: Review

Goal: Ensure code quality, security, and performance

• Code quality assessment
• Security vulnerability scanning
• Performance profiling
• Best practices validation
• Documentation review

Key Modes: reviewer, optimizer, debugger

Phase 5: Completion

Goal: Integration, deployment, and monitoring

• System integration
• Deployment automation
• Monitoring setup
• Documentation finalization
• Knowledge capture

Key Modes: workflow-manager, documenter, memory-manager

---

Available Modes

Core Orchestration Modes

orchestrator

Multi-agent task orchestration with TodoWrite/Task/Memory coordination.

Capabilities:

• Task decomposition into manageable units
• Agent coordination and resource allocation
• Progress tracking and result synthesis
• Adaptive strategy selection
• Cross-agent communication

Usage:

mcp__ruflo__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__ruflo__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__ruflo__sparc_mode {
  mode: "architect",
  task_description: "design scalable e-commerce platform",
  options: {
    detailed: true,
    memory_enabled: true,
    patterns: ["microservices", "event-driven"]
  }
}

tdd

Test-driven development with comprehensive testing.

Capabilities:

• Test-first development
• Red-green-refactor cycle
• Test suite design
• Coverage optimization (target: 90%+)
• Continuous testing

TDD Workflow:

1. Write failing test (RED)
2. Implement minimum code
3. Make test pass (GREEN)
4. Refactor for quality (REFACTOR)
5. Repeat cycle

Testing Strategies:

• Unit testing (Jest, Mocha, Vitest)
• Integration testing
• End-to-end testing (Playwright, Cypress)
• Performance testing
• Security testing

Usage:

mcp__ruflo__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__ruflo__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__ruflo__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 Codex)

Best for: Integrated Codex workflows with full orchestration capabilities

// Basic mode execution
mcp__ruflo__sparc_mode {
  mode: "<mode-name>",
  task_description: "<task description>",
  options: {
    // mode-specific options
  }
}

// Initialize swarm for complex tasks
mcp__ruflo__swarm_init {
  topology: "hierarchical",  // or "mesh", "ring", "star"
  strategy: "auto",           // or "balanced", "specialized", "adaptive"
  maxAgents: 8
}

// Spawn specialized agents
mcp__ruflo__agent_spawn {
  type: "<agent-type>",
  capabilities: ["<capability1>", "<capability2>"]
}

// Monitor execution
mcp__ruflo__swarm_monitor {
  swarmId: "current",
  interval: 5000
}

Method 2: NPX CLI (Fallback)

Best for: Terminal usage or when MCP tools unavailable

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

# Use alpha features
npx @sparkleideas/ruflo@latest sparc run <mode> "task description"

# List all available modes
npx Codex-flow sparc modes

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

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

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

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

# Pipeline execution
npx Codex-flow sparc pipeline "task description"

Method 3: Local Installation

Best for: Projects with local Codex-flow installation

# If Codex-flow is installed locally
./Codex-flow sparc run <mode> "task description"

---

Orchestration Patterns

Pattern 1: Hierarchical Coordination

Best for: Complex projects with clear delegation hierarchy

// Initialize hierarchical swarm
mcp__ruflo__swarm_init {
  topology: "hierarchical",
  maxAgents: 12
}

// Spawn coordinator
mcp__ruflo__agent_spawn {
  type: "coordinator",
  capabilities: ["planning", "delegation", "monitoring"]
}

// Spawn specialized workers
mcp__ruflo__agent_spawn { type: "architect" }
mcp__ruflo__agent_spawn { type: "coder" }
mcp__ruflo__agent_spawn { type: "tester" }
mcp__ruflo__agent_spawn { type: "reviewer" }

Pattern 2: Mesh Coordination

Best for: Collaborative tasks requiring peer-to-peer communication

mcp__ruflo__swarm_init {
  topology: "mesh",
  strategy: "balanced",
  maxAgents: 6
}

Pattern 3: Sequential Pipeline

Best for: Ordered workflow execution (spec → design → code → test → review)

mcp__ruflo__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__ruflo__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__ruflo__swarm_init {
  topology: "hierarchical",
  strategy: "adaptive",  // Auto-adjusts based on workload
  maxAgents: 20
}

---

TDD Workflows

Complete TDD Workflow

// Step 1: Initialize TDD swarm
mcp__ruflo__swarm_init {
  topology: "hierarchical",
  maxAgents: 8
}

// Step 2: Research and planning
mcp__ruflo__sparc_mode {
  mode: "researcher",
  task_description: "research testing best practices for feature X"
}

// Step 3: Architecture design
mcp__ruflo__sparc_mode {
  mode: "architect",
  task_description: "design testable architecture for feature X"
}

// Step 4: TDD implementation
mcp__ruflo__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__ruflo__sparc_mode {
  mode: "reviewer",
  task_description: "review feature X implementation",
  options: {
    test_coverage_check: true,
    security_check: true
  }
}

// Step 6: Optimization
mcp__ruflo__sparc_mode {
  mode: "optimizer",
  task_description: "optimize feature X performance"
}

Red-Green-Refactor Cycle

// RED: Write failing test
mcp__ruflo__sparc_mode {
  mode: "tester",
  task_description: "create failing test for shopping cart add item",
  options: { expect_failure: true }
}

// GREEN: Minimal implementation
mcp__ruflo__sparc_mode {
  mode: "coder",
  task_description: "implement minimal code to pass test",
  options: { minimal: true }
}

// REFACTOR: Improve code quality
mcp__ruflo__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__ruflo__memory_usage {
  action: "store",
  namespace: "architecture",
  key: "api-design-v1",
  value: JSON.stringify(apiDesign),
  ttl: 86400000  // 24 hours
}

// Retrieve in subsequent agents
mcp__ruflo__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__ruflo__agent_spawn { type: "researcher" }
  mcp__ruflo__agent_spawn { type: "coder" }
  mcp__ruflo__agent_spawn { type: "tester" }
  TodoWrite { todos: [8-10 todos] }

// ❌ WRONG: Multiple messages
Message 1: mcp__ruflo__agent_spawn { type: "researcher" }
Message 2: mcp__ruflo__agent_spawn { type: "coder" }
Message 3: TodoWrite { todos: [...] }

3. Hook Integration

Every SPARC mode should use hooks:

# Before work
npx @sparkleideas/ruflo@latest hooks pre-task --description "implement auth"

# During work
npx @sparkleideas/ruflo@latest hooks post-edit --file "auth.js"

# After work
npx @sparkleideas/ruflo@latest 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__ruflo__swarm_init {
  topology: "hierarchical",
  maxAgents: 10
}

// Architecture phase
mcp__ruflo__sparc_mode {
  mode: "architect",
  task_description: "design REST API with authentication",
  options: { memory_enabled: true }
}

// Research phase
mcp__ruflo__sparc_mode {
  mode: "researcher",
  task_description: "research authentication best practices"
}

// Implementation phase
mcp__ruflo__sparc_mode {
  mode: "coder",
  task_description: "implement Express API with JWT auth",
  options: { test_driven: true }
}

// Testing phase
mcp__ruflo__sparc_mode {
  mode: "tdd",
  task_description: "comprehensive API tests",
  options: { coverage_target: 90 }
}

// Review phase
mcp__ruflo__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__ruflo__sparc_mode {
  mode: "researcher",
  task_description: "research AI-powered search implementations",
  options: {
    depth: "comprehensive",
    sources: ["academic", "industry"]
  }
}

// Innovation phase
mcp__ruflo__sparc_mode {
  mode: "innovator",
  task_description: "propose novel search algorithm",
  options: { memory_enabled: true }
}

// Architecture phase
mcp__ruflo__sparc_mode {
  mode: "architect",
  task_description: "design scalable search system"
}

// Implementation phase
mcp__ruflo__sparc_mode {
  mode: "coder",
  task_description: "implement search algorithm",
  options: { test_driven: true }
}

// Documentation phase
mcp__ruflo__sparc_mode {
  mode: "documenter",
  task_description: "document search system architecture and API"
}

Example 3: Legacy Code Refactoring

// Analysis phase
mcp__ruflo__sparc_mode {
  mode: "analyzer",
  task_description: "analyze legacy codebase dependencies"
}

// Planning phase
mcp__ruflo__sparc_mode {
  mode: "orchestrator",
  task_description: "plan incremental refactoring strategy"
}

// Testing phase (create safety net)
mcp__ruflo__sparc_mode {
  mode: "tester",
  task_description: "create comprehensive test suite for legacy code",
  options: { coverage_target: 80 }
}

// Refactoring phase
mcp__ruflo__sparc_mode {
  mode: "coder",
  task_description: "refactor module X with modern patterns",
  options: { maintain_tests: true }
}

// Review phase
mcp__ruflo__sparc_mode {
  mode: "reviewer",
  task_description: "validate refactoring maintains functionality"
}

---

Common Workflows

Workflow 1: Feature Development

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

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

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

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

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

Workflow 2: Bug Investigation

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

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

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

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

Workflow 3: Performance Optimization

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

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

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

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

Workflow 4: Complete Pipeline

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

Cross-Session Memory

// Save session state
mcp__ruflo__memory_persist {
  sessionId: "feature-auth-v1"
}

// Restore in new session
mcp__ruflo__context_restore {
  snapshotId: "feature-auth-v1"
}

GitHub Integration

// Analyze repository
mcp__ruflo__github_repo_analyze {
  repo: "owner/repo",
  analysis_type: "code_quality"
}

// Manage pull requests
mcp__ruflo__github_pr_manage {
  repo: "owner/repo",
  pr_number: 123,
  action: "review"
}

Performance Monitoring

// Real-time swarm monitoring
mcp__ruflo__swarm_monitor {
  swarmId: "current",
  interval: 5000
}

// Bottleneck analysis
mcp__ruflo__bottleneck_analyze {
  component: "api-layer",
  metrics: ["latency", "throughput", "errors"]
}

// Token usage tracking
mcp__ruflo__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/Codex-flow
• Issues: https://github.com/ruvnet/Codex-flow/issues
• NPM Package: https://www.npmjs.com/package/Codex-flow
• Community: Discord server (link in repository)

---

Quick Reference

Most Common Commands

# List modes
npx Codex-flow sparc modes

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

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

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

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

Most Common MCP Calls

// Initialize swarm
mcp__ruflo__swarm_init { topology: "hierarchical" }

// Execute mode
mcp__ruflo__sparc_mode { mode: "coder", task_description: "..." }

// Monitor progress
mcp__ruflo__swarm_monitor { interval: 5000 }

// Store in memory
mcp__ruflo__memory_usage { action: "store", key: "...", value: "..." }

---

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