SPARC Agentic Development Framework

# SPARC Agentic Development Framework

## Overview

SPARC guides structured agentic coding through five core principles: **S**implicity, **P**lan before code, **A**gile iteration, **R**easoning with context, and **C**ollaborative AI-human workflow.

## Core Philosophy

### Five Pillars

1. **Simplicity First**: Prioritize clear, maintainable solutions; minimize unnecessary complexity
2. **Plan Before Code**: Draft approach, confirm understanding, then implement
3. **Agile Iteration**: Iterate over rewrites; evolve code incrementally
4. **Reasoning with Context**: Use symbolic reasoning and maintain persistent context
5. **Collaborative Workflow**: Structured AI-human teamwork with clear handoffs

## Methodology & Workflow

### Development Phases

1. **Specification**: Define requirements, constraints, success criteria
2. **Pseudocode**: Draft logic in plain language before coding
3. **Architecture**: Design component structure and data flow
4. **Refinement**: Iterate on implementation with feedback
5. **Completion**: Finalize with testing and documentation

### Task Execution Pattern

```markdown
## Task: [Name]

### Specification
- Goal: [What we're building]
- Constraints: [Limitations and requirements]
- Success Criteria: [How we know it's done]

### Approach
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Implementation
[Code with explanatory comments]

### Verification
- [ ] Meets success criteria
- [ ] Tests pass
- [ ] Documentation updated
```

## Agentic Integration

### Cline Configuration (.clinerules)

```markdown
# Project Rules

## Code Style
- TypeScript strict mode
- Functional patterns preferred
- Components under 300 lines

## Workflow
- Always explain before implementing
- Create tests for new features
- Update docs with changes

## Boundaries
- Never modify .env files
- Don't delete without confirmation
- Ask before major refactors
```

### Cursor Configuration (.cursorrules)

```markdown
# Cursor Rules

You are an expert developer following SPARC methodology.

## Principles
- Simplicity over cleverness
- Explicit over implicit
- Composition over inheritance

## Before Coding
- Confirm understanding of requirements
- Outline approach in comments
- Identify potential issues

## During Coding
- Write self-documenting code
- Add tests alongside features
- Keep functions focused
```

## Memory Bank Integration

### Persistent Context

Maintain context across sessions with structured memory:

```markdown
# Memory Bank

## Project Context
- Framework: Next.js 15
- Database: PostgreSQL with Drizzle
- Styling: Tailwind + shadcn/ui

## Decisions Made
- [Date]: Chose X over Y because Z
- [Date]: Implemented pattern A for reason B

## Patterns Established
- API routes use zod validation
- Components follow atomic design
- Error handling uses Result type
```

## Code Quality Standards

### TypeScript Guidelines

```typescript
// Strict typing - no any
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E }

// Explicit return types
function processData(input: Input): Result<Output> {
  // Implementation
}

// Discriminated unions for state
type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }
```

### Component Guidelines

```typescript
// Keep components focused (under 300 lines)
// Single responsibility
// Composition over configuration

interface UserCardProps {
  user: User
  onEdit?: (user: User) => void
  className?: string
}

export function UserCard({ user, onEdit, className }: UserCardProps) {
  return (
    <Card className={cn('p-4', className)}>
      <UserAvatar user={user} />
      <UserInfo user={user} />
      {onEdit && <EditButton onClick={() => onEdit(user)} />}
    </Card>
  )
}
```

## Testing Requirements

### Test-Driven Development

1. Write failing test first
2. Implement minimal passing code
3. Refactor while keeping tests green

### Coverage Standards

```typescript
// Unit tests for business logic
describe('calculateTotal', () => {
  it('applies discount correctly', () => {
    expect(calculateTotal(100, 0.1)).toBe(90)
  })

  it('handles zero discount', () => {
    expect(calculateTotal(100, 0)).toBe(100)
  })

  it('throws on negative values', () => {
    expect(() => calculateTotal(-100, 0.1)).toThrow()
  })
})

// Integration tests for flows
describe('checkout flow', () => {
  it('completes purchase successfully', async () => {
    // Arrange
    const cart = createTestCart()

    // Act
    const result = await checkout(cart)

    // Assert
    expect(result.success).toBe(true)
    expect(result.orderId).toBeDefined()
  })
})
```

## Security Practices

### Server-Side Authority

- Validate all inputs on server
- Never trust client data
- Use parameterized queries

### Input Sanitization

```typescript
import { z } from 'zod'

const UserInput = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  age: z.number().int().positive().max(150),
})

function createUser(input: unknown) {
  const validated = UserInput.parse(input) // Throws on invalid
  // Safe to use validated data
}
```

## Documentation Standards

### Code Comments

```typescript
/**
 * Calculates the total price with applied discounts.
 *
 * @param basePrice - Original price before discounts
 * @param discountRate - Discount as decimal (0.1 = 10%)
 * @returns Final price after discount
 * @throws {Error} If basePrice is negative
 *
 * @example
 * calculateTotal(100, 0.1) // Returns 90
 */
function calculateTotal(basePrice: number, discountRate: number): number {
  if (basePrice < 0) throw new Error('Price cannot be negative')
  return basePrice * (1 - discountRate)
}
```

### Change Documentation

After significant changes, update:
- README if usage changed
- CHANGELOG for version history
- API docs for endpoint changes
- Architecture docs for structural changes

## Version Control

### Commit Messages

```
feat: add user authentication flow
fix: resolve race condition in cart updates
refactor: extract validation logic to shared module
docs: update API documentation for v2 endpoints
test: add integration tests for checkout flow
```

### Branch Strategy

- `main` - Production-ready code
- `develop` - Integration branch
- `feature/*` - New features
- `fix/*` - Bug fixes
- `refactor/*` - Code improvements