agent-skill-kit 3.9.135

package/.agent/skills/api-architect/AGENTS.md

@@ -0,0 +1,1896 @@
+# api-architect
+
+**Version 1.0.0**
+Engineering
+March 2026
+
+> **Note:**
+> This document is for agents and LLMs to follow when working on api-architect domain.
+> Optimized for automation and consistency by AI-assisted workflows.
+
+---
+
+## Observability Requirements
+
+- **OpenTelemetry Integration (MANDATORY)**: EVERY API endpoint MUST propagate tracing headers (e.g., X-B3-TraceId or W3C 	raceparent). JSON outputs from validation MUST contain 	race_id.
+
+---
+
+# API Architect
+
+> Context-aware API design decisions. Learn to THINK about API style for THIS project, not default to REST.
+
+---
+
+## Prerequisites
+
+**Required:** None — API Architect is a knowledge-based skill with no external dependencies.
+
+**Optional:**
+- `scripts/api_validator.ts` — run `node scripts/api_validator.ts <project_path>` for endpoint validation
+
+---
+
+## When to Use
+
+| Situation | Reference |
+|-----------|-----------|
+| Choosing API style (REST/GraphQL/tRPC) | `rules/api-style.md` |
+| Designing REST endpoints | `rules/rest.md` |
+| Response format / error envelope | `rules/response.md` |
+| GraphQL schema design | `rules/graphql.md` |
+| tRPC for TypeScript fullstack | `rules/trpc.md` |
+| API versioning strategy | `rules/versioning.md` |
+| Auth pattern selection | `rules/auth.md` |
+| Rate limiting strategy | `rules/rate-limiting.md` |
+| OpenAPI documentation | `rules/documentation.md` |
+| OWASP API security audit | `rules/security-testing.md` |
+| Architecture review, contracts | `rules/engineering-spec.md` |
+
+**Selective Reading Rule:** Read ONLY the file matching the current request. Do not read all files.
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| API style selection (REST/GraphQL/tRPC) | API implementation code (→ backend-specialist) |
+| Response format and envelope design | Database schema (→ data-modeler) |
+| Versioning strategy selection | Auth implementation (→ auth-patterns) |
+| Rate limiting pattern selection | Security pen testing (→ security-scanner) |
+| OWASP API Top 10 checklist | Infrastructure / deployment (→ server-ops) |
+| OpenAPI documentation standards | Client-side consumption |
+
+**Pure decision skill:** Produces design documents and specifications. Zero code generation, zero network calls.
+
+---
+
+## Execution Model — 4-Phase Lifecycle
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| **Classify** | Validate request type and project context | Validated input or error |
+| **Evaluate** | Traverse decision tree (project_type → consumers → complexity → scale) | Selected pattern |
+| **Enrich** | Attach checklist, anti-patterns, related decisions | Complete decision |
+| **Emit** | Return structured output with rationale | Decision with metadata |
+
+All phases synchronous. Decision tree ordering is fixed and deterministic.
+
+---
+
+## API Style Decision Tree
+
+| Project Context | Recommended Style | Rationale |
+|----------------|-------------------|-----------|
+| TypeScript monorepo, internal consumers only | **tRPC** | End-to-end type safety, zero serialization overhead |
+| Complex relational data, multiple consumer types | **GraphQL** | Client-specific queries, no over-fetching |
+| Public API, third-party consumers | **REST** | Widest compatibility, cacheable, well-understood |
+| Simple CRUD, single consumer | **REST** | Minimal complexity, HTTP semantics sufficient |
+| Real-time data requirements | **GraphQL** (subscriptions) or **WebSocket** | Native subscription support |
+
+**Constraint:** `existing_api` context field takes precedence — avoid mixing styles unless justified.
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not one of the 8 supported types |
+| `ERR_MISSING_CONTEXT` | Yes | Required context field is null or empty |
+| `ERR_CONSTRAINT_CONFLICT` | Yes | Contradictory constraints in input |
+| `ERR_INVALID_CONSUMER` | Yes | Consumer type not recognized |
+| `ERR_REFERENCE_NOT_FOUND` | No | Rule file missing from rules/ directory |
+| `ERR_VALIDATOR_FAILED` | Yes | api_validator.ts exited with non-zero code |
+| `ERR_INVALID_SCALE` | No | Scale not one of: prototype, startup, growth, enterprise |
+
+**Zero internal retries.** Deterministic output; same context = same decision.
+
+---
+
+## Decision Checklist
+
+Before designing an API, confirm:
+
+- [ ] **Consumers identified?** (web-spa, mobile, third-party, internal-service, cli)
+- [ ] **API style chosen for THIS context?** (REST/GraphQL/tRPC — not defaulted)
+- [ ] **Response envelope format defined?** (consistent across all endpoints)
+- [ ] **Versioning strategy selected?** (URI/Header/Query — before first endpoint)
+- [ ] **Auth pattern selected?** (JWT/OAuth/Passkey/API Key)
+- [ ] **Rate limiting strategy defined?** (token bucket/sliding window)
+- [ ] **OpenAPI documentation approach set?**
+- [ ] **OWASP API Top 10 reviewed?**
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Default to REST for every project | Choose API style based on project context |
+| Use verbs in REST endpoints (`/getUsers`) | Use resource nouns (`/users`) with HTTP methods |
+| Different response formats per endpoint | Define one envelope pattern, apply uniformly |
+| Expose internal error details to clients | Map internal errors to safe client-facing codes |
+| Skip rate limiting on public APIs | Define rate limits before deployment |
+| Version after breaking changes occur | Define versioning strategy before first endpoint |
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [api-style.md](rules/api-style.md) | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| [rest.md](rules/rest.md) | Resource naming, HTTP methods, status codes | REST API design |
+| [response.md](rules/response.md) | Envelope pattern, error format, pagination | Response structure |
+| [graphql.md](rules/graphql.md) | Schema design, security, when to use | GraphQL consideration |
+| [trpc.md](rules/trpc.md) | TypeScript monorepo, type safety | TS fullstack projects |
+| [versioning.md](rules/versioning.md) | URI/Header/Query versioning strategies | API evolution |
+| [auth.md](rules/auth.md) | JWT, OAuth, Passkey, API Keys | Auth selection |
+| [rate-limiting.md](rules/rate-limiting.md) | Token bucket, sliding window | API protection |
+| [documentation.md](rules/documentation.md) | OpenAPI/Swagger standards | API documentation |
+| [security-testing.md](rules/security-testing.md) | OWASP API Top 10, auth/authz testing | Security audits |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec: contracts, security, scalability | Architecture review |
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.ts` | API endpoint validation | `node scripts/api_validator.ts <project_path>` |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `data-modeler` | Skill | Database schema design for API data |
+| `security-scanner` | Skill | Security vulnerability scanning |
+| `auth-patterns` | Skill | Authentication implementation patterns |
+| `nodejs-pro` | Skill | Node.js API implementation |
+| `/api` | Workflow | Full API build workflow |
+
+---
+
+
+
+---
+
+## Detailed Rules
+
+
+---
+
+### Rule: api-style
+
+---
+name: api-style
+description: REST vs GraphQL vs tRPC decision tree with code comparisons
+---
+
+# API Style Selection
+
+> Choose API style for THIS project's context — don't default to REST.
+
+---
+
+## Decision Tree
+
+```
+Who are the API consumers?
+│
+├── Public API / Multiple platforms
+│   └── REST + OpenAPI (widest compatibility)
+│
+├── Complex data needs / Multiple frontends
+│   └── GraphQL (flexible queries)
+│
+├── TypeScript frontend + backend (monorepo)
+│   └── tRPC (end-to-end type safety)
+│
+├── Real-time / Event-driven
+│   └── WebSocket + AsyncAPI
+│
+└── Internal microservices
+    └── gRPC (performance) or REST (simplicity)
+```
+
+## Comparison
+
+| Factor | REST | GraphQL | tRPC |
+|--------|------|---------|------|
+| **Best for** | Public APIs | Complex apps | TS monorepos |
+| **Learning curve** | Low | Medium | Low (if TS) |
+| **Over/under fetching** | Common | Solved | Solved |
+| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
+| **Caching** | HTTP native | Complex | Client-based |
+| **File uploads** | Native | Complex | Needs adapter |
+| **Versioning** | URI/Header | Schema evolution | Type inference |
+| **Tooling maturity** | Excellent | Good | Growing |
+
+## Code Comparison — Same Endpoint
+
+### REST
+
+```typescript
+// GET /api/users/123
+app.get('/api/users/:id', async (req, res) => {
+  const user = await db.user.findUnique({ where: { id: req.params.id } });
+  res.json({ data: user });
+});
+```
+
+### GraphQL
+
+```typescript
+// query { user(id: "123") { name email } }
+const resolvers = {
+  Query: {
+    user: (_: unknown, { id }: { id: string }) =>
+      db.user.findUnique({ where: { id } }),
+  },
+};
+```
+
+### tRPC
+
+```typescript
+// client.user.getById.query("123")
+export const userRouter = router({
+  getById: publicProcedure
+    .input(z.string())
+    .query(({ input }) => db.user.findUnique({ where: { id: input } })),
+});
+```
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Default to REST for every project | Evaluate consumers + context first |
+| Mix API styles without justification | Pick one, document reasoning |
+| Choose GraphQL for simple CRUD | Use REST or tRPC for simple cases |
+| Use tRPC for public APIs | Use REST + OpenAPI for public APIs |
+
+## Selection Questions
+
+1. Who are the API consumers? (web, mobile, third-party, internal)
+2. Is the frontend TypeScript?
+3. How complex are the data relationships?
+4. Is HTTP caching critical?
+5. Public or internal API?
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [rest.md](rest.md) | REST endpoint design |
+| [graphql.md](graphql.md) | GraphQL schema design |
+| [trpc.md](trpc.md) | tRPC for TS monorepos |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: auth
+
+---
+name: auth
+description: API authentication patterns — JWT, OAuth2 PKCE, API Keys, Passkeys, token refresh
+---
+
+# Authentication Patterns
+
+> Choose auth pattern based on consumers and security requirements.
+
+---
+
+## Selection Guide
+
+| Pattern | Best For | Security Level |
+|---------|----------|:--------------:|
+| **JWT** | Stateless APIs, microservices | Medium |
+| **Session** | Traditional web, server-rendered | High |
+| **OAuth 2.0 PKCE** | Third-party login, SPA/mobile | High |
+| **API Keys** | Server-to-server, public APIs | Low-Medium |
+| **Passkey** | Modern passwordless (2025+) | Very High |
+
+## JWT Pattern
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+// Sign — keep payload minimal
+function signTokens(userId: string) {
+  const accessToken = jwt.sign(
+    { sub: userId, type: 'access' },
+    process.env.JWT_SECRET!,
+    { expiresIn: '15m' }   // Short-lived
+  );
+
+  const refreshToken = jwt.sign(
+    { sub: userId, type: 'refresh' },
+    process.env.JWT_REFRESH_SECRET!,
+    { expiresIn: '7d' }
+  );
+
+  return { accessToken, refreshToken };
+}
+
+// Verify middleware
+function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) return res.status(401).json({ error: 'Missing token' });
+
+  try {
+    const payload = jwt.verify(token, process.env.JWT_SECRET!);
+    req.user = payload as JwtPayload;
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' });
+  }
+}
+```
+
+## Token Refresh Flow
+
+```
+Client                        Server
+  │                              │
+  ├── Request + Access Token ──→ │
+  │                              ├── Verify token
+  │ ←── 401 Token Expired ──────┤
+  │                              │
+  ├── POST /auth/refresh ──────→ │
+  │    { refreshToken }          ├── Verify refresh token
+  │                              ├── Issue new access + refresh
+  │ ←── { accessToken,          │
+  │       refreshToken } ───────┤
+  │                              │
+  ├── Retry original request ──→ │
+```
+
+## OAuth 2.0 PKCE (for SPAs/Mobile)
+
+```typescript
+// 1. Generate PKCE challenge
+const codeVerifier = crypto.randomBytes(32).toString('base64url');
+const codeChallenge = crypto
+  .createHash('sha256')
+  .update(codeVerifier)
+  .digest('base64url');
+
+// 2. Redirect to provider
+const authUrl = `https://provider.com/authorize?` +
+  `client_id=${CLIENT_ID}&` +
+  `code_challenge=${codeChallenge}&` +
+  `code_challenge_method=S256&` +
+  `redirect_uri=${REDIRECT_URI}&` +
+  `response_type=code&scope=openid+email`;
+
+// 3. Exchange code for tokens (server-side)
+const tokens = await fetch('https://provider.com/token', {
+  method: 'POST',
+  body: new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: authorizationCode,
+    code_verifier: codeVerifier,
+    client_id: CLIENT_ID,
+    redirect_uri: REDIRECT_URI,
+  }),
+});
+```
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Store sensitive data in JWT payload | Include only `sub`, `type`, `exp` |
+| Use long-lived access tokens (>1h) | Short access (15m) + refresh (7d) |
+| Send tokens in URL query params | Use `Authorization: Bearer` header |
+| Use OAuth implicit flow | Use PKCE for SPAs and mobile |
+| Skip token revocation | Maintain a revocation list for refresh tokens |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [security-testing.md](security-testing.md) | Auth testing patterns |
+| [rate-limiting.md](rate-limiting.md) | Rate limit auth endpoints |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: documentation
+
+---
+name: documentation
+description: OpenAPI 3.1 specs, Swagger UI setup, API documentation best practices
+---
+
+# API Documentation Principles
+
+> Good docs = happy developers = API adoption.
+
+---
+
+## OpenAPI 3.1 Example
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Users API
+  version: 1.0.0
+  description: User management endpoints
+
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, default: 1 }
+        - name: limit
+          in: query
+          schema: { type: integer, default: 20, maximum: 100 }
+      responses:
+        '200':
+          description: Paginated user list
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListResponse'
+
+    post:
+      summary: Create user
+      operationId: createUser
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserInput'
+      responses:
+        '201':
+          description: User created
+        '422':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        email: { type: string, format: email }
+      required: [id, name, email]
+
+    ErrorResponse:
+      type: object
+      properties:
+        success: { type: boolean, enum: [false] }
+        error:
+          type: object
+          properties:
+            code: { type: string }
+            message: { type: string }
+            requestId: { type: string }
+```
+
+## Swagger UI Setup (Express)
+
+```typescript
+import swaggerUi from 'swagger-ui-express';
+import spec from './openapi.json';
+
+app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec, {
+  customCss: '.swagger-ui .topbar { display: none }',
+  customSiteTitle: 'API Documentation',
+}));
+```
+
+## Good Documentation Includes
+
+| Section | Purpose |
+|---------|---------|
+| **Quick Start** | Get running in 5 minutes |
+| **Authentication** | How to get and use tokens |
+| **API Reference** | Every endpoint with examples |
+| **Error Handling** | Error codes and recovery |
+| **Rate Limits** | Limits and headers |
+| **Changelog** | Breaking changes and deprecations |
+| **Code Examples** | Multiple languages (curl, JS, Python) |
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Write docs after shipping | Generate from OpenAPI spec |
+| Skip request/response examples | Include full JSON examples |
+| Documentation-only errors | Use consistent error schema |
+| Outdated examples | Auto-generate from tests |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [response.md](response.md) | Response format for docs |
+| [versioning.md](versioning.md) | Documenting API versions |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: engineering-spec
+
+---
+title: API Architect — Engineering Specification
+impact: MEDIUM
+tags: api-architect
+---
+
+# API Architect — Engineering Specification
+
+> Production-grade specification for API design decision-making and pattern selection at FAANG scale.
+
+---
+
+## 1. Overview
+
+API Architect provides structured decision frameworks for API design: style selection (REST vs GraphQL vs tRPC), response formats, versioning strategies, authentication patterns, rate limiting, and documentation standards. The skill operates as an expert knowledge base that produces architectural decisions and API specifications, not runtime code.
+
+The skill codifies API design into deterministic decision trees backed by 10 reference documents covering style selection, REST patterns, GraphQL, tRPC, response formats, versioning, auth, rate limiting, documentation, and security testing.
+
+---
+
+## 2. Problem Statement
+
+API design at scale faces four quantified problems:
+
+| Problem | Measurement | Impact |
+|---------|-------------|--------|
+| Wrong API style selection | REST chosen for 100% of projects regardless of context | Unnecessary complexity for internal TS monorepos; insufficient for complex data graphs |
+| Inconsistent response formats | Different envelope patterns across endpoints within same API | Client-side parsing failures, increased integration cost |
+| No versioning strategy | Breaking changes deployed without versioning | Client breakage, forced upgrades, SLA violations |
+| Security gaps in API design | OWASP API Top 10 violations in 60%+ of first-design APIs | Vulnerability exposure, compliance failures |
+
+API Architect eliminates these by providing context-aware decision trees that produce documented, justified API design choices.
+
+---
+
+## 3. Design Goals
+
+| ID | Goal | Measurable Constraint |
+|----|------|-----------------------|
+| G1 | Context-aware style selection | Decision tree produces one of REST/GraphQL/tRPC based on ≤ 5 input criteria |
+| G2 | Consistent response format | Single envelope pattern per API; format documented before first endpoint |
+| G3 | Versioning from day one | Versioning strategy defined and documented before API implementation begins |
+| G4 | Security-first design | OWASP API Top 10 checklist completed before API goes to production |
+| G5 | Decision traceability | Every design choice includes rationale that references project context |
+
+---
+
+## 4. Non-Goals
+
+| ID | Excluded | Rationale |
+|----|----------|-----------|
+| NG1 | API implementation / code generation | This skill produces design decisions, not code; implementation is `backend-specialist` territory |
+| NG2 | Runtime API validation | Owned by `scripts/api_validator.ts`; SKILL.md defines design-time patterns |
+| NG3 | Database schema design | Owned by `data-modeler` skill |
+| NG4 | Authentication implementation | Owned by `auth-patterns` skill; this skill selects auth strategy |
+| NG5 | Infrastructure / deployment | Owned by `server-ops` and `cicd-pipeline` skills |
+| NG6 | Client-side API consumption | Out of scope; this skill designs the API surface, not its consumers |
+
+---
+
+## 5. System Boundaries
+
+| Boundary | Owned | Not Owned |
+|----------|-------|-----------|
+| API style selection | REST/GraphQL/tRPC decision tree | Implementation framework selection |
+| Response format design | Envelope pattern, error format, pagination | Serialization libraries |
+| Versioning strategy | URI/Header/Query versioning decision | Version deployment mechanics |
+| Auth pattern selection | JWT/OAuth/Passkey/API Key decision | Auth implementation (→ auth-patterns) |
+| Rate limiting strategy | Token bucket/sliding window selection | Rate limiter implementation |
+| API documentation | OpenAPI/Swagger structure standards | Doc hosting/rendering |
+| Security design | OWASP API Top 10 checklist | Penetration testing execution (→ security-scanner) |
+
+**Side-effect boundary:** API Architect produces design documents, decision records, and API specifications. It does not create API endpoints, modify server configurations, or make network requests.
+
+---
+
+## 6. Integration Model
+
+### 6.1 Agent Contract
+
+#### Input Schema
+
+```
+Request_Type: string      # One of: "style-selection" | "endpoint-design" | "response-format" |
+                          #         "versioning" | "auth-selection" | "rate-limiting" |
+                          #         "documentation" | "security-audit" | "full-design"
+Context: {
+  project_type: string    # "monorepo-ts" | "microservice" | "public-api" | "internal-api" | "bff"
+  consumers: Array<string> # ["web-spa", "mobile", "third-party", "internal-service", "cli"]
+  data_complexity: string  # "simple-crud" | "relational" | "graph" | "real-time"
+  team_expertise: string   # "typescript-fullstack" | "polyglot" | "backend-only"
+  scale: string           # "prototype" | "startup" | "growth" | "enterprise"
+  existing_api: string | null  # Existing API style if evolving, null if greenfield
+  constraints: Array<string> | null  # ["no-graphql", "must-version", "public-facing"]
+}
+contract_version: string  # "2.0.0"
+```
+
+#### Output Schema
+
+```
+Status: "success" | "error"
+Data: {
+  decision: string         # The selected pattern/approach
+  rationale: string        # Context-specific justification (references input criteria)
+  reference_file: string   # Path to the detailed reference document
+  checklist: Array<string> # Action items before implementation
+  anti_patterns: Array<string>  # Context-specific things to avoid
+  related_decisions: Array<{topic: string, reference: string}>  # Adjacent decisions to make
+  metadata: {
+    request_type: string
+    context_hash: string   # Hash of input context for reproducibility
+    version: string        # Skill version
+    contract_version: string    # "2.0.0"
+    backward_compatibility: string  # "breaking"
+  }
+}
+Error: ErrorSchema | null
+```
+
+**Contract Version:** 2.0.0
+**Backward Compatibility:** breaking (first hardened version)
+**Breaking Changes:** None — new spec for first hardening
+
+#### Error Schema
+
+```
+Code: string        # From Error Taxonomy (Section 11)
+Message: string     # Human-readable, single line
+Request_Type: string
+Recoverable: boolean
+```
+
+#### Deterministic Guarantees
+
+- Same `Request_Type` + `Context` = identical `decision` + `rationale` output.
+- Decision trees follow fixed evaluation order (project_type → consumers → data_complexity → team_expertise → scale).
+- Reference file selection is deterministic based on request_type.
+- No randomization, no A/B selection, no heuristic weighting.
+
+#### What Agents May Assume
+
+- Output `decision` is valid for the given `Context` and follows industry standards.
+- `reference_file` points to a file that exists in the skill's `rules/` directory.
+- `checklist` items are actionable and ordered by priority.
+- The skill is stateless; no prior invocation affects current output.
+
+#### What Agents Must NOT Assume
+
+- The decision is the only valid choice (multiple valid API styles may exist for a given context).
+- The decision accounts for undisclosed constraints (only explicit `Context` inputs affect output).
+- Implementation details are included (the skill produces design decisions, not code).
+- Security audit output replaces a full security review (it covers OWASP API Top 10, not exhaustive pen testing).
+
+#### Side-Effect Boundaries
+
+| Operation | Side Effects |
+|-----------|-------------|
+| Style selection | None; pure decision output |
+| Endpoint design | None; specification output |
+| Security audit | None; checklist output |
+| Validator script | Read-only filesystem scan; no modifications |
+
+### 6.2 Workflow Contract
+
+#### Invocation Pattern
+
+```
+1. Define project context (type, consumers, complexity, scale)
+2. Select request type (style-selection → response-format → versioning → auth → documentation)
+3. Receive decision with rationale and checklist
+4. Review and apply decision (caller's responsibility)
+5. Run api_validator.ts for implementation validation (optional)
+6. Repeat for adjacent decisions referenced in related_decisions
+```
+
+**Recommended ordering:** style-selection → endpoint-design → response-format → versioning → auth-selection → rate-limiting → documentation → security-audit.
+
+#### Execution Guarantees
+
+- Each invocation produces a complete, self-contained decision.
+- No background processes, no deferred execution.
+- Output includes all necessary context for the caller to act without re-invoking.
+
+#### Failure Propagation Model
+
+| Failure Severity | Propagation | Workflow Action |
+|-----------------|-------------|-----------------|
+| Invalid request type | Return error to caller | Use supported request type |
+| Missing context field | Return error to caller | Supply missing context |
+| Conflicting constraints | Return error to caller | Resolve constraint conflict |
+| Reference file missing | Return error to caller | Verify skill installation |
+
+Failures are isolated to the current invocation. No state carries between invocations.
+
+#### Retry Boundaries
+
+- Zero internal retries. Deterministic output makes retrying identical inputs meaningless.
+- Callers should modify `Context` between invocations to explore alternative decisions.
+
+#### Isolation Model
+
+- Each invocation is stateless and independent.
+- No shared state between invocations, sessions, or agents.
+- Reference files in `rules/` are read-only resources.
+
+#### Idempotency Expectations
+
+| Operation | Idempotent | Notes |
+|-----------|-----------|-------|
+| Decision generation | Yes | Same context = same decision |
+| Reference lookup | Yes | Read-only, no mutation |
+| Validator script | Yes | Read-only filesystem scan |
+
+---
+
+## 7. Execution Model
+
+### 4-Phase Lifecycle
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| **Classify** | Validate request type and context | Validated input or error |
+| **Evaluate** | Traverse decision tree for request type | Selected pattern with rationale |
+| **Enrich** | Attach checklist, anti-patterns, related decisions | Complete decision package |
+| **Emit** | Return structured output with metadata | Complete output schema |
+
+All phases execute synchronously in a single invocation. No async pipeline.
+
+---
+
+## 8. Deterministic Design Principles
+
+| Principle | Enforcement |
+|-----------|-------------|
+| Fixed decision tree ordering | project_type → consumers → data_complexity → team_expertise → scale |
+| No external calls | Decisions use only local reference files and input context |
+| No ambient state | Each invocation operates solely on explicit inputs |
+| No randomization | Decision trees are deterministic if-then-else chains |
+| Reproducible output | Input context hash echoed in output for audit trail |
+
+---
+
+## 9. State & Idempotency Model
+
+### State Machine
+
+```
+States: IDLE (single state — skill is stateless)
+Transitions: None — each invocation is independent
+```
+
+API Architect maintains zero persistent state. Every invocation starts from a clean state. Invoking N times with identical inputs produces N identical outputs.
+
+### Decision Versioning
+
+- Decision trees are versioned via `metadata.version` in SKILL.md frontmatter.
+- Reference file changes that alter decision outcomes require a version bump.
+- Callers can reference specific versions for decision auditability.
+
+---
+
+## 10. Failure Handling Strategy
+
+| Failure Class | Behavior | Caller Recovery |
+|---------------|----------|-----------------|
+| Unknown request type | Return `ERR_INVALID_REQUEST_TYPE` | Use supported request type |
+| Missing context field | Return `ERR_MISSING_CONTEXT` with field name | Supply missing field |
+| Conflicting constraints | Return `ERR_CONSTRAINT_CONFLICT` with conflicting items | Resolve conflict |
+| Invalid consumer type | Return `ERR_INVALID_CONSUMER` | Use supported consumer type |
+| Reference file missing | Return `ERR_REFERENCE_NOT_FOUND` | Verify skill installation |
+| Validator script failure | Return `ERR_VALIDATOR_FAILED` with exit code | Check project path |
+
+**Invariant:** Every failure returns a structured error. No invocation fails silently or returns partial decisions.
+
+---
+
+## 11. Error Taxonomy
+
+| Code | Category | Recoverable | Description |
+|------|----------|-------------|-------------|
+| `ERR_INVALID_REQUEST_TYPE` | Validation | No | Request type not one of the 8 supported types |
+| `ERR_MISSING_CONTEXT` | Validation | Yes | Required context field is null or empty |
+| `ERR_CONSTRAINT_CONFLICT` | Validation | Yes | Two constraints contradict each other |
+| `ERR_INVALID_CONSUMER` | Validation | Yes | Consumer type not recognized |
+| `ERR_REFERENCE_NOT_FOUND` | Infrastructure | No | Reference file missing from rules/ directory |
+| `ERR_VALIDATOR_FAILED` | Runtime | Yes | api_validator.ts exited with non-zero code |
+| `ERR_INVALID_SCALE` | Validation | No | Scale value not one of: prototype, startup, growth, enterprise |
+
+---
+
+## 12. Timeout & Retry Policy
+
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| Decision generation timeout | N/A | Synchronous decision tree traversal; completes in < 50ms |
+| Internal retries | Zero | Deterministic output makes retries meaningless |
+| Validator script timeout | 30,000 ms | Filesystem scan; fail if project is inaccessible |
+| Reference file read timeout | 1,000 ms | Local filesystem; fail immediately if inaccessible |
+
+**Retry policy:** Zero internal retries. Callers should modify context between invocations to explore alternatives.
+
+---
+
+## 13. Observability & Logging Schema
+
+### Log Entry Format
+
+```json
+{
+  "trace_id": "uuid",
+  "skill_name": "api-architect",
+  "contract_version": "2.0.0",
+  "execution_id": "uuid",
+  "timestamp": "ISO-8601",
+  "request_type": "string",
+  "decision": "string",
+  "context_hash": "string",
+  "status": "success|error",
+  "error_code": "string|null",
+  "reference_files_read": ["string"],
+  "duration_ms": "number"
+}
+```
+
+### Required Log Points
+
+| Event | Log Level | Fields |
+|-------|-----------|--------|
+| Decision generated | INFO | All fields |
+| Decision failed | ERROR | All fields + error_code |
+| Reference file read | DEBUG | file path, read duration |
+| Constraint conflict detected | WARN | conflicting constraints |
+| Validator script executed | INFO | project_path, exit_code, duration |
+
+### Metrics
+
+| Metric | Type | Unit |
+|--------|------|------|
+| `api.decision.duration` | Histogram | ms |
+| `api.decision.error_rate` | Counter | per error_code |
+| `api.request_type.usage` | Counter | per request_type |
+| `api.style.selected` | Counter | per style (REST/GraphQL/tRPC) |
+| `api.validator.duration` | Histogram | ms |
+| `api.validator.pass_rate` | Counter | pass/fail |
+
+---
+
+## 14. Security & Trust Model
+
+### Design-Time Security
+
+- API Architect enforces OWASP API Top 10 awareness through the `security-audit` request type.
+- Security checklist is generated before API implementation, not after.
+- Auth pattern selection references `rules/auth.md` for current industry standards.
+
+### Credential Handling
+
+- API Architect does not store, process, or transmit credentials.
+- Auth pattern selection produces strategy recommendations, not credential configurations.
+
+### Reference Integrity
+
+- Reference files in `rules/` are read-only resources.
+- Modifications require a version bump in SKILL.md frontmatter.
+- No runtime code injection; reference files are static markdown, not executable.
+
+### Input Sanitization
+
+- Context parameters are used for decision tree traversal, not code execution.
+- No eval, no template injection, no dynamic code generation from inputs.
+
+### Multi-Tenant Boundaries
+
+- Each invocation is stateless; no data persists between invocations.
+- No invocation can access context or outputs from another invocation.
+
+---
+
+## 15. Scalability Model
+
+| Dimension | Constraint | Mitigation |
+|-----------|-----------|------------|
+| Throughput | CPU-bound decision tree traversal | Completes in < 50ms; scales linearly with CPU |
+| Concurrency | Stateless invocations | Unlimited parallel invocations |
+| Reference storage | 10 rule files (~12 KB total) | Static files; no growth concern |
+| Memory per invocation | < 1 MB | No accumulation |
+| Network | Zero network calls (except validator against local filesystem) | No external dependency |
+
+### Capacity Planning
+
+| Metric | Per Invocation | Per Node |
+|--------|---------------|----------|
+| CPU | < 10 ms computation | 100,000+ invocations/second |
+| Memory | < 1 MB | Bound only by concurrent invocations |
+| Disk I/O | 1–2 rule file reads (~1–3 KB each) | Cached by OS after first read |
+| Network | Zero | Zero |
+
+---
+
+## 16. Concurrency Model
+
+| Scope | Model | Behavior |
+|-------|-------|----------|
+| Within invocation | Sequential | Classify → Evaluate → Enrich → Emit |
+| Across invocations | Fully parallel | No shared state, no coordination |
+| Reference access | Read-only shared | Multiple concurrent reads safe |
+| Validator script | Isolated per invocation | Each run scans independently |
+
+**No undefined behavior:** Stateless skill with read-only resource access; any concurrency level is safe.
+
+---
+
+## 17. Resource Lifecycle Management
+
+| Resource | Created By | Destroyed By | Max Lifetime |
+|----------|-----------|-------------|--------------|
+| Decision output | Emit phase | Caller (after consumption) | Invocation scope |
+| Rule file handle | Evaluate phase | Auto-close after read | < 10 ms |
+| Validator process | Caller (script invocation) | Process exit | 30,000 ms max |
+| Input context | Caller | Invocation completion | Invocation scope |
+
+**Leak prevention:** All resources scoped to single invocation. Validator script is a separate process with its own lifecycle.
+
+---
+
+## 18. Performance Constraints
+
+| Operation | P50 Target | P99 Target | Hard Limit |
+|-----------|-----------|-----------|------------|
+| Decision generation | < 5 ms | < 20 ms | 50 ms |
+| Rule file read | < 1 ms | < 5 ms | 1,000 ms |
+| Full design (8 request types) | < 40 ms | < 160 ms | 400 ms |
+| Validator script execution | < 5,000 ms | < 15,000 ms | 30,000 ms |
+| Output decision size | ≤ 500 chars | ≤ 2,000 chars | 5,000 chars |
+
+---
+
+## 19. Operational Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Decision tree staleness | Medium | Recommends outdated patterns | Version bumps with periodic review; rules/ files track dates |
+| Context under-specification | High | Generic decision instead of context-specific | `ERR_MISSING_CONTEXT` for required fields; checklist prompts for common gaps |
+| Over-reliance on single decision | Medium | Team skips alternative evaluation | Output includes `related_decisions` to prompt adjacent thinking |
+| Validator script false positives | Low | Flags correct implementations | Validator results are advisory; caller makes final judgment |
+| Rule file conflicts | Low | Contradictory guidance across files | Each file owns a single concern; cross-references are explicit |
+
+---
+
+## 20. Compliance with skill-design-guide.md
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| YAML frontmatter complete | ✅ | name, description, metadata with category, version, triggers, coordinates_with, success_metrics |
+| SKILL.md < 200 lines | ✅ | Entry point under 200 lines; details in rules/ |
+| Prerequisites documented | ✅ | No external dependencies |
+| When to Use section | ✅ | Request-type-based decision matrix |
+| Quick Reference | ✅ | Decision checklist and content map |
+| Core content matches skill type | ✅ | Expert type: decision trees, checklists |
+| Troubleshooting section | ✅ | Anti-patterns table |
+| Related section | ✅ | Cross-links to data-modeler, security-scanner, auth-patterns |
+| Content Map for multi-file | ✅ | Links to 10 rule files + engineering-spec.md |
+| Scripts documented | ✅ | api_validator.ts with command example |
+| Contract versioning | ✅ | contract_version, backward_compatibility, breaking_changes |
+| Compliance matrix structured | ✅ | This table with ✅/❌ + evidence |
+
+---
+
+## 21. Production Readiness Checklist
+
+| Category | Check | Status |
+|----------|-------|--------|
+| **Functionality** | 8 request types specified | ✅ |
+| **Functionality** | 3 API styles (REST/GraphQL/tRPC) with decision tree | ✅ |
+| **Functionality** | 10 reference files covering all API design concerns | ✅ |
+| **Contracts** | Input/output/error schemas defined | ✅ |
+| **Contracts** | Agent assumptions and non-assumptions documented | ✅ |
+| **Contracts** | Workflow invocation pattern with recommended ordering | ✅ |
+| **Failure** | Error taxonomy with 7 categorized error codes | ✅ |
+| **Failure** | No silent failures; every error returns structured response | ✅ |
+| **Failure** | Retry policy: zero internal retries | ✅ |
+| **Determinism** | Fixed decision tree ordering | ✅ |
+| **Determinism** | No randomization, no external calls | ✅ |
+| **Security** | OWASP API Top 10 checklist integrated | ✅ |
+| **Security** | No credential handling; design-time only | ✅ |
+| **Observability** | Structured log schema with 5 log points | ✅ |
+| **Observability** | 6 metrics defined with types and units | ✅ |
+| **Performance** | P50/P99 targets for all operations | ✅ |
+| **Scalability** | Stateless; unlimited parallel invocations | ✅ |
+| **Concurrency** | No shared state; read-only reference access | ✅ |
+| **Resources** | All resources scoped to invocation lifetime | ✅ |
+| **Idempotency** | Fully idempotent — all operations are pure functions | ✅ |
+| **Compliance** | All skill-design-guide.md sections present | ✅ |
+
+---
+
+
+
+---
+
+### Rule: graphql
+
+---
+name: graphql
+description: GraphQL schema design, resolver patterns, N+1 prevention, security
+---
+
+# GraphQL Principles
+
+> Flexible queries for complex, interconnected data.
+
+---
+
+## When to Use
+
+```
+✅ Good fit:
+├── Complex, interconnected data
+├── Multiple frontend platforms
+├── Clients need flexible queries
+├── Evolving data requirements
+└── Reducing over-fetching matters
+
+❌ Poor fit:
+├── Simple CRUD operations
+├── File upload heavy
+├── HTTP caching important
+└── Team unfamiliar with GraphQL
+```
+
+## Schema Design
+
+```graphql
+# Think in graphs, not endpoints
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  posts(first: Int = 10, after: String): PostConnection!
+  createdAt: DateTime!
+}
+
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  author: User!
+}
+
+# Relay-style pagination (recommended)
+type PostConnection {
+  edges: [PostEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type PostEdge {
+  node: Post!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+## Resolver Pattern
+
+```typescript
+const resolvers = {
+  Query: {
+    user: (_: unknown, { id }: { id: string }, ctx: Context) =>
+      ctx.dataSources.users.getById(id),
+
+    users: (_: unknown, args: PaginationArgs, ctx: Context) =>
+      ctx.dataSources.users.getConnection(args),
+  },
+
+  // Field resolver — handles N+1 via DataLoader
+  User: {
+    posts: (parent: User, args: PaginationArgs, ctx: Context) =>
+      ctx.dataSources.posts.getByAuthor(parent.id, args),
+  },
+};
+```
+
+## N+1 Prevention — DataLoader
+
+```typescript
+import DataLoader from 'dataloader';
+
+// Batch function: receives array of IDs, returns array of results
+const userLoader = new DataLoader<string, User>(async (ids) => {
+  const users = await db.user.findMany({ where: { id: { in: [...ids] } } });
+  const map = new Map(users.map(u => [u.id, u]));
+  return ids.map(id => map.get(id)!);
+});
+
+// In resolver — automatically batched
+const resolvers = {
+  Post: {
+    author: (post: Post) => userLoader.load(post.authorId),
+  },
+};
+```
+
+## Security
+
+| Threat | Mitigation |
+|--------|-----------|
+| Query depth attack | Set max depth (e.g., 7) |
+| Query complexity | Calculate cost per field, set max |
+| Batching abuse | Limit batch size |
+| Introspection leak | Disable in production |
+| Field-level auth | Check permissions per resolver |
+
+```typescript
+// Query depth + complexity limits
+const server = new ApolloServer({
+  validationRules: [
+    depthLimit(7),
+    costAnalysis({ maximumCost: 1000 }),
+  ],
+  introspection: process.env.NODE_ENV !== 'production',
+});
+```
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Expose database schema directly | Design schema for clients |
+| One mega-query resolver | Keep resolvers small + composable |
+| Skip DataLoader | Always use DataLoader for relations |
+| Allow unlimited query depth | Set max depth (7) + cost limits |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [api-style.md](api-style.md) | REST vs GraphQL vs tRPC decision |
+| [security-testing.md](security-testing.md) | GraphQL security testing |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: rate-limiting
+
+---
+name: rate-limiting
+description: Rate limiting strategies — token bucket, sliding window, Redis implementation, recommended limits
+---
+
+# Rate Limiting Principles
+
+> Protect your API from abuse and overload.
+
+## Why Rate Limit
+
+```
+Protect against:
+├── Brute force attacks
+├── Resource exhaustion
+├── Cost overruns (if pay-per-use)
+└── Unfair usage
+```
+
+## Strategy Selection
+
+| Type | How | When |
+|------|-----|------|
+| **Token bucket** | Burst allowed, refills over time | Most APIs |
+| **Sliding window** | Smooth distribution | Strict limits |
+| **Fixed window** | Simple counters per window | Basic needs |
+
+## Response Headers
+
+```
+Include in headers:
+├── X-RateLimit-Limit (max requests)
+├── X-RateLimit-Remaining (requests left)
+├── X-RateLimit-Reset (when limit resets)
+└── Return 429 when exceeded
+```
+
+## Redis Implementation Pattern
+
+```typescript
+// Sliding window with Redis
+const key = `ratelimit:${userId}:${endpoint}`;
+const current = await redis.incr(key);
+if (current === 1) {
+  await redis.expire(key, windowSeconds);
+}
+if (current > maxRequests) {
+  throw new RateLimitError();
+}
+```
+
+**Recommended Limits:**
+| Endpoint Type | Limit | Window |
+|---------------|-------|--------|
+| Public API | 100 | 1 min |
+| Authenticated | 1000 | 1 min |
+| Auth endpoints | 5 | 15 min |
+| File uploads | 10 | 1 hour |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [security-testing.md](security-testing.md) | Rate limit bypass testing |
+| [auth.md](auth.md) | Auth endpoint limits |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: response
+
+---
+name: response
+description: API response envelope pattern, error format, pagination, TypeScript types
+---
+
+# Response Format Principles
+
+> One envelope pattern for ALL endpoints — consistency is key.
+
+---
+
+## Envelope Pattern (Recommended)
+
+```typescript
+// Success response
+interface ApiResponse<T> {
+  success: true;
+  data: T;
+  meta?: PaginationMeta;
+}
+
+// Error response
+interface ApiError {
+  success: false;
+  error: {
+    code: string;         // Machine-readable: "VALIDATION_ERROR"
+    message: string;      // Human-readable: "Email is invalid"
+    details?: Record<string, string[]>; // Field-level errors
+    requestId: string;    // For support: "req_abc123"
+  };
+}
+
+type ApiResult<T> = ApiResponse<T> | ApiError;
+```
+
+### Usage Example
+
+```typescript
+// Express middleware helper
+function ok<T>(res: Response, data: T, meta?: PaginationMeta) {
+  res.json({ success: true, data, meta });
+}
+
+function fail(res: Response, status: number, code: string, message: string) {
+  res.status(status).json({
+    success: false,
+    error: { code, message, requestId: res.locals.requestId },
+  });
+}
+
+// In route handler
+app.get('/users/:id', async (req, res) => {
+  const user = await db.user.findUnique({ where: { id: req.params.id } });
+  if (!user) return fail(res, 404, 'NOT_FOUND', 'User not found');
+  ok(res, user);
+});
+```
+
+## Error Response Standards
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": {
+      "email": ["Must be a valid email"],
+      "age": ["Must be at least 18"]
+    },
+    "requestId": "req_abc123"
+  }
+}
+```
+
+**Never expose:** stack traces, SQL queries, internal paths, dependency versions.
+
+## Pagination
+
+| Type | Best For | Trade-offs |
+|------|----------|------------|
+| **Offset** | Simple, jumpable pages | Slow on large datasets, skip drift |
+| **Cursor** | Large datasets, infinite scroll | Can't jump to page N |
+| **Keyset** | Performance critical, sorted data | Requires sortable unique key |
+
+### Pagination Response
+
+```typescript
+interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+// Cursor-based alternative
+interface CursorMeta {
+  cursor: string | null;  // null = no more pages
+  hasMore: boolean;
+  limit: number;
+}
+```
+
+### Selection Guide
+
+1. Dataset < 10K rows → Offset pagination
+2. Dataset > 10K, infinite scroll → Cursor pagination
+3. Performance critical → Keyset pagination
+4. Data frequently changing → Cursor (avoids skip drift)
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Different formats per endpoint | One envelope for all endpoints |
+| Expose stack traces in errors | Map to safe client-facing codes |
+| Return `200 OK` with error body | Use proper HTTP status codes |
+| No request ID in errors | Always include for debugging/support |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [rest.md](rest.md) | HTTP methods + status codes |
+| [rate-limiting.md](rate-limiting.md) | 429 response format |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: rest
+
+---
+name: rest
+description: REST API design — resource naming, HTTP methods, status codes, filtering, sorting
+---
+
+# REST Principles
+
+> Resource-based API design — nouns not verbs.
+
+---
+
+## Resource Naming Rules
+
+```
+Principles:
+├── Use NOUNS, not verbs (resources, not actions)
+├── Use PLURAL forms (/users not /user)
+├── Use lowercase with hyphens (/user-profiles)
+├── Nest for relationships (/users/123/posts)
+└── Keep shallow (max 3 levels deep)
+```
+
+### Endpoint Examples
+
+```
+✅ Good:
+GET    /users              → List users
+GET    /users/123          → Get user 123
+POST   /users              → Create user
+PUT    /users/123          → Replace user 123
+PATCH  /users/123          → Partial update user 123
+DELETE /users/123          → Delete user 123
+GET    /users/123/posts    → User 123's posts
+
+❌ Bad:
+GET    /getUsers           → Verb in URL
+POST   /createUser         → Verb in URL
+GET    /user               → Singular
+GET    /users/123/posts/456/comments/789/likes  → Too deep (>3 levels)
+```
+
+## HTTP Method Selection
+
+| Method | Purpose | Idempotent? | Body? |
+|--------|---------|-------------|-------|
+| **GET** | Read resource(s) | Yes | No |
+| **POST** | Create new resource | No | Yes |
+| **PUT** | Replace entire resource | Yes | Yes |
+| **PATCH** | Partial update | No | Yes |
+| **DELETE** | Remove resource | Yes | No |
+
+## Status Code Selection
+
+| Situation | Code | When |
+|-----------|------|------|
+| Success (read) | 200 | GET returning data |
+| Created | 201 | POST success, include Location header |
+| No content | 204 | DELETE success, PUT with no response body |
+| Bad request | 400 | Malformed JSON, missing required field |
+| Unauthorized | 401 | Missing or invalid auth token |
+| Forbidden | 403 | Valid auth, insufficient permissions |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | Duplicate key, state conflict |
+| Validation error | 422 | Valid syntax, invalid semantics |
+| Rate limited | 429 | Too many requests, include Retry-After |
+| Server error | 500 | Unhandled exception |
+
+## Filtering, Sorting & Search
+
+```typescript
+// Filtering — use query params
+GET /users?role=admin&status=active
+
+// Sorting — prefix with - for descending
+GET /users?sort=-created_at,name
+
+// Search — use q parameter
+GET /users?q=john
+
+// Fields projection (sparse fieldsets)
+GET /users?fields=id,name,email
+
+// Combined
+GET /users?role=admin&sort=-created_at&fields=id,name&page=2&limit=20
+```
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| `/getUsers`, `/deleteUser/123` | `GET /users`, `DELETE /users/123` |
+| `/user` (singular) | `/users` (plural) |
+| Return 200 for errors | Use semantic HTTP status codes |
+| Nest beyond 3 levels | Use flat endpoints with filters |
+| Ignore idempotency | Design PUT/DELETE as idempotent |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [response.md](response.md) | Response envelope + pagination |
+| [versioning.md](versioning.md) | API versioning strategy |
+| [api-style.md](api-style.md) | REST vs GraphQL vs tRPC decision |
+
+---
+
+### Rule: security-testing
+
+---
+name: security-testing
+description: OWASP API Top 10, JWT testing, BOLA/IDOR, authorization and input validation testing
+---
+
+# API Security Testing
+
+> Principles for testing API security. OWASP API Top 10, authentication, authorization testing.
+
+---
+
+## OWASP API Security Top 10
+
+| Vulnerability | Test Focus |
+|---------------|------------|
+| **API1: BOLA** | Access other users' resources |
+| **API2: Broken Auth** | JWT, session, credentials |
+| **API3: Property Auth** | Mass assignment, data exposure |
+| **API4: Resource Consumption** | Rate limiting, DoS |
+| **API5: Function Auth** | Admin endpoints, role bypass |
+| **API6: Business Flow** | Logic abuse, automation |
+| **API7: SSRF** | Internal network access |
+| **API8: Misconfiguration** | Debug endpoints, CORS |
+| **API9: Inventory** | Shadow APIs, old versions |
+| **API10: Unsafe Consumption** | Third-party API trust |
+
+---
+
+## Authentication Testing
+
+### JWT Testing
+
+| Check | What to Test |
+|-------|--------------|
+| Algorithm | None, algorithm confusion |
+| Secret | Weak secrets, brute force |
+| Claims | Expiration, issuer, audience |
+| Signature | Manipulation, key injection |
+
+### Session Testing
+
+| Check | What to Test |
+|-------|--------------|
+| Generation | Predictability |
+| Storage | Client-side security |
+| Expiration | Timeout enforcement |
+| Invalidation | Logout effectiveness |
+
+---
+
+## Authorization Testing
+
+| Test Type | Approach |
+|-----------|----------|
+| **Horizontal** | Access peer users' data |
+| **Vertical** | Access higher privilege functions |
+| **Context** | Access outside allowed scope |
+
+### BOLA/IDOR Testing
+
+1. Identify resource IDs in requests
+2. Capture request with user A's session
+3. Replay with user B's session
+4. Check for unauthorized access
+
+---
+
+## Input Validation Testing
+
+| Injection Type | Test Focus |
+|----------------|------------|
+| SQL | Query manipulation |
+| NoSQL | Document queries |
+| Command | System commands |
+| LDAP | Directory queries |
+
+**Approach:** Test all parameters, try type coercion, test boundaries, check error messages.
+
+---
+
+## Rate Limiting Testing
+
+| Aspect | Check |
+|--------|-------|
+| Existence | Is there any limit? |
+| Bypass | Headers, IP rotation |
+| Scope | Per-user, per-IP, global |
+
+**Bypass techniques:** X-Forwarded-For, different HTTP methods, case variations, API versioning.
+
+---
+
+## GraphQL Security
+
+| Test | Focus |
+|------|-------|
+| Introspection | Schema disclosure |
+| Batching | Query DoS |
+| Nesting | Depth-based DoS |
+| Authorization | Field-level access |
+
+---
+
+## Security Testing Checklist
+
+**Authentication:**
+- [ ] Test for bypass
+- [ ] Check credential strength
+- [ ] Verify token security
+
+**Authorization:**
+- [ ] Test BOLA/IDOR
+- [ ] Check privilege escalation
+- [ ] Verify function access
+
+**Input:**
+- [ ] Test all parameters
+- [ ] Check for injection
+
+**Config:**
+- [ ] Check CORS
+- [ ] Verify headers
+- [ ] Test error handling
+
+---
+
+> **Remember:** APIs are the backbone of modern apps. Test them like attackers will.
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [auth.md](auth.md) | Auth patterns to test |
+| [rate-limiting.md](rate-limiting.md) | Rate limit bypass testing |
+| [graphql.md](graphql.md) | GraphQL-specific security |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: trpc
+
+---
+name: trpc
+description: tRPC router patterns, Zod validation, React Query client for TypeScript monorepos
+---
+
+# tRPC Principles
+
+> End-to-end type safety for TypeScript monorepos — zero code generation.
+
+---
+
+## When to Use
+
+```
+✅ Perfect fit:
+├── TypeScript on both ends
+├── Monorepo structure
+├── Internal tools / dashboards
+├── Rapid development
+└── Type safety is critical
+
+❌ Poor fit:
+├── Non-TypeScript clients
+├── Public API (need OpenAPI docs)
+├── Need REST conventions (caching)
+└── Multiple language backends
+```
+
+## Router Definition
+
+```typescript
+// server/trpc.ts — Base setup
+import { initTRPC, TRPCError } from '@trpc/server';
+import { z } from 'zod';
+
+const t = initTRPC.context<Context>().create();
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+export const protectedProcedure = t.procedure.use(isAuthed);
+```
+
+```typescript
+// server/routers/user.ts — Router with Zod validation
+export const userRouter = router({
+  getById: publicProcedure
+    .input(z.string().uuid())
+    .query(async ({ input, ctx }) => {
+      const user = await ctx.db.user.findUnique({ where: { id: input } });
+      if (!user) throw new TRPCError({ code: 'NOT_FOUND' });
+      return user;
+    }),
+
+  create: protectedProcedure
+    .input(z.object({
+      name: z.string().min(1).max(100),
+      email: z.string().email(),
+      role: z.enum(['user', 'admin']).default('user'),
+    }))
+    .mutation(async ({ input, ctx }) => {
+      return ctx.db.user.create({ data: input });
+    }),
+
+  list: publicProcedure
+    .input(z.object({
+      page: z.number().int().min(1).default(1),
+      limit: z.number().int().min(1).max(100).default(20),
+    }))
+    .query(async ({ input, ctx }) => {
+      const { page, limit } = input;
+      const [data, total] = await Promise.all([
+        ctx.db.user.findMany({ skip: (page - 1) * limit, take: limit }),
+        ctx.db.user.count(),
+      ]);
+      return { data, total, totalPages: Math.ceil(total / limit) };
+    }),
+});
+```
+
+## Client Usage (React Query)
+
+```typescript
+// Client — fully typed, zero codegen
+import { trpc } from '~/utils/trpc';
+
+function UserProfile({ id }: { id: string }) {
+  const { data: user } = trpc.user.getById.useQuery(id);
+  const createUser = trpc.user.create.useMutation();
+
+  // Autocomplete works across the full stack
+  return <div>{user?.name}</div>;
+}
+```
+
+## Integration Patterns
+
+| Setup | Framework | Notes |
+|-------|-----------|-------|
+| Next.js + tRPC | `@trpc/next` | App Router + RSC support |
+| Remix + tRPC | Custom adapter | Less common |
+| Monorepo | Shared `@repo/trpc` package | Most scalable |
+| Standalone | Express adapter | `@trpc/server/adapters/express` |
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Use tRPC for public APIs | Use REST + OpenAPI for public |
+| Skip Zod validation | Always validate with `.input(z.object(...))` |
+| Put all routes in one file | Split into domain routers (`userRouter`, `postRouter`) |
+| Catch errors silently | Throw `TRPCError` with proper codes |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [api-style.md](api-style.md) | REST vs GraphQL vs tRPC decision |
+| [auth.md](auth.md) | Auth middleware patterns |
+| [SKILL.md](../SKILL.md) | Full decision framework |
+
+---
+
+### Rule: versioning
+
+---
+name: versioning
+description: API versioning strategies — URI, header, query; deprecation and sunset policies
+---
+
+# Versioning Strategies
+
+> Plan for API evolution from day one.
+
+---
+
+## Strategy Selection
+
+| Strategy | Implementation | Best For | Trade-offs |
+|----------|---------------|----------|------------|
+| **URI** | `/v1/users` | Public APIs | Clear, easy caching; URL pollution |
+| **Header** | `Accept-Version: 1` | Internal APIs | Clean URLs; harder discovery |
+| **Query** | `?version=1` | Quick prototypes | Easy to add; messy, cache-unfriendly |
+| **None** | Evolve carefully | GraphQL, tRPC | Simplest; risky for REST public APIs |
+
+## Decision Guide
+
+```
+Is it a public REST API?
+├── Yes → URI versioning (/v1/users)
+│         Most discoverable, best tooling support
+│
+├── Internal REST only? → Header versioning
+│         Cleaner URLs, version-aware clients
+│
+├── GraphQL? → No versioning (evolve schema)
+│         Add fields, deprecate old ones
+│
+└── tRPC? → No versioning (types enforce compat)
+          Breaking changes caught at compile time
+```
+
+## URI Versioning Example
+
+```typescript
+// Express — version in path
+import { Router } from 'express';
+
+const v1 = Router();
+v1.get('/users', getUsersV1);
+v1.get('/users/:id', getUserByIdV1);
+
+const v2 = Router();
+v2.get('/users', getUsersV2);        // Changed response format
+v2.get('/users/:id', getUserByIdV2);
+
+app.use('/api/v1', v1);
+app.use('/api/v2', v2);
+```
+
+## Deprecation & Sunset
+
+```typescript
+// Deprecation headers (RFC 8594)
+app.use('/api/v1', (req, res, next) => {
+  res.set('Deprecation', 'true');
+  res.set('Sunset', 'Sat, 01 Jun 2026 00:00:00 GMT');
+  res.set('Link', '</api/v2>; rel="successor-version"');
+  next();
+});
+```
+
+**Sunset Policy:**
+1. Announce deprecation with `Deprecation: true` header
+2. Set `Sunset` date (minimum 6 months for public APIs)
+3. Include `Link` header pointing to successor
+4. Monitor usage — notify active consumers
+5. Remove after sunset date
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Version after breaking changes | Define strategy before first endpoint |
+| Remove old version without notice | Sunset with 6+ months warning |
+| Mix versioning strategies | Pick one approach |
+| Version internal tRPC APIs | Let TypeScript catch breaking changes |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [rest.md](rest.md) | REST endpoint design |
+| [documentation.md](documentation.md) | Documenting versions |
+| [api-style.md](api-style.md) | API style decision |
+
+---
+
+⚡ PikaKit v3.9.134