Sparc Framework

SPARC Framework Skill

Systematic software development through five disciplined phases: Specification, Pseudocode, Architecture, Refinement, and Completion.

Skill Overview

This skill implements ruvnet's SPARC methodology - a structured, test-driven approach to building robust, well-documented, production-ready software. SPARC emphasizes comprehensive planning before implementation, continuous testing, and systematic progression through five phases.

Usage

To activate this skill:

/sparc

Or specify a phase:

/sparc specification for user authentication feature
/sparc architecture for microservices design
/sparc refinement with TDD for payment processing

What This Skill Does

When activated, the SPARC skill guides you through:

1. Specification - Define comprehensive, testable requirements
2. Pseudocode - Design algorithms and logic flow
3. Architecture - Plan system structure and components
4. Refinement - Implement with Test-Driven Development
5. Completion - Finalize, document, deploy, and monitor

Each phase produces artifacts that inform subsequent phases, ensuring quality and maintainability.

The Five SPARC Phases

Phase 1: Specification

Purpose: Define what to build with testable requirements

Activities:

• Document functional and non-functional requirements
• Create user stories with acceptance criteria
• Identify edge cases and constraints
• Define success metrics

Deliverables:

• Requirements document
• Test scenarios
• Acceptance criteria
• Success metrics

When to Use:

• Starting new features
• Planning major changes
• Clarifying ambiguous requirements

Phase 2: Pseudocode

Purpose: Design logic flow before writing code

Activities:

• Create language-agnostic algorithms
• Plan data structures
• Document complexity analysis
• Validate logic with walkthroughs

Deliverables:

• Pseudocode for main algorithms
• Data structure designs
• Complexity analysis
• Edge case handling plans

When to Use:

• Complex algorithms
• Novel implementations
• Teaching/documentation
• Logic validation before coding

Phase 3: Architecture

Purpose: Define system structure and technical decisions

Activities:

• Design component interactions
• Select technologies and frameworks
• Define API contracts
• Plan integration points
• Choose design patterns

Deliverables:

• Architecture diagrams
• Component specifications
• API contracts
• Database schemas
• Technology decisions

When to Use:

• System design
• Microservices planning
• Major refactoring
• Technology selection

Phase 4: Refinement

Purpose: Implement with Test-Driven Development

Activities:

• Write failing tests (RED)
• Write minimal passing code (GREEN)
• Refactor for quality (REFACTOR)
• Achieve ≥80% test coverage
• Continuous code review

Deliverables:

• Production code
• Comprehensive test suite
• Code coverage report
• Performance benchmarks
• Refactored, clean code

When to Use:

• Feature implementation
• Bug fixes with tests
• Code quality improvement
• TDD practice

Phase 5: Completion

Purpose: Production readiness and deployment

Activities:

• Final integration testing
• Documentation completion
• Deployment automation
• Monitoring setup
• Security hardening

Deliverables:

• API documentation
• User guides
• Deployment artifacts
• Monitoring dashboards
• Production deployment

When to Use:

• Feature completion
• Release preparation
• Production deployment
• Operational handoff

When to Use This Skill

Use SPARC when you need:

• Systematic development from concept to deployment
• High-quality code with comprehensive testing
• Clear documentation for team collaboration
• Production-ready software with monitoring
• Disciplined approach to complex projects
• TDD practice and test coverage
• Architectural clarity before implementation

SPARC Workflows

Full SPARC Cycle (New Feature)

/sparc full-cycle user authentication system

Guides through all five phases sequentially:

1. Specification → requirements and acceptance criteria
2. Pseudocode → auth algorithm and token refresh logic
3. Architecture → auth service, database, API design
4. Refinement → TDD implementation with 80%+ coverage
5. Completion → deployment, monitoring, documentation

Rapid SPARC (Bug Fix)

/sparc rapid-fix authentication token expiry bug

Condensed cycle optimized for speed:

1. Specification (5 min) → bug definition
2. Pseudocode (5 min) → fix approach
3. Architecture (5 min) → impact assessment
4. Refinement (30 min) → TDD bug fix
5. Completion (10 min) → deploy with monitoring

