chidekina/aria-superpowers/spec

/prd (human intent) → /spec (AI-native YAML) → /ralph (executable prd.json)

<analysis>
1. FEATURE SCOPE
   What is the core feature? What is explicitly out of scope?
 
2. DOMAIN TYPES
   What data entities are created or modified?
   For each entity: what fields, types, and constraints are required?
 
3. ENDPOINTS / OPERATIONS
   What actions does the user or system perform?
   For each: method, path, inputs, all possible outputs (success + every error).
 
4. EFFECT DETECTION
   Which systems does each operation touch?
   (db-write, db-read, email-send, whatsapp-send, github-pr, docker, calendar, api-call, ollama)
 
5. TOTALITY CHECK
   Which operations are critical paths (auth, payments, data mutations)?
   These get isTotal: true — every error variant MUST be listed in outputs.
 
6. LATENCY CLASSIFICATION
   API reads → 50-100ms | API writes → 100-500ms | Batch → 1000-5000ms | Heavy → 5000-30000ms
 
7. TEST COVERAGE
   What test scenarios are implied by the outputs?
   List T-NNN IDs for each endpoint.
</analysis>

spec: SPEC-{YYYY}-{NNN}
title: "{Feature Title}"
project: {project-name}
branch: ralph/{feature-name-kebab}
specRef: PRD-{feature-name}
author: agent:claude-opus-4
 
# What systems/APIs does this feature touch?
effects:
  - db-write
  - hub-write
  - whatsapp-send
 
# Domain types with constraints
types:
  User:
    fields:
      id:
        type: UUID
        generated: true
        immutable: true
      email:
        type: String
        format: email
        unique: true
        constraints:
          - minLen: 5
          - maxLen: 255
      name:
        type: String
        constraints:
          - minLen: 1
          - maxLen: 200
 
# Endpoints with exhaustive outputs
endpoints:
  createUser:
    method: POST
    path: /api/users
    effects: [db-write]
    isTotal: true
    latencyBudgetMs: 200
    input:
      email:
        type: String
        source: body
        required: true
      name:
        type: String
        source: body
        required: true
    outputs:
      - status: 201
        type: ok
        returns: User
        description: User created successfully
      - status: 400
        type: err
        code: VALIDATION_ERROR
        description: Invalid input data
      - status: 409
        type: err
        code: CONFLICT
        description: Email already exists
      - status: 500
        type: err
        code: INTERNAL_ERROR
        description: Database error
 
  getUser:
    method: GET
    path: /api/users/{id}
    effects: [db-read]
    isTotal: true
    latencyBudgetMs: 50
    input:
      id:
        type: UUID
        source: path
        required: true
    outputs:
      - status: 200
        type: ok
        returns: User
      - status: 404
        type: err
        code: NOT_FOUND
        description: User not found
      - status: 400
        type: err
        code: INVALID_ID
        description: Invalid UUID format
 
# Test references
tests:
  - id: T-001
    covers: createUser
    scenario: "Create user with valid data"
  - id: T-002
    covers: createUser
    scenario: "Reject duplicate email"
  - id: T-003
    covers: getUser
    scenario: "Get existing user"
  - id: T-004
    covers: getUser
    scenario: "Handle not found"
 
# Quality gates
quality:
  - All endpoints must handle errors explicitly
  - All isTotal endpoints must cover all output variants
  - Latency budgets must be defined for all endpoints

# Requirements: {Feature Name}
 
## Functional Requirements
-**EARS-UBIQ-001**: The system SHALL {do X}
-**EARS-EVENT-002**: WHEN {event} the system SHALL {do Y}
-**EARS-COND-003**: WHERE {condition} the system SHALL {do Z}
-**EARS-OPT-004**: WHERE {optional feature} is included the system SHALL {do W}
-**EARS-UNW-005**: IF {unwanted condition} THEN the system SHALL {respond}
 
## Non-Functional Requirements
-**PERF-001**: {endpoint} SHALL respond within {N}ms at p99
-**SEC-001**: All inputs SHALL be validated against {schema}
-**REL-001**: The system SHALL handle {failure mode} gracefully
 
## Out of Scope
-{explicitly excluded features}

# Design: {Feature Name}
 
## Architecture Decision
**Choice:** {chosen approach}
**Rationale:** {why}
**Rejected alternatives:** {what and why not}
 
## Sequence Diagram
 

 
## Data Flow
{describe how data moves through the system}
 
## Error Handling Strategy
{how failures are surfaced to the caller}

# Tasks: {Feature Name}
 
## Status: IN PROGRESS
 
| # | Task | Status | Story |
|---|------|--------|-------|
| 1 | Add DB schema | ✅ Done | US-001 |
| 2 | Implement service | 🔄 Active | US-002 |
| 3 | Wire up route | ⬜ Pending | US-003 |
| 4 | Add frontend component | ⬜ Pending | US-004 |

PRD created: tasks/prd-{feature}.md
→ Suggest: "Run /spec to generate structured YAML spec"

# Validate spec files
for spec in tasks/spec-*.yaml; do
  claude-code validate-spec "$spec"
done

## Requirements
-User can register with email and password
-Email must be unique
-Password must be 8+ characters
-System sends welcome email after registration

spec: SPEC-2026-001
title: "User Registration"
project: my-app
effects:
  - db-write
  - email-send
 
types:
  User:
    fields:
      email:
        type: String
        format: email
        unique: true
      password:
        type: String
        constraints:
          - minLen: 8
 
endpoints:
  register:
    method: POST
    path: /api/auth/register
    effects: [db-write, email-send]
    isTotal: true
    latencyBudgetMs: 500
    outputs:
      - status: 201
        type: ok
        returns: User
      - status: 400
        type: err
        code: VALIDATION_ERROR
      - status: 409
        type: err
        code: CONFLICT
        description: Email already registered