@khanhspring/forge-spec 1.0.0

package/forge-contract/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: "forge-contract"
+description: "Phase 4 of 4. Researches existing contracts for patterns, clarifies ambiguous API design decisions, challenges against REST best practices, then generates a multi-file Specmatic-compatible OpenAPI 3.0 contract on confirmation."
+argument-hint: "Feature slug (e.g. 'user-registration')"
+compatibility: "Requires spec repo with .forge/project.json, features/{slug}/spec.md, and features/{slug}/tasks.md"
+metadata:
+  author: "forge-workflow"
+  source: "spec-skills/forge-contract/SKILL.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Forge Contract
+
+Phase 4 of 4. Understand the API design fully before writing any YAML.
+Research existing contracts, surface ambiguities, challenge against best practices —
+then generate a contract that implementors and consumers can trust.
+
+<HARD-GATE>
+Do NOT write any contract files until you have presented a contract outline
+and the user has explicitly confirmed it.
+</HARD-GATE>
+
+---
+
+## Pre-check
+
+- Feature slug from $ARGUMENTS, or ask: "Which feature do you want to generate a contract for?"
+- Read `features/{slug}/spec.md` — must exist, otherwise stop.
+- Read `features/{slug}/tasks.md` — must exist, otherwise say "Run `/forge-tasks {slug}` first."
+- Read `.forge/project.json` — get module names, ports, stacks.
+
+---
+
+## Step 1 — Research Context
+
+Before asking anything, research silently:
+
+1. **Existing contracts for this module** — scan `contracts/{module}/` for existing YAML files.
+   Note: field naming convention (camelCase vs snake_case), URL prefix, existing shared schemas,
+   existing error format, auth patterns, pagination shape.
+
+2. **Shared schemas** — does `contracts/{module}/shared/` exist with `api-error.yaml`,
+   `pagination-meta.yaml`, or other reusables? If yes, `$ref` to them — do not redefine.
+
+3. **Other module contracts in this feature** — any sibling modules with contracts already written?
+   Note shared data models for consistency.
+
+4. **Related feature contracts** — earlier features for the same module with schemas to extend
+   (e.g. an existing `UserResponse` that this feature adds fields to).
+
+5. **Spec API endpoint list** — extract every endpoint from `spec.md` API Endpoints table.
+
+6. **Tasks** — extract `[api]` tagged tasks per backend module from `tasks.md`.
+
+Report findings:
+
+> "Here's what I found:
+> - Existing contracts: {files or 'none yet'}
+> - Shared schemas available: {list or 'none — will create'}
+> - Reusable schemas: {e.g. 'UserResponse in user-auth.yaml' or 'none'}
+> - Endpoints to contract: {list}
+> - Convention: {camelCase/snake_case, /api/v1/ prefix, etc.}
+> - Conflicts: {any mismatch or 'none'}"
+
+---
+
+## Step 2 — Clarifying Questions (one at a time)
+
+Ask ONE question at a time. Only ask about genuine ambiguities not answered by spec or existing contracts.
+
+- **HTTP method** — PUT (full replace) or PATCH (partial update)? POST with server ID or PUT with client ID?
+- **Sync vs async** — immediate result (201) or acknowledged and processed later (202)?
+- **Pagination** — which list endpoints need it? page+size, cursor, or offset?
+- **Field types** — IDs: UUID or string? Dates: date-time or date? Enum values?
+- **Required vs optional** — which request fields are mandatory?
+- **Auth scope** — all endpoints require bearer, or are some public?
+- **Error cases** — 403 Forbidden distinct from 401? 409 Conflict needed? 422 for business rules?
+
+Use the research flag for anything needing external investigation:
+> "🔍 **Research needed:** {what's unclear}. (a) pause, (b) assume, or (c) flag and move on?"
+
+Skip if all decisions are clear.
+
+---
+
+## Step 3 — Challenge Round
+
+Flag at least 2 best-practice concerns specific to this feature before drafting:
+
+> "Before the outline, a couple of things to flag:
+>
+> **[Concern 1]:** {e.g. 'The spec says GET /users — list endpoints need pagination.
+> Should I add page+size query params and a paginated response wrapper?'}
+>
+> **[Concern 2]:** {e.g. 'The spec says "update user" — is this a full replace (PUT)
+> or partial update (PATCH)? PATCH is safer for partial updates and what the spec implies.'}
+>
+> How should these be handled?"
+
+Wait for resolution before the outline.
+
+---
+
+## Step 4 — Contract Outline & Gate
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Contract Outline: {feature-slug}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Module: {module}  Port: {port}
+
+FILES TO GENERATE
+  contracts/{module}/{slug}.yaml        ← main contract
+  contracts/{module}/schemas/
+    create-{resource}-request.yaml
+    update-{resource}-request.yaml      ← if update endpoint
+    {resource}-response.yaml            ← for GET single
+    {resource}-summary.yaml             ← for GET list items
+    {resource}-reference.yaml           ← for POST 201 response
+    enums/{resource}-status.yaml        ← if status/type enum
+  contracts/{module}/shared/            ← create if not exists
+    api-error.yaml
+    api-error-detail.yaml
+    pagination-meta.yaml                ← if list endpoint
+
+ENDPOINTS
+  POST /api/v1/{resources}
+    Auth: bearer
+    Request:  Create{Resource}Request (no id, no timestamps)
+    201:      {Resource}Reference (id: uuid only)
+    400:      ApiError (with details[])
+    401:      ApiError
+    409:      ApiError  ← if duplicate possible
+
+  GET /api/v1/{resources}
+    Auth: bearer
+    Query: page: int, size: int, sort: string, order: asc|desc
+    200:  { data: {Resource}Summary[], pagination: PaginationMeta }
+    401:  ApiError
+
+  GET /api/v1/{resources}/{id}
+    Auth: bearer
+    200:  {Resource}Response (full object)
+    401:  ApiError
+    404:  ApiError
+
+  PATCH /api/v1/{resources}/{id}
+    Auth: bearer
+    Request: Update{Resource}Request (all fields optional)
+    204:  (no body)
+    400:  ApiError (with details[])
+    401:  ApiError
+    403:  ApiError  ← if ownership check
+    404:  ApiError
+
+  DELETE /api/v1/{resources}/{id}
+    Auth: bearer
+    204:  (no body)
+    401:  ApiError
+    403:  ApiError
+    404:  ApiError
+
+ASSUMPTIONS
+  - {any recorded assumption}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+> "Does this outline look right? Say **yes** to generate, or tell me what to change."
+
+---
+
+## Step 5 — Generate the contract files
+
+Now read both reference files in this skill's folder:
+- `reference/best-practices.md` — schema segregation, HTTP methods, status codes, the
+  `ApiError` / `ApiErrorDetail` / `PaginationMeta` shared schemas, enum rules, naming conventions
+- `reference/contract-template.yaml` — the main-contract skeleton (paths + `components/responses`)
+
+Then generate every file from the approved outline:
+1. The main contract `contracts/{module}/{slug}.yaml` — use the template skeleton, keeping only
+   `info` + `paths` + `$ref`s (no inline schemas).
+2. One file per schema under `schemas/` (and `schemas/enums/` for enums), per the segregation table.
+3. The `shared/` files (`api-error.yaml`, `api-error-detail.yaml`, `pagination-meta.yaml`) —
+   only if they don't already exist for this module (reuse if present, per Step 1 research).
+
+Apply every rule in `best-practices.md`. Hard requirements:
+- Every endpoint has at least one `examples` block (Specmatic needs them for stubs)
+- `operationId` unique across the file; relative `$ref` paths only
+- Match the field naming convention found in Step 1 (camelCase vs snake_case)
+- Create endpoint → 201 + `Location` header + `{Resource}Reference` (id only); update/delete → 204 no body
+
+---
+
+## Step 6 — Update spec.md
+
+Update the API Endpoints table in `features/{slug}/spec.md`:
+
+```markdown
+| POST   | /api/v1/{resources}      | {module} | [contract](../../contracts/{module}/{slug}.yaml) |
+| GET    | /api/v1/{resources}      | {module} | [contract](../../contracts/{module}/{slug}.yaml) |
+| GET    | /api/v1/{resources}/{id} | {module} | [contract](../../contracts/{module}/{slug}.yaml) |
+| PATCH  | /api/v1/{resources}/{id} | {module} | [contract](../../contracts/{module}/{slug}.yaml) |
+| DELETE | /api/v1/{resources}/{id} | {module} | [contract](../../contracts/{module}/{slug}.yaml) |
+```
+
+Also advance the spec status: change the `**Status:**` line in `features/{slug}/spec.md`
+from `Draft` to `Ready` (planning complete — ready for implementation).
+
+---
+
+## Step 7 — Completion
+
+> "Done. Feature `{slug}` contracts generated:
+>
+> contracts/{module}/
+>   {slug}.yaml
+>   schemas/  ({n} schema files)
+>   shared/   (api-error, pagination-meta)
+>
+> Run `/forge-implement {slug}` in each module repo to start implementation."

package/forge-contract/reference/best-practices.md

@@ -0,0 +1,223 @@
+# Contract Best Practices
+
+Conventions to enforce when generating Specmatic OpenAPI 3.0 contracts.
+Read this together with `contract-template.yaml` (the skeleton).
+
+## File structure
+
+```
+contracts/
+  {module}/
+    {feature-slug}.yaml          ← main file: info + paths + $refs only
+    schemas/
+      create-{resource}-request.yaml
+      update-{resource}-request.yaml
+      {resource}-response.yaml
+      {resource}-summary.yaml
+      {resource}-reference.yaml
+      enums/
+        {resource}-status.yaml   ← one file per enum
+    shared/                      ← shared across all features in this module
+      api-error.yaml
+      api-error-detail.yaml
+      pagination-meta.yaml
+```
+
+The main contract file contains only `info`, `servers`, `security`, `paths`, and
+`components` with `$ref` entries pointing to the schema files.
+Never inline a complex schema in the main file.
+
+## Schema segregation — never reuse if even one field differs
+
+| Schema | Purpose | Rules |
+|--------|---------|-------|
+| `Create{Resource}Request` | POST body | No `id`, no `createdAt`/`updatedAt`. Only fields the client sets. Required fields required. |
+| `Update{Resource}Request` | PATCH body | All fields optional. No `id`, no timestamps. At least one field must be present (use `minProperties: 1`). |
+| `Replace{Resource}Request` | PUT body | Required fields required. No `id`, no timestamps. |
+| `{Resource}Response` | GET single | Full object. All server-set fields included (`id`, timestamps). |
+| `{Resource}Summary` | GET list item | Lightweight — key fields only (id, name, status, createdAt). No nested objects. |
+| `{Resource}Reference` | POST 201 body | Minimal reference: `id` (uuid) only. Optionally add `href` (the resource URL). |
+
+## HTTP method rules
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| Create resource | `POST` | `/api/v1/{resources}` |
+| Get single | `GET` | `/api/v1/{resources}/{id}` |
+| Get list | `GET` | `/api/v1/{resources}` |
+| Partial update | `PATCH` | `/api/v1/{resources}/{id}` |
+| Full replace | `PUT` | `/api/v1/{resources}/{id}` |
+| Delete | `DELETE` | `/api/v1/{resources}/{id}` |
+| Custom action | `POST` | `/api/v1/{resources}/{id}/{action}` |
+
+- Never use `GET` to mutate state
+- Never put verbs in resource paths (`/deactivateUser` ❌ → `POST /users/{id}/deactivation` ✅)
+- Max 2 nesting levels: `/users/{userId}/addresses/{addressId}` MAX
+- Custom actions as sub-resource nouns: `/activation`, `/suspension`, `/password-reset`
+
+## URL path rules
+
+- Plural nouns: `/users` not `/user`
+- Kebab-case for multi-word segments: `/user-profiles`, `/order-items`
+- Version prefix: `/api/v1/`
+- No trailing slashes
+- IDs always in path, not query string, when addressing a specific resource
+- UUIDs only — never expose sequential integer IDs in paths
+
+## Status code rules
+
+| Case | Code |
+|------|------|
+| Successful GET | `200 OK` |
+| Successful POST (resource created) | `201 Created` |
+| Async operation accepted | `202 Accepted` |
+| Successful PATCH / PUT / DELETE (no body) | `204 No Content` |
+| Validation failure (client fixable) | `400 Bad Request` |
+| Not authenticated (missing/invalid token) | `401 Unauthorized` |
+| Authenticated but not authorized | `403 Forbidden` |
+| Resource not found | `404 Not Found` |
+| Duplicate / state conflict | `409 Conflict` |
+| Business rule violation (semantically invalid) | `422 Unprocessable Entity` |
+| Rate limit exceeded | `429 Too Many Requests` |
+| Unexpected server error | `500 Internal Server Error` |
+
+## Consistent error object
+
+All error responses across all endpoints use `ApiError`.
+Never define a custom error shape per endpoint.
+
+**`shared/api-error.yaml`:**
+```yaml
+type: object
+required: [code, message, traceId]
+properties:
+  code:
+    type: string
+    description: "Machine-readable error code (SCREAMING_SNAKE_CASE)"
+    example: "VALIDATION_ERROR"
+  message:
+    type: string
+    description: "Human-readable summary"
+    example: "Validation failed for 1 field(s)"
+  traceId:
+    type: string
+    format: uuid
+    description: "Unique request trace ID for debugging and support"
+    example: "123e4567-e89b-12d3-a456-426614174000"
+  details:
+    type: array
+    description: "Field-level errors — present on 400, omitted otherwise"
+    items:
+      $ref: "./api-error-detail.yaml"
+```
+
+**`shared/api-error-detail.yaml`:**
+```yaml
+type: object
+required: [field, code, message]
+properties:
+  field:
+    type: string
+    description: "JSON path to the invalid field"
+    example: "email"
+  code:
+    type: string
+    description: "Field-level error code"
+    example: "INVALID_FORMAT"
+  message:
+    type: string
+    description: "What is wrong and how to fix it"
+    example: "Must be a valid email address"
+```
+
+**Common error codes to use consistently:**
+
+| Code | When |
+|------|------|
+| `VALIDATION_ERROR` | 400 — one or more fields invalid (use with `details[]`) |
+| `INVALID_FORMAT` | 400 — field detail: wrong format |
+| `REQUIRED_FIELD` | 400 — field detail: missing required field |
+| `INVALID_VALUE` | 400 — field detail: value not in allowed set |
+| `UNAUTHENTICATED` | 401 |
+| `FORBIDDEN` | 403 |
+| `NOT_FOUND` | 404 |
+| `ALREADY_EXISTS` | 409 — duplicate |
+| `STATE_CONFLICT` | 409 — operation not valid in current state |
+| `BUSINESS_RULE_VIOLATION` | 422 — semantically invalid |
+| `RATE_LIMIT_EXCEEDED` | 429 |
+| `INTERNAL_ERROR` | 500 |
+
+## Enum rules
+
+- Every enum is a separate file under `schemas/enums/`
+- Values in SCREAMING_SNAKE_CASE: `ACTIVE`, `PENDING_VERIFICATION`, `SOFT_DELETED`
+- Always `$ref` to the enum file — never inline enum values
+- Include a `description` on the enum schema and on each value via `x-enum-descriptions`
+
+**Example `schemas/enums/user-status.yaml`:**
+```yaml
+type: string
+description: "Lifecycle status of a user account"
+enum:
+  - ACTIVE
+  - PENDING_VERIFICATION
+  - SUSPENDED
+  - DELETED
+x-enum-descriptions:
+  ACTIVE: "Account is active and can log in"
+  PENDING_VERIFICATION: "Email not yet verified"
+  SUSPENDED: "Account suspended by admin"
+  DELETED: "Soft-deleted, not visible to users"
+example: "ACTIVE"
+```
+
+## Naming conventions
+
+| Item | Convention | Example |
+|------|-----------|---------|
+| Schema names | PascalCase | `CreateUserRequest`, `UserResponse` |
+| Properties | camelCase | `firstName`, `createdAt`, `isActive` |
+| Enum values | SCREAMING_SNAKE_CASE | `PENDING_VERIFICATION` |
+| Operation IDs | camelCase verb+noun | `createUser`, `listUsers`, `getUserById` |
+| File names | kebab-case | `create-user-request.yaml` |
+| Error codes | SCREAMING_SNAKE_CASE | `VALIDATION_ERROR` |
+
+## Additional rules
+
+- Never return `null` fields — omit absent optional fields from responses
+- IDs are always `type: string, format: uuid` — never integer
+- Dates always `type: string, format: date-time` (ISO 8601 with timezone)
+- List endpoints always support `page` (int, default 1), `size` (int, default 20, max 100)
+- List responses always include `PaginationMeta`: `page`, `size`, `total`, `totalPages`
+- POST 201 response includes `Location` header pointing to the created resource URL
+
+**`shared/pagination-meta.yaml`:**
+```yaml
+type: object
+required: [page, size, total, totalPages]
+properties:
+  page:
+    type: integer
+    description: "Current page (1-based)"
+    example: 1
+  size:
+    type: integer
+    description: "Items per page"
+    example: 20
+  total:
+    type: integer
+    description: "Total number of items"
+    example: 142
+  totalPages:
+    type: integer
+    description: "Total number of pages"
+    example: 8
+```
+
+## Specmatic rules
+
+- Every endpoint MUST have at least one `examples` block — Specmatic uses these for stubs
+- `operationId` must be unique across the entire file
+- Include `format` for every applicable property: `uuid`, `date`, `date-time`, `email`, `uri`
+- One main contract file per module per feature — never one file per endpoint
+- All `$ref` paths must be relative (e.g. `./schemas/user-response.yaml`, `../shared/api-error.yaml`)