SPARC Refactoring

/sparc refactor legacy authentication module

Refactoring-focused workflow:

1. Specification → refactoring goals and constraints
2. Pseudocode → refactoring transformations
3. Architecture → new design and migration path
4. Refinement → incremental refactoring with tests
5. Completion → gradual rollout with feature flags

Single Phase SPARC

/sparc specification for payment processing
/sparc architecture for event-driven system
/sparc refinement for checkout flow

Focus on one phase when others are complete or known.

TDD in SPARC (Phase 4)

The Refinement phase uses strict Test-Driven Development:

RED-GREEN-REFACTOR Cycle

RED - Write Failing Test

it('should authenticate user with valid credentials', async () => {
  const result = await authService.login({
    username: 'test',
    password: 'password123'
  });
  expect(result).toHaveProperty('accessToken');
});

❌ Test fails (not implemented)

GREEN - Minimal Implementation

async login(credentials) {
  return { accessToken: 'mock-token' };
}

✅ Test passes

REFACTOR - Improve Code

async login(credentials: LoginCredentials): Promise<AuthResponse> {
  const user = await this.userRepo.findByUsername(credentials.username);
  if (!user || !await this.validatePassword(credentials.password, user.hash)) {
    throw new AuthError('Invalid credentials');
  }
  return await this.tokenService.generateTokens(user);
}

✅ Tests still pass, code improved

TDD Best Practices

1. Always write tests first - No production code without failing test
2. Small increments - One test, one feature
3. Fast tests - Unit tests run in milliseconds
4. Descriptive names - Tests document expected behavior
5. Arrange-Act-Assert - Clear test structure
6. Mock I/O - Fast, isolated unit tests
7. Refactor fearlessly - Tests provide safety net

Phase Transitions

SPARC phases have clear transition criteria:

Specification → Pseudocode

✅ Requirements documented ✅ Acceptance criteria defined ✅ Edge cases identified ✅ Stakeholder approval

Pseudocode → Architecture

✅ Algorithms designed ✅ Logic validated ✅ Complexity analyzed ✅ Edge case handling planned

Architecture → Refinement

✅ Components specified ✅ API contracts defined ✅ Technology selected ✅ Integration planned

Refinement → Completion

✅ All tests passing ✅ Coverage ≥80% ✅ Code reviewed ✅ Performance validated

Completion → Production

✅ Documentation complete ✅ Monitoring configured ✅ Security hardened ✅ Deployment tested

Integration with Other Skills

SPARC + Swarm Intelligence

Enhance SPARC phases with swarm methodology:

Specification Phase:

/sparc specification + /swarm validate requirements

Use Systems + Critical agents to validate requirements

Architecture Phase:

/sparc architecture + /swarm design system

Full-spectrum swarm for architecture decisions

Refinement Phase:

/sparc refinement + /swarm parallel-implementation

Convergent agents for parallel TDD on components

SPARC + Code Review

/sparc refinement --with-review

Automatic code review after TDD implementation

SPARC + Documentation

/sparc completion --generate-docs

Auto-generate API docs, guides, and runbooks

Configuration Options

Customize SPARC workflow:

Set test coverage target:

/sparc refinement --coverage=90

Choose TDD style:

/sparc refinement --tdd-style=london  # mock dependencies
/sparc refinement --tdd-style=chicago # use real implementations

Skip phases (not recommended):

/sparc --skip=pseudocode architecture payment-service

Specify deployment strategy:

/sparc completion --deploy=blue-green
/sparc completion --deploy=canary

Progress Tracking

SPARC automatically tracks progress through phases:

## SPARC Progress: User Authentication Feature

Phase 1: Specification
✅ Requirements documented
✅ Acceptance criteria defined
✅ Edge cases identified
✅ Stakeholder approval obtained
Status: COMPLETE

Phase 2: Pseudocode
✅ Auth algorithm designed
✅ Token refresh logic planned
✅ Complexity analyzed
Status: COMPLETE

