api-contract-init

name	api-contract-init
description	Generate API_CONTRACT.md by scanning existing routes and controllers
argument-hint	["shared|root — where to create the file"]

Generate an API_CONTRACT.md by scanning the real codebase. Never fabricate endpoints or types.

1. Detect the backend stack

File	Stack
package.json with @nestjs/core	NestJS
package.json with express/fastify	Express/Fastify
composer.json	CakePHP / Laravel
pyproject.toml or requirements.txt with django/fastapi/flask	Python
go.mod	Go
Cargo.toml with actix/axum/rocket	Rust
Gemfile with rails	Rails

2. Scan routes and controllers

Stack	Where to look
NestJS	*.controller.ts — decorators @Get, @Post, @Put, @Delete, @Patch
Express/Fastify	routes/**, router/** — router.get(), app.post(), etc.
CakePHP/Laravel	*Controller.php — public methods, routes/*.php
Django	urls.py — urlpatterns, ViewSet classes
FastAPI	*.py — @app.get, @router.post, etc.
Go	*_handler.go, *_router.go — HandleFunc, mux.Handle
Rails	config/routes.rb — resources, get/post/put/delete
Rust	routes/*.rs — handler functions, route macros

3. For each endpoint, extract

• HTTP method and path
• Request body / query params (from DTOs, structs, dataclasses, type annotations)
• Response type (if detectable)
• Auth requirement (if detectable)
• If a type cannot be determined, write // TODO: define type — NEVER fabricate

4. Generate the contract

Use this format:

# API Contract — [Project Name]

Source of truth for backend/frontend communication.

## Global Conventions
- Base URL: [detected or TODO]
- Auth: [detected or TODO]
- Response format: [detected or standard JSON]
- Error format: [detected or TODO]

## [Domain — grouped by controller/router]

### [METHOD] [path]

**Request:**
\`\`\`[lang]
[body type / query params]
\`\`\`

**Response:**
\`\`\`[lang]
[response type]
\`\`\`

**Auth:** [required/optional/none]
**Notes:** [if applicable]

---

## Changelog

| Date | Change | Side |
|------|--------|------|
| [today] | Initial generation from code | backend |

5. Placement

• If argument is shared or no argument: propose shared/API_CONTRACT.md
• If argument is root: propose API_CONTRACT.md at project root

Present the generated contract and wait for user validation before writing.