📄 spec-template.md 3,373 bytes Monday 19:54 📋 Raw

SPEC: {Feature Name}

Generated by Agent Collaboration Protocol

Overview

One sentence. What this feature does and why it matters.

Contract

Field Value
API Base Path http://localhost:8000/api/v1
Auth Scheme Bearer JWT / Session cookie / None
Content Type application/json
Error Format { "error": "...", "detail": { ... } }

Data Models

{Entity Name}

Field Type Required Notes
id string yes UUID
name string yes Display name
status string yes See Shared Constants

{Entity Name 2}

...

Shared Constants

Both backend and frontend must use the same values for these:

Status Enums

Constant Values Used By
{Entity}Status active, inactive, pending Backend enum + frontend labels
ErrorCode NOT_FOUND, UNAUTHORIZED, VALIDATION_ERROR Backend error responses + frontend error messages

Feature Flags

Flag Default Description
ENABLE_{FEATURE} false Controls {feature} visibility

Endpoints

GET /api/v1/{resource}

Response:

{
  "data": [ ... ],
  "total": 42,
  "page": 1
}

POST /api/v1/{resource}

Request:

{
  "field": "value"
}

Response: 201 Created with body containing the created entity

Error Response (all endpoints)

{
  "error": "VALIDATION_ERROR",
  "detail": {
    "field": "email",
    "message": "Invalid email format"
  }
}

UI Components

{Component Name}

  • Purpose: One sentence
  • Data source: GET /api/v1/{resource}
  • States: loading, empty, error, populated
  • Interactions: click to select, pull to refresh

File Structure

Backend

backend/
  router.py        ← Route handlers
  models.py        ← Data models/schemas
  service.py       ← Business logic

Frontend

frontend/
  components/      ← UI components
  templates/       ← Page templates
  styles/          ← Styles
  api.js           ← API client

Edge Cases

  • Empty state: What shows when no data exists?
  • Error state: What shows on API failure?
  • Loading state: What shows while data fetches?
  • Offline: Does it degrade gracefully?

Verification Checklist

Backend

  • [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)
  • [ ] Error responses match the shared error format
  • [ ] Status enums match the Shared Constants section
  • [ ] Auth scheme matches the Contract section

Frontend

  • [ ] Loading state renders (spinner/skeleton)
  • [ ] Empty state renders (no data message)
  • [ ] Error state renders (actionable error message)
  • [ ] Populated state renders with real data
  • [ ] All user interactions work (click, submit, navigate)

Integration

  • [ ] Frontend fetch calls match backend endpoint paths
  • [ ] Request/response shapes match the spec
  • [ ] Shared constants are consistent between frontend and backend
  • [ ] Auth flow works end-to-end

Success Criteria

  • [ ] Observable behavior that proves it works (not "tests pass")
  • [ ] User can complete the full happy path end-to-end
  • [ ] API errors display actionable messages in the UI

Out of Scope

  • What we are NOT building right now
  • Authentication improvements
  • Performance optimization
← Back