Phase 3: Architecture
✅ Auth service designed
✅ Database schema defined
✅ API contracts specified
⏳ Integration points being mapped
Status: IN PROGRESS (75%)

Phase 4: Refinement
⏳ Pending architecture completion
Status: NOT STARTED

Phase 5: Completion
⏳ Pending refinement completion
Status: NOT STARTED

Overall Progress: 45%

Quality Gates

SPARC enforces quality at each phase:

Specification Gates

• All requirements have acceptance criteria
• Edge cases documented
• Success metrics defined
• Stakeholder sign-off

Pseudocode Gates

• Algorithm logic validated
• Complexity analyzed
• Edge cases handled
• Walkthrough completed

Architecture Gates

• Components specified
• API contracts defined
• Technology justified
• Integration planned
• Security considered

Refinement Gates

• All tests passing (100%)
• Code coverage ≥80%
• No linting errors
• Performance benchmarks met
• Code reviewed and approved

Completion Gates

• Integration tests passing
• Documentation complete
• Monitoring configured
• Security scan passed
• Deployment successful
• Post-deployment monitoring (24h)

Output Artifacts

Each SPARC phase produces reusable artifacts:

Specification Artifacts

• Requirements document
• User stories
• Test scenarios
• Success metrics

Pseudocode Artifacts

• Algorithm pseudocode
• Data structure designs
• Complexity analysis
• Edge case documentation

Architecture Artifacts

• System diagrams
• Component specs
• API contracts (OpenAPI)
• Database schemas (SQL)
• Architecture Decision Records (ADRs)

Refinement Artifacts

• Production code
• Test suite (unit/integration/E2E)
• Coverage reports
• Performance benchmarks

Completion Artifacts

• API documentation
• User guides
• Deployment runbooks
• Monitoring dashboards
• Security audit results

Best Practices

Do's ✅

1. Complete each phase before moving to the next
2. Document continuously during each phase
3. Test first in Refinement phase
4. Review at transitions between phases
5. Iterate within phases when needed
6. Track metrics (coverage, performance, quality)
7. Involve stakeholders at phase boundaries

Don'ts ❌

1. Skip phases (especially Specification)
2. Write code before tests in Refinement
3. Rush Completion (monitoring is critical)
4. Ignore edge cases in Specification
5. Make architectural decisions in Refinement
6. Deploy without monitoring in Completion
7. Skip stakeholder review at transitions

Common Patterns

Pattern 1: New Feature Development

/sparc full-cycle real-time notifications

Complete SPARC cycle from requirements to production.

Pattern 2: Bug Fix with Tests

/sparc rapid-fix race condition in token refresh

Fast SPARC cycle ensuring bug fix has tests.

Pattern 3: Major Refactoring

/sparc refactor monolith to microservices

Architecture-heavy SPARC with migration planning.

Pattern 4: API Development

/sparc full-cycle REST API for user management

Contract-first SPARC with OpenAPI specs.

Pattern 5: Performance Optimization

/sparc refinement optimize database queries

Focus on Refinement with benchmarking.

Success Metrics

Track SPARC effectiveness:

• Phase Completion Rate: % phases completed vs skipped
• Test Coverage: Maintain ≥80% across projects
• Defect Density: Bugs per 1000 LOC (target: <5)
• Time per Phase: Optimize duration over time
• Rework Rate: % work redone due to skipped phases
• Deployment Success: % deployments without rollback

Example Workflow

Example: Building Authentication Feature

Phase 1: Specification

## Feature: User Authentication

### Functional Requirements
FR-1: Users can log in with username/password
FR-2: System generates JWT access + refresh tokens
FR-3: Tokens expire after 1 hour (access) / 7 days (refresh)
FR-4: System handles token refresh with race conditions

### Acceptance Criteria
- [ ] Valid credentials return access + refresh tokens
- [ ] Invalid credentials return 401 Unauthorized
- [ ] Expired tokens trigger refresh flow
- [ ] Concurrent refresh requests handled safely

