Propose

# /propose — API Endpoint Proposal Generator

Generates a detailed API endpoint proposal for a Bukoo use case, iterates with the developer until approved, then saves it to `.claude/context/api-proposals/`.

## Input Format

/propose [| ]

Accepted formats for `<endpoint_ref>`:

- Catalog notation: `1.6`, `4.3`, `11.1`
- Zero-padded: `01_06`, `04_03`
- Description: `auth logout`, `create book`, `place order`

The optional `| <notes>` section passes free-form context that shapes the proposal. Examples:

/propose 1.6 | also invalidate all refresh tokens on logout /propose auth register | use SendGrid for verification email

---

## Steps

### 1. Parse the Reference

Split input on `|` — everything before is `<endpoint_ref>`, everything after (if present) is `<notes>`. Trim both parts.

Map `<endpoint_ref>` to an API set index and endpoint index using `.claude/context/api-endpoint-catalog.md`. If the reference is ambiguous or not found, list the closest matches and ask the user to clarify.

### 2. Read Context (in parallel)

- `.claude/context/api-endpoint-catalog.md` — endpoint spec and notes
- `.claude/context/architecture.md` — layer rules, request lifecycle, patterns
- `.claude/context/domain-model.md` — entities, invariants, existing repo interfaces
- Relevant existing domain files (entity, exceptions, repo interface) for this domain group — read these to use **real class names** in the proposal, not placeholders

If `<notes>` were provided, display them prominently before generating the proposal:

> **Proposal notes:** `<notes>`

Apply them throughout — they may add behaviour, restrict scope, or specify implementation choices.

### 3. Generate the Proposal

Using the **Proposal Template** below, produce a complete proposal covering all 8 sections. The Procedures section requires the highest effort — it must be detailed enough that any developer could implement the endpoint without ambiguity.

### 4. Output in Chat

Present the full proposal as a fenced markdown block. Then ask:

> "Does this proposal look correct? Let me know any sections to revise, or say **approved** when ready to save."

### 5. Iterate

Incorporate all feedback and re-output the updated proposal. Repeat until the user signals final approval with any of: `approved`, `looks good`, `save it`, `save`, `lgtm`.

### 6. Save

Save the final proposal to:

.claude/context/api-proposals/[api_set_idx][uc_idx][use_case_name]_proposal.md

- Both indices zero-padded to 2 digits
- Use case name: lowercase with underscores, no spaces or hyphens
- Set the status field to `Approved`

Confirm the saved path to the user.

---

## Proposal Template

````markdown
# [API Set Name] — [Use Case Name] Proposal

## Overview

| Field        | Value                                            |
| ------------ | ------------------------------------------------ |
| API Set      | [index]. [name]                                  |
| Use Case     | [uc_idx]. [name]                                 |
| File Index   | [api_set_idx]\_[uc_idx]                          |
| Access Level | [🌐 Public / 👤 Customer / 🔑 Admin / 👤🔑 Both] |
| Status       | Draft                                            |

---

## Endpoint

| Field  | Value                                                                                   |
| ------ | --------------------------------------------------------------------------------------- |
| Method | [GET / POST / PATCH / PUT / DELETE]                                                     |
| URL    | `/api/app/v1/[path]`                                                                    |
| Auth   | [None / Bearer token (USER role) / Bearer token (ADMIN role) / Bearer token (any role)] |

---

## Request

### Headers

| Header        | Required | Description           |
| ------------- | -------- | --------------------- |
| Content-Type  | [Yes/No] | application/json      |
| Authorization | [Yes/No] | Bearer {access_token} |

### Path Parameters

| Parameter | Type          | Description   |
| --------- | ------------- | ------------- |
| [param]   | string (UUID) | [description] |

_(None — if no path params)_

### Query Parameters

| Parameter | Type   | Required | Default   | Description   |
| --------- | ------ | -------- | --------- | ------------- |
| [param]   | [type] | [Yes/No] | [default] | [description] |

_(None — if no query params)_

### Request Body

| Field   | Type   | Required | Constraints   |
| ------- | ------ | -------- | ------------- |
| [field] | [type] | [Yes/No] | [constraints] |

_(None — if no request body)_

**Example:**

```json
{
  "field": "value"
}

---

## Response

### Success Response

**Status:** [HTTP status code and name]

```json
{
  "success": true,
  "data": {
    "field": "value"
  },
  "meta": {
    "requestId": "01932abc-...",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}
```

### Error Responses

| HTTP Status | Error Code                 | Condition                   |
| ----------- | -------------------------- | --------------------------- |
| 400         | VALIDATION_ERROR           | [condition]                 |
| 401         | AUTH_TOKEN_INVALID         | [condition]                 |
| 403         | PERMISSION_DENIED          | [condition]                 |
| 404         | [RESOURCE]\_NOT_FOUND      | [condition]                 |
| 409         | [RESOURCE]\_ALREADY_EXISTS | [condition]                 |
| 422         | UNPROCESSABLE_ENTITY       | Pydantic validation failure |

---

## Procedures

Detailed step-by-step logic in plain English. Use **real class names** from the domain files you read in Step 2 — no placeholders like `[EntityNotFoundError]`. Be specific about exception classes, error codes, field names, and where `commit()` is called.

**General flow pattern** (adapt step count to the endpoint's actual complexity — simple endpoints may need 4 steps, complex ones 12+):

- **Auth/guard** — Validate Bear
```