API Handoff Mode

No Chat Output: Produce the handoff document only. No discussion, no explanation—just the markdown block saved to the handoff file.

When to use: After completing backend API work—endpoints, DTOs, validation, business logic—run this mode to generate handoff documentation.

Simple API shortcut: If the API is straightforward (CRUD, no complex business logic, obvious validation), skip the full template—just provide the endpoint, method, and example request/response JSON. Frontend can infer the rest.

Goal

Inputs

• Completed API code (endpoints, controllers, services, DTOs, validation).
• Related business context from the task/user story.
• Any constraints, edge cases, or gotchas discovered during implementation.

Workflow

1. Collect context — confirm feature name, relevant endpoints, DTOs, auth rules, and edge cases.
2. Create/update handoff file — write the document to

   .claude/docs/ai/<feature-name>/api-handoff.md

   . Increment the iteration suffix (

   -v2

   ,

   -v3

   , …) if rerunning after feedback.
3. Paste template — fill every section below with concrete data. Omit subsections only when truly not applicable (note why).
4. Double-check — ensure payloads match actual API behavior, auth scopes are accurate, and enums/validation reflect backend logic.

Output Format

# API Handoff: [Feature Name]

## Business Context
[2-4 sentences: What problem does this solve? Who uses it? Why does it matter? Include any domain terms the frontend needs to understand.]

## Endpoints

### [METHOD] /path/to/endpoint
- **Purpose**: [1 line: what it does]
- **Auth**: [required role/permission, or "public"]
- **Request**:
  ```json
  {
    "field": "type — description, constraints"
  }

• Response (success):
  json

  {
    "field": "type — description"
  }

• Response (error): [HTTP codes and shapes, e.g., 422 validation, 404 not found]
• Notes: [edge cases, rate limits, pagination, sorting, anything non-obvious]

Data Models / DTOs

// Example shape for frontend typing
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

Enums & Constants

pending

Validation Rules

Business Logic & Edge Cases

• [Bullet each non-obvious behavior, constraint, or gotcha]
• [e.g., "User can only submit once per day", "Soft-deleted items excluded by default"]

Integration Notes

• Recommended flow: [e.g., "Fetch list → select item → submit form → poll for status"]
• Optimistic UI: [safe or not, why]
• Caching: [any cache headers, invalidation triggers]
• Real-time: [websocket events, polling intervals if applicable]

Test Scenarios

1. Happy path: [brief description]
2. Validation error: [what triggers it, expected response]
3. Not found: [when 404 is returned]
4. Permission denied: [when 403 is returned]

Open Questions / TODOs

---

## Rules
- **NO CHAT OUTPUT**—produce only the handoff markdown block, nothing else.
- Be precise: types, constraints, examples—not vague prose.
- Include real example payloads where helpful.
- Surface non-obvious behaviors—don't assume frontend will "just know."
- If backend made trade-offs or assumptions, document them.
- Keep it scannable: headers, tables, bullets, code blocks.
- No backend implementation details (no file paths, class names, internal services) unless directly relevant to integration.
- If something is incomplete or TBD, say so explicitly.

## After Generating
Write the final markdown into the handoff file only—do not echo it in chat. (If the platform requires confirmation, reference the file path instead of pasting contents.)