# 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:**
```json
{
  "data": [ ... ],
  "total": 42,
  "page": 1
}
```

### `POST /api/v1/{resource}`
**Request:**
```json
{
  "field": "value"
}
```
**Response:** `201 Created` with body containing the created entity

### Error Response (all endpoints)
```json
{
  "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