agent-skill-kit 3.9.135

package/.agent/skills/api-architect/rules/rate-limiting.md

@@ -0,0 +1,76 @@
+---
+name: rate-limiting
+description: Rate limiting strategies — token bucket, sliding window, Redis implementation, recommended limits
+title: "Rate Limiting Principles"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: rate, limiting
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/api-architect/rules/response.md

@@ -0,0 +1,138 @@
+---
+name: response
+description: API response envelope pattern, error format, pagination, TypeScript types
+title: "Response Format Principles"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: response
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/api-architect/rules/rest.md

@@ -0,0 +1,113 @@
+---
+name: rest
+description: REST API design — resource naming, HTTP methods, status codes, filtering, sorting
+title: "REST Principles"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: rest
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/api-architect/rules/security-testing.md

@@ -0,0 +1,146 @@
+---
+name: security-testing
+description: OWASP API Top 10, JWT testing, BOLA/IDOR, authorization and input validation testing
+title: "API Security Testing"
+impact: HIGH
+impactDescription: "Important architectural or correctness impact"
+tags: security, 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 |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/api-architect/rules/trpc.md

@@ -0,0 +1,129 @@
+---
+name: trpc
+description: tRPC router patterns, Zod validation, React Query client for TypeScript monorepos
+title: "tRPC Principles"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: trpc
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/api-architect/rules/versioning.md

@@ -0,0 +1,100 @@
+---
+name: versioning
+description: API versioning strategies — URI, header, query; deprecation and sunset policies
+title: "Versioning Strategies"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: versioning
+---
+
+# 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