### Success Metrics
- Response time: <200ms (p95)
- Uptime: 99.9%
- Test coverage: ≥85%

Phase 2: Pseudocode

function authenticateUser(credentials):
    validate credentials format

    user = findUserByUsername(credentials.username)
    if not user or not validatePassword(credentials.password, user.hash):
        return error(401, "Invalid credentials")

    tokens = generateTokens(user)
    storeRefreshToken(tokens.refresh, user.id)

    return success(tokens)

function refreshAccessToken(refreshToken):
    acquire refreshLock  // Prevent race conditions

    if not isValidRefreshToken(refreshToken):
        release refreshLock
        return error(401, "Invalid refresh token")

    user = getUserFromRefreshToken(refreshToken)
    newTokens = generateTokens(user)

    release refreshLock
    return success(newTokens)

Phase 3: Architecture

## Architecture: Auth Service

### Components
1. Auth API (Node.js + Express)
2. Token Service (JWT generation/validation)
3. User Repository (PostgreSQL)
4. Token Store (Redis for refresh tokens)

### API Contracts
POST /auth/login
  Request: { username, password }
  Response: { accessToken, refreshToken, expiresIn }

POST /auth/refresh
  Request: { refreshToken }
  Response: { accessToken, refreshToken, expiresIn }

### Database Schema
users: id, username, password_hash, created_at
refresh_tokens: token_hash, user_id, expires_at

Phase 4: Refinement (TDD)

// RED
test('should return tokens for valid credentials', async () => {
  const result = await authService.login({
    username: 'test',
    password: 'pass123'
  });
  expect(result.accessToken).toBeDefined();
});

// GREEN
class AuthService {
  async login(credentials) {
    return { accessToken: 'mock', refreshToken: 'mock' };
  }
}

// REFACTOR
class AuthService {
  constructor(
    private userRepo: UserRepository,
    private tokenService: TokenService
  ) {}

  async login(credentials: Credentials): Promise<AuthTokens> {
    const user = await this.userRepo.findByUsername(credentials.username);
    if (!user || !await bcrypt.compare(credentials.password, user.hash)) {
      throw new AuthError('Invalid credentials');
    }
    return await this.tokenService.generateTokens(user);
  }
}

Phase 5: Completion

## Production Checklist

### Testing
✅ Unit tests: 87% coverage
✅ Integration tests: All passing
✅ E2E tests: Login + refresh flows
✅ Load test: 1500 req/s sustained

### Documentation
✅ OpenAPI spec published
✅ User guide written
✅ Deployment runbook created

### Deployment
✅ Docker image built
✅ Kubernetes manifests ready
✅ CI/CD pipeline configured

### Monitoring
✅ Prometheus metrics exposed
✅ Grafana dashboard created
✅ Alerts configured
✅ Error tracking (Sentry)

### Security
✅ Dependencies scanned
✅ JWT secret rotated
✅ Rate limiting enabled
✅ Input validation comprehensive

Tips for Success

1. Don't skip Specification - Most rework comes from unclear requirements
2. Pseudocode saves time - Catching logic errors before coding is 10x faster
3. Architecture before code - Prevents major refactoring later
4. TDD is non-negotiable - Write tests first, always
5. Completion is critical - Production incidents come from incomplete monitoring
6. Document as you go - Retroactive documentation is painful
7. Get reviews at transitions - Catch issues early between phases

Skill Composition

SPARC works well with:

• Swarm Intelligence - Multi-agent validation at each phase
• Code Review Skills - Enhanced review during Refinement
• Architecture Skills - Deep-dive architecture in Phase 3
• Testing Skills - TDD expertise in Phase 4
• DevOps Skills - Deployment automation in Phase 5

Meta Information

Skill Type: Development Methodology / Process Framework Based on: ruvnet's SPARC Framework Best for: Feature development, system design, production deployments Token Usage: Medium (scales with project complexity) Output Quality: Very High (comprehensive, tested, documented) Learning Curve: Medium (requires TDD discipline)

Invoke this skill when you want systematic, test-driven development that produces production-ready, well-documented software through disciplined phases.