# Sparc Framework

> SPARC Framework Skill

- Skill: `alex-tgk/sparc-framework` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alex-tgk/sparc-framework`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alex-tgk/sparc-framework/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alex-tgk (https://skillmd.com/u/alex-tgk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alex-tgk/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**
```typescript
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**
```typescript
async login(credentials) {
  return { accessToken: 'mock-token' };
}
```
✅ Test passes

**REFACTOR - Improve Code**
```typescript
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:

```markdown
## 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**
```markdown
## 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**
```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**
```markdown
## 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)**
```typescript
// 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**
```markdown
## 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.*