Gate 4: API contracts document - defines component interfaces and data contracts before protocol/technology selection. Large Track only.
Defines protocol-agnostic API contracts and component interfaces before technology selection.
npx claudepluginhub lerianstudio/ringThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Component contracts and interfaces must be defined before technology/protocol selection.
Jumping to implementation without contract definition creates:
The API Design answers: WHAT data/operations components expose and consume? The API Design never answers: HOW those are implemented (protocols, serialization, specific tech).
Before defining contracts, check for organizational naming standards.
See shared-patterns/standards-discovery.md for complete workflow.
Context: API field naming standards
Output: docs/pre-dev/{feature-name}/api-standards-ref.md
Use AskUserQuestion tool:
Question: "Do you have a data dictionary or API field naming standards to reference?"
1. Load the document:
| Source Type | Tool | Actions |
|---|---|---|
| URL | WebFetch | Fetch document content; parse for field definitions, naming rules, validation patterns |
| File path | Read | Read file content; support .md (Markdown tables), .json (structured), .yaml (structured), .csv (tabular) |
2. Extract standards:
MUST extract these elements if present:
| Element | What to Extract | Example |
|---|---|---|
| Field naming convention | camelCase, snake_case, PascalCase | userId vs user_id |
| Standard field names | Common fields used across APIs | createdAt, updatedAt, isActive |
| Data type formats | How to represent dates, IDs, amounts | ISO8601, UUID v4, Decimal(10,2) |
| Validation patterns | Regex, constraints, rules | Email RFC 5322, phone E.164 |
| Standard error codes | Organizational error naming | EMAIL_ALREADY_EXISTS vs DuplicateEmail |
| Pagination fields | Standard query/response pagination | page, pageSize, totalCount |
3. Save extracted standards:
Output to: docs/pre-dev/{feature-name}/api-standards-ref.md
Format:
# API Standards Reference - {Feature Name}
Source: {URL or file path}
Extracted: {timestamp}
## Field Naming Conventions
- IDs: `{pattern}` (example)
- Timestamps: `{pattern}` (example)
- Booleans: `{pattern}` (example)
- Collections: `{pattern}` (example)
## Standard Fields
| Field | Type | Format | Validation | Example |
|-------|------|--------|------------|---------|
| userId | string | UUID v4 | Required, unique | "550e8400-e29b-41d4-a716-446655440000" |
| email | string | RFC 5322 | Required, unique | "user@example.com" |
| createdAt | string | ISO 8601 | Auto-generated | "2026-01-23T10:30:00Z" |
## Standard Error Codes
| Code | Usage | HTTP Equivalent (for reference) |
|------|-------|--------------------------------|
| EMAIL_ALREADY_EXISTS | Duplicate email registration | 409 Conflict |
| INVALID_INPUT | Validation failure | 400 Bad Request |
## Validation Patterns
| Pattern Type | Rule | Example |
|-------------|------|---------|
| Email | RFC 5322, max 254 chars | "user@example.com" |
| Phone | E.164 format | "+5511987654321" |
## Pagination Standards
| Field | Type | Description |
|-------|------|-------------|
| page | integer | 1-indexed page number |
| pageSize | integer | Items per page (max 100) |
| totalCount | integer | Total items across all pages |
4. Apply throughout Gate 4:
If Phase 0 from Gate 0 (Research) found existing patterns that conflict with the dictionary:
STOP and use AskUserQuestion:
Question: "Dictionary says {dictionary_pattern}, but codebase uses {codebase_pattern}. Which should we follow?"
Proceed with standard naming conventions:
Document the choice in api-standards-ref.md with rationale.
| Phase | Activities |
|---|---|
| 0. API Standards Discovery | Check for organizational field naming standards (data dictionary); load from URL or file if provided; extract field conventions, types, validation patterns; save to api-standards-ref.md for reference throughout gate |
| 1. Contract Analysis | Load approved TRD (Gate 3), Feature Map (Gate 2), PRD (Gate 1); identify integration points from TRD component diagram; extract data flows |
| 2. Contract Definition | Per interface: define operations, specify inputs/outputs, define errors, document events, set constraints (validation), version contracts; apply standards from Phase 0 if available |
| 3. Gate 4 Validation | Verify all checkboxes in validation checklist before proceeding to Data Modeling |
Operation names/descriptions, input parameters (name, type, required/optional, constraints), output structure (fields, types, nullable), error codes/descriptions, event types/payloads, validation rules, idempotency requirements, auth/authz needs (abstract), versioning strategy
HTTP verbs (GET/POST/PUT), gRPC/GraphQL/WebSocket details, URL paths/routes, serialization formats (JSON/Protobuf), framework code, database queries, infrastructure, specific auth libraries
| Element | Abstract (✅) | Protocol-Specific (❌) |
|---|---|---|
| Operation | "CreateUser" | "POST /api/v1/users" |
| Data Type | "EmailAddress (validated)" | "string with regex" |
| Error | "UserAlreadyExists" | "HTTP 409 Conflict" |
| Auth | "Requires authenticated user" | "JWT Bearer token" |
| Format | "ISO8601 timestamp" | "time.RFC3339" |
| Excuse | Reality |
|---|---|
| "No need to ask about data dictionary" | Organizations have standards. Check first, don't assume. Phase 0 is MANDATORY. |
| "I'll just use common sense for field names" | "Common sense" varies. Ask for standards, or explicitly choose best practices. |
| "Skip Phase 0, user will mention standards if important" | User doesn't know when to mention it. YOU must ask proactively. |
| "REST is obvious, just document endpoints" | Protocol choice goes in Dependency Map. Define contracts abstractly. |
| "We need HTTP codes for errors" | Error semantics matter; HTTP codes are protocol. Abstract the errors. |
| "Teams need to see JSON examples" | JSON is serialization. Define structure; format comes later. |
| "The contract IS the OpenAPI spec" | OpenAPI is protocol-specific. Design contracts first, generate specs later. |
| "gRPC/GraphQL affects the contract" | Protocols deliver contracts. Design protocol-agnostic contracts first. |
| "We already know it's REST" | Knowing doesn't mean documenting prematurely. Stay abstract. |
| "Framework validates inputs" | Validation logic is universal. Document rules; implementation comes later. |
| "This feels redundant with TRD" | TRD = components exist. API = how they talk. Different concerns. |
| "URL structure matters for APIs" | URLs are HTTP-specific. Focus on operations and data. |
| "But API Design means REST API" | API = interface. Could be REST, gRPC, events, or in-process. Stay abstract. |
If you catch yourself writing any of these in API Design, STOP:
When you catch yourself: Replace protocol detail with abstract contract. "POST /users" → "CreateUser operation"
| Category | Requirements |
|---|---|
| Contract Completeness | All component-to-component interactions have contracts; all external integrations covered; all event/message contracts defined; client-facing APIs specified |
| Operation Clarity | Each operation has clear purpose/description; consistent naming convention; idempotency documented; batch operations identified |
| Data Specification | All inputs typed and documented; required vs optional explicit; outputs complete; null/empty cases handled |
| Error Handling | All scenarios identified; error codes/types defined; actionable messages; retry/recovery documented |
| Event Contracts | All events named/described; payloads specified; ordering/delivery semantics documented; versioning defined |
| Constraints & Policies | Validation rules explicit; timeouts specified; backward compatibility exists |
| Technology Agnostic | No protocol specifics; no serialization formats; no framework names; implementable in any protocol |
Gate Result: ✅ PASS (all checked) → Data Modeling | ⚠️ CONDITIONAL (remove protocol details) | ❌ FAIL (incomplete)
Output to (path depends on topology.structure):
docs/pre-dev/{feature-name}/api-design.md{backend.path}/docs/pre-dev/{feature-name}/api-design.md| Section | Content |
|---|---|
| Overview | TRD/Feature Map/PRD references, status, last updated |
| Versioning Strategy | Approach (semantic/date-based), backward compatibility policy, deprecation process |
| Component Contracts | Per component: purpose, integration points (inbound/outbound), operations |
| Field | Content |
|---|---|
| Purpose | What the operation does |
| Inputs | Table: Parameter, Type, Required, Constraints, Description |
| Validation Rules | Format patterns, business rules |
| Outputs (Success) | Table: Field, Type, Nullable, Description + abstract structure |
| Errors | Table: Error Code, Condition, Description, Retry? |
| Idempotency | Behavior on duplicate calls |
| Authorization | Required permissions (abstract) |
| Related Operations | Events triggered, downstream calls |
| Field | Content |
|---|---|
| Purpose/When Emitted | Trigger conditions |
| Payload | Table: Field, Type, Nullable, Description |
| Consumers | Services that consume this event |
| Delivery Semantics | At-least-once, at-most-once, exactly-once |
| Ordering/Retention | Ordering guarantees, retention period |
| Section | Content |
|---|---|
| Cross-Component Integration | Per integration: purpose, operations used, data flow diagram (abstract), error handling |
| External System Contracts | Operations exposed to us, operations we expose, per-operation details |
| Custom Type Definitions | Per type: base type, format, constraints, example |
| Naming Conventions | Operations (verb+noun), parameters (camelCase), events (past tense), errors (noun+condition) |
| Backward Compatibility | Breaking vs non-breaking changes, deprecation timeline |
| Testing Contracts | Contract testing strategy, example test scenarios |
| Gate 4 Validation | Date, validator, checklist, approval status |
| Violation | Wrong | Correct |
|---|---|---|
| Protocol Details | "Endpoint: POST /api/v1/users, Status: 201 Created, 409 Conflict" | "Operation: CreateUser, Errors: EmailAlreadyExists, InvalidInput" |
| Implementation Code | JavaScript regex validation code | "email must match RFC 5322 format, max 254 chars" |
| Technology Types | JSON example with "uuid", "Date", "Map<String,Any>" | Table with abstract types: Identifier (UUID format), Timestamp (ISO8601), ProfileObject |
| Factor | Points | Criteria |
|---|---|---|
| Contract Completeness | 0-30 | All ops: 30, Most: 20, Gaps: 10 |
| Interface Clarity | 0-25 | Clear/unambiguous: 25, Some interpretation: 15, Vague: 5 |
| Integration Complexity | 0-25 | Simple point-to-point: 25, Moderate deps: 15, Complex orchestration: 5 |
| Error Handling | 0-20 | All scenarios: 20, Common cases: 12, Minimal: 5 |
Action: 80+ autonomous generation | 50-79 present options | <50 ask clarifying questions
api-design.md is a backend document - it defines API contracts implemented by backend services.
| Structure | api-design.md Location |
|---|---|
| single-repo | docs/pre-dev/{feature}/api-design.md |
| monorepo | {backend.path}/docs/pre-dev/{feature}/api-design.md |
| multi-repo | {backend.path}/docs/pre-dev/{feature}/api-design.md |
Why backend path? API contracts are:
Directory creation for multi-module:
# Read topology from research.md frontmatter
backend_path="${topology_modules_backend_path:-"."}"
mkdir -p "${backend_path}/docs/pre-dev/{feature}"
⛔ HARD GATE: If api_pattern: bff (from research.md), this section is MANDATORY.
Check research.md frontmatter:
topology:
scope: frontend-only | fullstack
api_pattern: bff # ← This triggers BFF contract design
After backend contracts (Phase 2), define BFF-to-Frontend contracts:
| Step | Activity |
|---|---|
| 1 | Identify all frontend components that need data |
| 2 | Map component data needs to backend APIs |
| 3 | Define BFF aggregation operations |
| 4 | Specify BFF response contracts (frontend-optimized shapes) |
| 5 | Document error normalization strategy |
Add to api-design.md under ## BFF Contracts section:
## BFF Contracts
### Overview
- **Pattern:** BFF (Backend-for-Frontend)
- **Purpose:** [Aggregation | Transformation | Security | All]
- **Frontend Framework:** [Next.js | React | Vue | etc.]
### BFF Operations
#### Operation: Get{Feature}Data
**Purpose:** Aggregate data for {feature} component
**Frontend Consumer:** `{ComponentName}.tsx`
**Backend APIs Consumed:**
| API | Operation | Purpose |
|-----|-----------|---------|
| User Service | GetUser | User profile data |
| Order Service | ListOrders | Recent orders |
**Input Contract:**
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| userId | Identifier | Yes | Valid UUID | Target user |
| limit | Integer | No | 1-100, default 10 | Max orders |
**Output Contract (Frontend-Optimized):**
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| user | UserSummary | No | Simplified user object |
| user.id | Identifier | No | User ID |
| user.displayName | String | No | Formatted name |
| recentOrders | OrderSummary[] | No | Last N orders |
| recentOrders[].id | Identifier | No | Order ID |
| recentOrders[].total | FormattedCurrency | No | Display-ready total |
**Error Normalization:**
| Backend Error | BFF Error Code | Frontend Action |
|---------------|----------------|-----------------|
| User 404 | USER_NOT_FOUND | Redirect to error page |
| Orders 500 | ORDERS_UNAVAILABLE | Show partial data |
| Auth 401 | SESSION_EXPIRED | Trigger re-auth |
BFF MUST transform backend types to frontend-optimized types:
| Backend Type | Frontend Type | Transformation |
|---|---|---|
| ISO8601 string | RelativeTime | "2 hours ago" |
| Decimal amount | FormattedCurrency | "$1,234.56" |
| Full entity | Summary object | Select display fields |
| Nested IDs | Resolved names | Join data |
If topology.scope: frontend-only:
The BFF consumes EXISTING backend APIs (documented in PRD Data Sources).
MUST verify:
### PRD Data Source Coverage
| PRD Data Source | Covered by BFF Operation | Notes |
|-----------------|-------------------------|-------|
| User API | GetDashboardData | User summary included |
| Orders API | GetDashboardData | Recent orders included |
| Reports API | GenerateReport | New BFF operation |
| Category | Requirements |
|---|---|
| BFF Completeness | All frontend components have data contracts; all backend APIs mapped to BFF operations; error normalization defined; type transformations documented |
| Excuse | Reality |
|---|---|
| "BFF is just a proxy" | Proxies still transform errors and aggregate. Document contracts. |
| "Frontend types are implementation" | Types define component contracts. Design them here. |
| "We'll figure out transformations later" | Later = bugs. Define transformations upfront. |
| "Backend contract = frontend contract" | Backend serves multiple clients. Frontend needs optimized shapes. |
| "BFF contracts are obvious from UI" | Obvious to you ≠ documented. Write explicit contracts. |
ring:pre-dev-data-model)If you wrote API contracts with HTTP endpoints or gRPC services, remove them.
Contracts are protocol-agnostic. Period. No REST. No GraphQL. No HTTP codes.
Protocol choices go in Dependency Map. That's a later phase. Wait for it.
Define the contract. Stay abstract. Choose protocol later.
This skill is an API contract design skill and does NOT require WebFetch of language-specific standards.
Purpose: API Design defines WHAT operations and data contracts exist, not HOW they're implemented. Protocol-specific patterns apply during Dependency Map (Gate 6) and implementation.
However, MUST complete Phase 0 (API Standards Discovery) to check for organizational naming standards before designing contracts.
| Condition | Action | Severity |
|---|---|---|
| TRD (Gate 3) not validated | STOP and complete Gate 3 first | CRITICAL |
| Protocol details in contracts (HTTP verbs, URLs) | STOP and abstract to operations | HIGH |
| Phase 0 not completed (no standards check) | STOP and ask user about data dictionary | HIGH |
| Dictionary conflicts with codebase patterns | STOP and ask user which to follow | MEDIUM |
| Operation missing error handling | STOP and define error contracts | MEDIUM |
| BFF pattern required but contracts missing | STOP and define BFF contracts | HIGH |
These requirements are NON-NEGOTIABLE:
| Severity | Definition | Example |
|---|---|---|
| CRITICAL | Cannot proceed with API design | TRD not validated, no component boundaries |
| HIGH | Contract contains forbidden content | HTTP verbs, URL paths, status codes |
| MEDIUM | Contract incomplete but usable | Missing error contract for some operations |
| LOW | Minor documentation gaps | Idempotency behavior not fully detailed |
| User Says | Your Response |
|---|---|
| "REST is obvious, just document endpoints" | "Cannot include REST specifics. Define operations abstractly. Protocol choice happens in Gate 6." |
| "We need HTTP codes for errors" | "Cannot use HTTP codes. Define error semantics abstractly. 'UserNotFound' not '404'." |
| "Teams need to see JSON examples" | "Cannot include JSON. JSON is serialization. Define structure abstractly, format later." |
| "Skip Phase 0, naming is obvious" | "Cannot skip standards discovery. Organizational standards may exist. I'll check with user first." |
| "The contract IS the OpenAPI spec" | "Cannot conflate contract with spec. Design abstract contracts first, generate OpenAPI later." |
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.