fe-api-handoff

# Frontend API handoff Produce one instruction file that lets a frontend developer/agent implement support for this branch's backend changes **without reading the backend diff**. The file is the deliverable; the chat gets only a short recap and the path. You run in a forked, isolated context. Read and diff freely — only your final short summary reaches the main conversation, and the file write lands at `/tmp/fe-api-handoff/<branch>.html`. ## Scope — API facts only Every statement in the file is a fact about **what the backend now accepts or returns**. You describe the contract; you do not tell the frontend how to build against it. **In scope:** request/response field names, types, nullability, defaults; endpoint paths + HTTP methods; validation rules the server enforces; HTTP status codes + error `code` strings; new/changed enum values and exposed constants; the overall backend behavior a FE dev needs as context. **Out of scope — never write these:** anything about rendering, forms, buttons, disabling controls, showing warnings, layout, grouping/sorting *for display*, or "the UI should…". No UI/UX design judgment of any kind. **Conversion rule** — when you catch yourself writing frontend behavior, restate it as the underlying API fact and drop the rest: - ✗ "The UI should show an inline validation error on the condition field." → ✓ "`POST`/`PUT` reject a malformed `condition` with `400 VALIDATION_ERROR`." - ✗ "The UI must always resend `multiTurnId` since PUT is a full replacement." → ✓ "`PUT` is a full replacement: `multiTurnId`/`turnIndex` omitted from the body are cleared." - ✗ "Group by `(traceId, runIndex)` to render a multi-turn." → ✓ "All turns of one multi-turn run share a `traceId`; each turn is a separate row with its own `turnIndex`." The recipe below has no slot for UI/UX prose. If a sentence doesn't fit a slot, it doesn't belong. ## Steps 1. **Find the changes.** `git diff --stat development...HEAD` for the map, then `git diff development...HEAD` on the surfaces that define the contract: - `web.controller` / `query.web` — routes, methods, params, status codes - `service.domain.dto`, `service.domain.dto.analytics` — request/response DTO fields, `@Schema`, validation annotations, nullability - `constants`, enums — exposed constant/enum values - `web.handler` + `service.domain.exception` — error `code` strings and their HTTP status - `src/main/resources/openapi/examples/**` — concrete request/response shapes 2. **Get context, but derive facts from code.** For an opsx branch, read the change proposal(s) under `openspec/changes/*/proposal.md` and relevant `AGENTS.md` inline conventions for the *why*. Always confirm each contract fact against the actual DTO/controller/example — prose can lag the code. 3. **Write the file** to `/tmp/fe-api-handoff/<branch>.html` (sanitize `/` → `-` in the branch name; `mkdir -p /tmp/fe-api-handoff` first) using the template below. 4. **Return to chat**: 3–8 bullet highlights of the biggest contract changes + the absolute file path. Do NOT paste the file contents. ## Output template One `<important>` block wrapping raw semantic HTML. **No** `style=`, `<style>`, `class=`, CSS, or markdown — structure only. ```html <important> <h1>Frontend API handoff — <branch> (vs development)</h1> <h2>Overall context</h2> <p>What this change does at the backend level and why it exists — 1–3 short paragraphs. Enough for a FE dev to understand the feature. Facts only, no UI recommendations.</p> <h2>API contract changes</h2> <h3>[NEW|CHANGED|REMOVED] METHOD /api/v1/path/{param}</h3> <p>One line: what this endpoint does and what changed.</p> <h4>Request</h4> <ul> <li><code>fieldName</code> — type, nullable?, default, constraint (e.g. "String, max 2000, nullable"). Mark NEW/CHANGED/REMOVED.</li> </ul> <h4>Response (200/201)</h4> <ul> <li><code>fieldName</code> — type, nullable?, when present/omitted. Mark NEW/CHANGED/REMOVED.</li> </ul> <h4>Status codes &amp; errors</h4> <ul> <li><code>409 CONFLICT</code> — condition that triggers it.</li> </ul> <!-- repeat one <h3> block per changed endpoint --> <h2>Enums &amp; constants</h2> <ul> <li><code>NAME</code> = value — where it surfaces in the API.</li> </ul> <h2>Error-code reference</h2> <table> <tr><th>Scenario</th><th>HTTP</th><th>code</th></tr> <tr><td>...</td><td>400</td><td>VALIDATION_ERROR</td></tr> </table> </important> ``` Omit a section only if this branch genuinely has nothing for it (e.g. no enum changes). Every changed endpoint gets its own `<h3>` block; do not collapse several endpoints into prose. ## Red flags — stop and fix before writing - A sentence containing "UI", "user", "display", "render", "form", "button", "should show" → convert to an API fact or delete. - You're about to print the HTML into the chat instead of the file → write the file; chat gets highlights + path only. - Output is markdown, or HTML with `style`/`class`/CSS → strip to raw semantic tags inside one `<important>` block. - A contract fact taken from a spec/proposal you didn't confirm against a DTO/controller/example → verify it.