@jamie-tam/forge 6.0.0

package/skills/plan-architecture/SKILL.md

@@ -0,0 +1,457 @@
+---
+name: plan-architecture
+description: "Use when the user has an approved approach and asks for technical artifacts: API contracts, DB schemas, system diagrams, sequence diagrams, component layout. Triggers on 'design the API', 'sketch the architecture', 'data model', 'schema for', 'how should the components fit'. For prototype-driven work, harden produces architecture from the prototype — use this skill only for library/internal-tool/refactor work where prototype/wireframe phases were skipped."
+---
+
+# Plan Architecture
+
+**When this skill is the wrong fit:** v6 prototype-driven flow uses the `harden` skill at Phase 5 (codify) to extract architecture from a locked prototype — citation-bound, not invented. The architecture files land in `aiwiki/architecture/` and ADRs in `aiwiki/decisions/`. This skill is the non-prototype fallback that invents architecture upfront from an approved brainstorm; use it only when prototype/wireframe phases don't apply.
+
+**Boundary with plan-brainstorm:** Brainstorming produces a high-level design with no code. This skill translates that design into precise technical artifacts. Code examples in architecture artifacts (JSON schemas, SQL DDL, ASCII diagrams, type definitions) are specification artifacts, not implementation code. They define contracts that implementation must follow.
+
+**Announce at start:** "I'm using the plan-architecture skill to generate technical artifacts from the approved design."
+
+When this skill is invoked: do NOT proceed to task decomposition or implementation until all architecture artifacts are complete and have ZERO TBDs. Every endpoint, every schema column, every error code must be defined. Ambiguity here becomes bugs later. (The gate applies to this skill's flow; prototype-driven flow handles architecture differently via `harden`.)
+
+---
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `brainstorm-approved.md` (approved design — produced by `plan-brainstorm` in the non-prototype fallback flow). `codebase-analysis.md` (if existing project). `DESIGN.md` at project root (if frontend — from `plan-design-system`). |
+| **Produces** | `.forge/work/{type}/{name}/architecture/api-contract.md`, `.forge/work/{type}/{name}/architecture/db-schema.md`, `.forge/work/{type}/{name}/architecture/system-diagram.md`, `.forge/work/{type}/{name}/architecture/frontend-architecture.md` (if frontend) |
+| **Feeds into** | `plan-task-decompose`, `build-tdd`, `quality-test-plan` |
+| **Updates manifest** | `artifacts.api-contract`, `artifacts.db-schema`, `artifacts.system-diagram`, `artifacts.frontend-architecture` (if frontend) |
+
+---
+
+## Checklist
+
+Complete these steps in order:
+
+1. **Review approved design** -- read brainstorm-approved.md, codebase analysis, and DESIGN.md at project root (if frontend)
+2. **Generate API contracts** -- endpoints, methods, types, errors, auth
+3. **Generate DB schema** -- tables, columns, constraints, indexes, relationships
+4. **Generate system diagrams** -- ASCII format component and sequence diagrams
+5. **Generate frontend architecture** -- (if frontend) page shells, component boundaries, token implementation
+6. **Record architectural decisions** -- ADRs for every new pattern choice
+7. **Resolve all TBDs** -- no ambiguity allowed
+8. **User review** -- present artifacts for approval
+9. **Update feature manifest** -- record artifact paths and approval
+10. **Transition to task decomposition** -- invoke plan-task-decompose
+
+---
+
+## Agent Dispatch
+
+Dispatch the **architect** subagent (Opus) to generate the technical artifacts. The architect agent specializes in system design decisions, tradeoff analysis, and produces higher-quality architecture. The architect determines the appropriate depth of analysis based on the complexity of the design.
+
+---
+
+## Process
+
+### Step 1: Review Approved Design
+
+Read the inputs thoroughly before generating any artifacts:
+
+**From brainstorm-approved.md:**
+- Architecture overview -- what components exist, how they communicate
+- Data model -- entities, relationships, storage decisions
+- API design -- endpoints, interfaces, auth approach
+- Error handling strategy -- how errors propagate
+- Testing strategy -- what test types are needed
+
+**From codebase-analysis.md (if existing project):**
+- Existing API patterns -- follow them unless the design explicitly deviates
+- Existing database patterns -- ORM style, naming conventions, migration approach
+- Existing conventions -- naming, types, error handling patterns
+- Flagged risks -- address them in the architecture
+
+**From DESIGN.md at project root (if frontend feature):**
+- Design tokens (colors, typography, spacing) -- inform component contracts
+- Layout structure -- page shells, sidebar widths, breakpoints
+- Component conventions -- button sizes, input heights, card patterns
+
+**From decision log (aiwiki/decisions/):**
+- Prior architectural decisions that apply to this feature
+- Patterns already established that should be followed
+
+### Step 1.5: Codex Mode Check
+
+Now that the approved design and context are reviewed, run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation.
+
+- **Takeover:** Dispatch Codex with the design, codebase analysis, and decision log to generate API contracts, DB schema, and system diagrams. Claude reviews and writes ADRs.
+- **Verify** or **Skip / Codex unavailable:** Proceed with the steps below. Step 6.5 will dispatch Codex to verify Claude's architecture artifacts (Verify only).
+
+### Step 2: Generate API Contracts
+
+Write comprehensive API contracts to `.forge/work/{type}/{name}/architecture/api-contract.md`.
+
+Use `templates/api-contract.md` as the format. For each endpoint, the contract MUST define: purpose, auth, rate limiting, full request schema (with per-field type + constraints), success response shape, and all applicable error codes with response schema.
+
+Rules for API contracts:
+
+- **No vague types.** Never use "object", "any", "mixed", or "data". Every field has a specific type.
+- **Every endpoint has error responses.** At minimum: 400, 401, 404, 500. Add 403, 409, 422 where applicable.
+- **Every field has constraints.** String length limits, numeric ranges, enum values, format patterns.
+- **Pagination defined.** If an endpoint returns lists, define the pagination contract (cursor vs offset, page size limits, response envelope).
+- **Versioning noted.** If the project uses API versioning, specify the version.
+- **Follow existing patterns.** If the codebase analysis found a specific API style, match it exactly.
+
+### Step 2b: Verify External Service Contracts
+
+For every external service the system integrates with (STT, LLM, payment APIs, third-party SDKs, etc.):
+
+1. **Identify** all external services from the brainstorm-approved design
+2. **Attempt automated connectivity** — hit a read-only or idempotent endpoint (health check, GET, list) with a 5-second timeout. Never call endpoints that create resources, trigger payments, or have side effects.
+3. **If reachable** — compare the actual response structure (field names, types, nesting) against what you are writing in the contract. **If there is a mismatch, update the contract to match reality — not the other way around.**
+4. **If not reachable** — verify the API contract via official documentation (context7 MCP or web search). Document the source of truth.
+5. **Record in the contract** which endpoints were verified by real call vs documentation only:
+
+```markdown
+## External Service Verification
+
+| Service | Endpoint | Verified By | Response Shape Confirmed |
+|---|---|---|---|
+| Payment API | POST /v1/charges | Real call ✓ | response shape confirmed |
+| Email Service | POST /v3/mail/send | Documentation only | sendgrid.com/docs |
+```
+
+**Why:** Wrong contracts produce wrong mocks, which produce passing tests against a broken integration. A single real call here catches mismatches before any implementation code is written.
+
+### Step 3: Generate DB Schema
+
+Write database schema changes to `.forge/work/{type}/{name}/architecture/db-schema.md`.
+
+Use `templates/db-schema.md` as the format. Every table needs: columns (type, nullability, default), indexes, foreign keys (with ON DELETE/UPDATE), and constraints.
+
+Rules for DB schema:
+
+- **Every column has a type, nullability, and default.** No ambiguity.
+- **Every foreign key has ON DELETE and ON UPDATE behavior.** CASCADE, RESTRICT, SET NULL -- choose explicitly.
+- **Indexes for every foreign key.** And for columns used in WHERE, ORDER BY, or JOIN clauses.
+- **Unique constraints documented.** What combinations must be unique?
+- **Migration direction.** Note whether this is a new table, adding columns, or modifying existing columns.
+- **Data migration notes.** If existing data needs transformation, document the strategy.
+- **Follow existing conventions.** If the codebase uses snake_case table names, follow suit. If it uses a specific ORM, match its conventions.
+
+### Step 4: Generate System Diagrams
+
+Write ASCII diagrams to `.forge/work/{type}/{name}/architecture/system-diagram.md`.
+
+Use `templates/system-design.md` for complex multi-service architectures. Use ASCII box-and-arrow diagrams:
+
+```
+┌────────┐     ┌─────┐     ┌─────────┐     ┌────────────┐
+│ Client │────>│ API │────>│ Service │────>│ Database   │
+└────────┘     └─────┘     └────┬────┘     └────────────┘
+                                │
+                                v
+                         ┌──────────────┐
+                         │ External API │
+                         └──────────────┘
+```
+
+At minimum: component diagram for structure, sequence diagram for flows touching 3+ components, ER diagram if DB changes exist.
+
+Rules for diagrams:
+
+- **At least one component diagram.** Shows how the new feature fits in the system.
+- **Sequence diagrams for complex flows.** If an operation touches 3+ components, diagram it.
+- **ER diagram if DB changes exist.** Shows relationships between tables.
+- **Label all connections.** Arrows without labels are meaningless.
+- **Keep it readable.** Maximum ~15 nodes per diagram. Split into multiple diagrams if needed.
+- **ASCII only.** Diagrams must be readable in any context — terminal, editor, agent prompt, GitHub.
+
+### Step 4.5: Generate Frontend Architecture (Frontend Features Only)
+
+If `DESIGN.md` exists at the project root, write frontend architecture to `.forge/work/{type}/{name}/architecture/frontend-architecture.md`. This captures the technical consequences of the visual direction — how the design tokens are realized structurally in code.
+
+**Contents:**
+
+- **Page and layout shell structure** — which components own the page-level layout (header, sidebar, main content area), how they compose, responsive behavior at each breakpoint from DESIGN.md
+- **Component boundaries and shared primitives** — which components are shared (Button, Card, Input), which are page-specific, component hierarchy
+- **Token implementation strategy** — how design tokens from DESIGN.md become code: CSS custom properties, Tailwind config values, theme provider, or styled-components theme object
+- **CSS framework integration** — how the chosen framework (from DESIGN.md) integrates with the component tree: utility classes, CSS modules scope, styled-components ThemeProvider
+- **State ownership for UI concerns** — which components own theme state, sidebar collapse, responsive breakpoint detection, modal stacking
+- **Accessibility constraints** — ARIA landmark structure, focus management strategy, keyboard navigation flow across page shells
+
+If no `DESIGN.md` exists (backend-only feature), skip this step.
+
+### Step 5: Record Architectural Decisions
+
+For every new pattern choice, technology selection, or significant design decision, create an Architecture Decision Record (ADR) in `aiwiki/decisions/`.
+
+Use the template from `templates/adr-template.md` if available. ADR format:
+
+```markdown
+# ADR-{number}: {Title}
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+**Feature:** {feature name}
+
+## Context
+{What is the issue that we're seeing that is motivating this decision?}
+
+## Decision
+{What is the change that we're proposing and/or doing?}
+
+## Consequences
+
+### Positive
+- {Benefit 1}
+- {Benefit 2}
+
+### Negative
+- {Tradeoff 1}
+- {Tradeoff 2}
+
+### Neutral
+- {Side effect that is neither positive nor negative}
+
+## Alternatives Considered
+{Brief summary of alternatives and why they were rejected}
+```
+
+Rules for ADRs:
+
+- **One ADR per decision.** Do not bundle unrelated decisions.
+- **Number sequentially.** Check existing ADRs and increment.
+- **Reference from architecture docs.** API contracts and schemas should link to relevant ADRs.
+- **Decisions are immutable.** If a decision is reversed, create a new ADR that supersedes the old one. Never edit a past ADR.
+- **Every new pattern choice gets an ADR.** Choosing a validation library, selecting a caching strategy, picking a pagination approach -- these all merit ADRs.
+
+### Step 6: Resolve All TBDs
+
+Before presenting artifacts to the user, scan every document for:
+
+- "TBD", "TODO", "TBC", "to be determined", "to be decided"
+- Placeholder values ("xxx", "???", "FIXME")
+- Vague language ("some kind of", "probably", "might need")
+
+**Every instance must be resolved.** If you cannot resolve it from the approved design, ask the user:
+
+> "I found an unresolved decision in the architecture: {description}. Before I can finalize, I need to know: {specific question with options}."
+
+Do not proceed to user review with any TBDs remaining.
+
+### Step 6.5: Critic Review of Architecture
+
+Before presenting architecture artifacts to the user, dispatch the **critic** subagent (Opus) to review all artifacts for completeness, feasibility, and gaps. Provide the critic with the brainstorm-approved design, the generated API contracts, DB schema, system diagrams, and decision records.
+
+If the critic identifies gaps or TBDs, resolve them before proceeding to user review.
+
+**Codex Verify:** Check the mode recorded at Step 1.5. If **Verify** was selected, dispatch Codex alongside the critic to review artifacts for internal consistency, feasibility gaps, missing error cases, and scalability concerns. If **Takeover** was selected, skip this step (Codex already generated the artifacts). If **Skip**, do nothing. Do NOT re-run the consent flow.
+
+#### Graphify Context (Optional)
+
+**Protocol:** `protocols/graphify.md` | **Guard:** Run the status check from the protocol before Step 1.
+
+Graph communities map directly to bounded contexts, and god nodes identify components needing explicit interface contracts.
+
+**How graph data maps to this skill:**
+- **Communities** → candidate bounded contexts when defining component boundaries
+- **God nodes** → components that need explicit interface contracts
+- **Community boundaries** → proposed component boundaries should align with graph communities
+
+**CLI queries** (if graph exists and CLI available):
+- `graphify query "how does [subsystem A] connect to [subsystem B]" --budget 1500 --graph graphify-out/graph.json` — verify proposed component boundaries match actual dependencies
+
+**Codex bridge:** Pass community-informed architecture context to the Codex verify step below.
+
+#### Codex Integration
+
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude generates architecture artifacts, Codex reviews for gaps.
+- **Takeover:** Codex generates API contracts and DB schema, Claude reviews and generates diagrams/ADRs.
+
+**When:** Step 6.5 — after architecture artifacts are generated, alongside the critic review (sequential, not parallel).
+
+**Context to pass:**
+- Path to `brainstorm-approved.md`
+- Path to `architecture/api-contract.md`
+- Path to `architecture/db-schema.md`
+- Path to `architecture/system-diagram.md`
+- Path to `architecture/frontend-architecture.md` (if present)
+
+**What Codex reviews:**
+- Internal consistency (API shapes match DB columns, diagrams match contracts)
+- Feasibility gaps (hand-waving over hard problems)
+- Missing error cases or edge conditions
+- Scalability concerns not addressed
+
+**Prompt focus:** "Review these architecture artifacts against the approved design. Check internal consistency, missing error cases, and feasibility gaps. Report specific inconsistencies with file paths and line references."
+
+**Presentation:** Present alongside Claude critic findings. Highlight any disagreements between critics.
+
+### Step 7: User Review
+
+Present all artifacts to the user for review:
+
+> "Architecture artifacts generated:
+>
+> 1. **API Contract** -- `.forge/work/{type}/{name}/architecture/api-contract.md`
+>    - {N} endpoints defined
+>    - All error responses specified
+>
+> 2. **DB Schema** -- `.forge/work/{type}/{name}/architecture/db-schema.md`
+>    - {N} tables ({new/modified})
+>    - {N} indexes, {N} foreign keys
+>
+> 3. **System Diagrams** -- `.forge/work/{type}/{name}/architecture/system-diagram.md`
+>    - Component diagram showing {scope}
+>    - Sequence diagrams for {key flows}
+>
+> 4. **Frontend Architecture** (if frontend) -- `.forge/work/{type}/{name}/architecture/frontend-architecture.md`
+>    - Page shells, component boundaries, token implementation strategy
+>
+> 5. **Decisions** -- {N} ADRs recorded in `aiwiki/decisions/`
+>
+> Please review these artifacts. API contracts in particular will become the binding specification for implementation -- any issues should be caught now."
+
+Wait for user approval. If changes are requested, make them and re-present.
+
+### Step 8: Update Feature Manifest
+
+After approval, update `.forge/work/{type}/{name}/manifest.yaml`:
+
+```yaml
+artifacts:
+  api-contract:
+    path: architecture/api-contract.md
+    status: approved
+    approved_at: YYYY-MM-DD
+    endpoint_count: N
+  db-schema:
+    path: architecture/db-schema.md
+    status: approved
+    approved_at: YYYY-MM-DD
+    table_count: N
+    new_tables: N
+    modified_tables: N
+  system-diagram:
+    path: architecture/system-diagram.md
+    status: approved
+    approved_at: YYYY-MM-DD
+    diagram_count: N
+decisions:
+  - ADR-{N}: {title}
+```
+
+### Step 9: Transition
+
+After the user approves all artifacts, architecture is complete. The calling command determines the next step.
+
+---
+
+## Key Rules
+
+1. **API contracts are BINDING.** Once approved, they are the source of truth for implementation. Subagents implement exactly what the contract specifies. Changes require re-approval.
+2. **NO TBDs allowed.** Every field, every type, every error code must be defined before proceeding. Ambiguity in architecture becomes bugs in implementation.
+3. **Every new pattern goes in the decision log.** Choosing a library, defining an error format, selecting a pagination approach -- all merit an ADR.
+4. **Reference existing conventions.** If codebase-analysis found specific patterns (naming, types, error handling), the architecture MUST follow them unless the approved design explicitly deviates.
+5. **Diagrams use ASCII.** Renders in GitHub, VS Code, and documentation tools without additional tooling.
+6. **Error responses are mandatory.** Every endpoint must define its error responses. "Happy path only" contracts are incomplete.
+7. **Constraints on every field.** String length, numeric range, enum values, format patterns. No unbounded types.
+8. **Follow existing DB conventions.** If the project uses an ORM, match its naming and type conventions.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Is Wrong | What To Do Instead |
+|---|---|---|
+| **Leaving endpoints undefined** | Implementors will guess, and guess differently | Define every endpoint completely |
+| **Using vague types** | "object" and "any" are not types | Specify exact shape with field types |
+| **Skipping error responses** | Errors are the majority of real-world API traffic | Define every error: status, code, message, when |
+| **No constraints on fields** | "string" allows empty strings, SQL injection, 10MB payloads | Add length limits, format patterns, allowed values |
+| **TBDs in delivered artifacts** | "We'll figure it out during implementation" means rework | Resolve everything before handoff |
+| **Ignoring existing patterns** | New API style in an old codebase creates maintenance debt | Match existing patterns from codebase analysis |
+| **Monolithic diagrams** | 50-node diagram is unreadable | Split into focused diagrams, max ~15 nodes each |
+| **Decisions without ADRs** | Future developers won't know why choices were made | Record every significant decision |
+
+---
+
+## Artifact Dependencies
+
+```
+brainstorm-approved.md ─────────────────────────────────────┐
+        |                                                   |
+        +── api-contract.md (endpoints, types, errors)      |
+        |                                                   |
+        +── db-schema.md (tables, columns, indexes)         |
+        |                                                   |
+        +── system-diagram.md (component, sequence, ER)    |
+        |                                                   |
+        +── aiwiki/decisions/ADR-*.md (one per decision)    |
+        |                                                   |
+DESIGN.md at project root (if frontend) ────────────────────┤
+        |                                                   |
+        +── frontend-architecture.md (page shells,          |
+            component boundaries, token implementation)     |
+        |                                                   |
+        v                                                   v
+    plan-task-decompose (consumes all of the above)
+```
+
+All architecture artifacts must be internally consistent:
+
+- API response shapes must match DB schema columns
+- Sequence diagrams must match API contract endpoints
+- ER diagrams must match DB schema tables and relationships
+- ADRs must align with choices made in contracts and schemas
+
+---
+
+## Handling Special Cases
+
+### No Database Changes
+
+If the feature does not require DB changes, skip the db-schema.md artifact and note in the manifest:
+
+```yaml
+artifacts:
+  db-schema:
+    status: not-applicable
+    reason: "Feature does not require database changes"
+```
+
+### No API Changes
+
+If the feature is purely internal (background job, refactoring, etc.), skip the api-contract.md and note in the manifest:
+
+```yaml
+artifacts:
+  api-contract:
+    status: not-applicable
+    reason: "Feature does not expose new API endpoints"
+```
+
+### Existing API Modifications
+
+If modifying existing endpoints, document both the current and new state:
+
+```markdown
+### PUT /api/users/{id} (MODIFIED)
+
+**Change:** Adding `role` field to request and response
+
+**Current request body:**
+{existing shape}
+
+**New request body:**
+{new shape with additions highlighted}
+
+**Migration:** Backward compatible -- `role` is optional with default 'member'
+```
+
+### Complex Multi-Service Architecture
+
+If the feature spans multiple services:
+1. Create separate API contract sections per service
+2. Document inter-service communication (sync vs async, protocol, error handling)
+3. Sequence diagrams for cross-service flows
+4. Note deployment order dependencies

package/skills/plan-architecture/templates/adr-template.md

@@ -0,0 +1,52 @@
+# ADR-{number}: {Title}
+
+## Status
+
+{Proposed / Accepted / Deprecated / Superseded}
+
+{If superseded: Superseded by [ADR-{number}](./ADR-{number}.md)}
+
+## Date
+
+{YYYY-MM-DD}
+
+## Context
+
+{What is the issue that we are seeing that is motivating this decision or change? What is the technical, business, or project context? What constraints exist?}
+
+## Decision
+
+{What is the change that we are proposing and/or doing? State the decision clearly and concisely.}
+
+## Consequences
+
+### Positive
+- {Benefit 1}
+- {Benefit 2}
+- {Benefit 3}
+
+### Negative
+- {Cost or downside 1}
+- {Cost or downside 2}
+
+### Neutral
+- {Side effect or observation that is neither good nor bad}
+
+## Alternatives Considered
+
+### Alternative 1: {name}
+- **Description**: {what this alternative would look like}
+- **Pros**: {advantages}
+- **Cons**: {disadvantages}
+- **Why rejected**: {specific reason this was not chosen}
+
+### Alternative 2: {name}
+- **Description**: {what this alternative would look like}
+- **Pros**: {advantages}
+- **Cons**: {disadvantages}
+- **Why rejected**: {specific reason this was not chosen}
+
+## References
+
+- {Link to relevant documentation, discussion, or research}
+- {Link to prototype or proof of concept if applicable}

package/skills/plan-architecture/templates/api-contract.md

@@ -0,0 +1,99 @@
+# API Contract
+
+## Endpoint: {METHOD} {/path}
+
+### Description
+{What this endpoint does in one sentence.}
+
+### Authentication
+- **Required**: Yes / No
+- **Method**: Bearer token / API key / Session cookie / None
+- **Permissions**: {required roles or scopes}
+
+### Request
+
+#### Headers
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | Yes | Bearer {token} |
+| Content-Type | Yes | application/json |
+| X-Request-ID | No | Client-generated request ID for tracing |
+
+#### Path Parameters
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| {param} | {type} | {description} |
+
+#### Query Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| {param} | {type} | {Yes/No} | {default} | {description} |
+
+#### Request Body
+```json
+{
+  "field_name": "string — Description of this field",
+  "nested_object": {
+    "inner_field": "number — Description of this field"
+  },
+  "optional_field?": "string — This field is optional"
+}
+```
+
+**Validation Rules**:
+- `field_name`: {min/max length, format, allowed values}
+- `nested_object.inner_field`: {range, constraints}
+
+### Response
+
+#### Success Response (200 / 201)
+```json
+{
+  "data": {
+    "id": "uuid — Unique identifier",
+    "field_name": "string — Description",
+    "created_at": "ISO 8601 timestamp"
+  }
+}
+```
+
+#### Error Responses
+
+| Status | Error Code | Description | Response Body |
+|--------|-----------|-------------|---------------|
+| 400 | VALIDATION_ERROR | Invalid request body | `{"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [{"field": "...", "issue": "..."}]}}` |
+| 401 | UNAUTHORIZED | Missing or invalid auth token | `{"error": {"code": "UNAUTHORIZED", "message": "..."}}` |
+| 403 | FORBIDDEN | Insufficient permissions | `{"error": {"code": "FORBIDDEN", "message": "..."}}` |
+| 404 | NOT_FOUND | Resource does not exist | `{"error": {"code": "NOT_FOUND", "message": "..."}}` |
+| 409 | CONFLICT | Resource already exists | `{"error": {"code": "CONFLICT", "message": "..."}}` |
+| 429 | RATE_LIMITED | Too many requests | `{"error": {"code": "RATE_LIMITED", "message": "...", "retry_after": 60}}` |
+| 500 | INTERNAL_ERROR | Server error | `{"error": {"code": "INTERNAL_ERROR", "message": "..."}}` |
+
+### Example
+
+#### Request
+```bash
+curl -X {METHOD} {base_url}{/path} \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "field_name": "example value"
+  }'
+```
+
+#### Response
+```json
+{
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "field_name": "example value",
+    "created_at": "2025-01-15T10:30:00Z"
+  }
+}
+```
+
+---
+
+## Endpoint: {METHOD} {/next-path}
+
+{Repeat the same structure for each endpoint.}