/meta-planning-api-planning

name: meta-planning-api-planning
description: Backend specification planning frameworks. Use when a spec touches API endpoints, database schema, middleware, or auth. Covers endpoint contracts with request/response shapes, error catalogs, auth per endpoint, schema design with constraints and indexes, migration strategy, and middleware pipeline ordering.

API Planning Frameworks

> **Quick Guide:** Specify every endpoint as a complete contract — method, path, auth requirement, request shape, success response, and an error catalog with a status per condition. Specify schema as exact columns with constraints, relationships, indexes, and a migration strategy. Order the middleware pipeline explicitly. Apply a framework only when the spec touches its artifact class — an endpoint-only change needs no schema section.

---

<critical_requirements>

CRITICAL: Before Specifying Backend Contracts

> **All specifications must be grounded in the codebase's real routes, schemas, and middleware** — reference specific files with line numbers

**(You MUST give every endpoint a complete contract: method, path, auth requirement, request shape, success response shape, and an error catalog)**

**(You MUST state the auth requirement per endpoint — which middleware, which permission — never "endpoints should be protected")**

**(You MUST specify schema as exact columns with types, constraints, relationships, indexes, and a migration strategy)**

**(You MUST catalog error responses per endpoint — a status code per condition with its response body shape)**

**(You MUST apply each framework only when the spec touches its artifact class — an unused section is omitted, never filled)**

</critical_requirements>

---

**Auto-detection:** API spec, endpoint design, REST contract, request response shape, database schema spec, migration plan, middleware ordering, auth requirements, error catalog

**When to use:**

• Specifying new or changed API endpoints (request/response contracts)
• Specifying database tables, columns, relationships, or indexes
• Specifying auth and permission requirements per endpoint
• Specifying middleware pipelines and their ordering
• Specifying error response catalogs
• Planning migrations (reversibility, data migration, downtime)

**When NOT to use:**

• When implementing backend code (use the relevant API implementation skill)
• For the frontend that consumes the API (use the web planning skill)
• For model-calling capabilities behind an endpoint (use the ai planning skill)
• For the planning PROCESS itself — research, scope fencing, success criteria — which the PM agent carries

**Key patterns covered:**

• Endpoint contract completeness (method, path, auth, shapes, errors)
• Auth specification per endpoint
• Error response catalogs
• Database schema design (columns, constraints, relationships, indexes)
• Migration strategy
• Middleware pipeline ordering
• Consumer-contract awareness (who breaks on change)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Per-artifact spec section templates and a worked example specification

---

<philosophy>

Philosophy

**An API contract is a promise to consumers you cannot see.** Frontends, other services, and external clients all code against the shapes and status codes the spec defines. An ambiguous contract does not stay ambiguous — it gets resolved differently by the implementer and each consumer.

**When specifying backend work:**

• Read the closest existing route first; its naming, middleware chain, and response envelope are the vocabulary the spec must reuse
• Name the downstream consumers of every contract, and what breaks for each if the shape changes
• Specify the error catalog with the same care as the success path — consumers branch on status codes
• Treat the schema as a contract too: a column without constraints is a decision deferred to whoever writes the migration

**When NOT to specify:**

• Don't add endpoints beyond the smallest set that achieves the goal
• Don't design schema columns for data no requirement names
• Don't invent new middleware when an existing chain covers the requirement
• Don't specify implementation (handler bodies, ORM calls) — contracts and schemas, not code

**Core principles:**

• **Auth is per endpoint**: "protected" is not a specification; the middleware and permission are
• **Errors are a catalog**: every condition a consumer can hit has a status code and a body shape
• **Schema constraints are requirements**: nullable, unique, and FK decisions belong in the spec
• **Migrations are planned, not improvised**: reversibility, data migration, and downtime are stated up front

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Endpoint Contract Completeness

Every endpoint the spec introduces or changes carries all six parts.

## Endpoint Contract

For EACH endpoint:

- [ ] Method and exact path, with path parameters named (`GET /api/v1/users/:userId`)
- [ ] Auth requirement: middleware name + permission/role, or explicitly public
- [ ] Rate limit, or explicitly none
- [ ] Request shape: every parameter with location (path/query/body), type, required flag, constraints
- [ ] Success response: status code and exact body shape with field types
- [ ] Error catalog: a row per condition (see Pattern 3)

BAD:  "Create an endpoint for user management"
GOOD: "GET /api/v1/users — paginated list with cursor-based pagination following
       routes/jobs.ts:45-67. Response shape matches JobListResponse."

**Why this matters:** each missing part becomes an invention. An invented pagination style or response envelope diverges from the codebase's own, and consumers inherit the inconsistency permanently.

---

Pattern 2: Auth Per Endpoint

State the requirement per endpoint, naming real middleware.

BAD:  "Endpoints should be protected"
GOOD: "GET /api/v1/users requires authMiddleware. DELETE /api/v1/users/:id requires
       authMiddleware + adminGuard.