agent-skill-kit 3.9.135

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

@@ -0,0 +1,173 @@
+---
+name: api-architect
+description: >-
+  API design patterns for REST, GraphQL, and tRPC services.
+  Use when designing endpoints, versioning APIs, or choosing API architecture.
+  NOT for code implementation (use nodejs-pro/python-pro) or database schema (use data-modeler).
+category: architecture
+triggers: ["API design", "REST", "GraphQL", "tRPC", "endpoint", "versioning"]
+coordinates_with: ["data-modeler", "security-scanner", "auth-patterns", "nodejs-pro"]
+success_metrics: ["0 breaking API changes without explicit version bump", "100% compliant with OWASP API Top 10"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

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

@@ -0,0 +1,35 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. General (general)
+
+**Impact:** HIGH  
+**Description:** General patterns and best practices.
+
+## 2. API Design (api)
+
+**Impact:** HIGH  
+**Description:** RESTful, GraphQL, and tRPC API design patterns and best practices.
+
+## 3. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 4. Rate (rate)
+
+**Impact:** LOW  
+**Description:** Rate patterns and best practices.
+
+## 5. Security Patterns (security)
+
+**Impact:** CRITICAL  
+**Description:** Security-first patterns to prevent vulnerabilities and protect user data.
+
+---
+
+⚡ PikaKit v3.9.134

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

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

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

@@ -0,0 +1,115 @@
+---
+name: api-style
+description: REST vs GraphQL vs tRPC decision tree with code comparisons
+title: "API Style Selection"
+impact: HIGH
+impactDescription: "Important architectural or correctness impact"
+tags: api, style
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

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

@@ -0,0 +1,134 @@
+---
+name: auth
+description: API authentication patterns — JWT, OAuth2 PKCE, API Keys, Passkeys, token refresh
+title: "Authentication Patterns"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: auth
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134

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

@@ -0,0 +1,131 @@
+---
+name: documentation
+description: OpenAPI 3.1 specs, Swagger UI setup, API documentation best practices
+title: "API Documentation Principles"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: documentation
+---
+
+# 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 |
+
+---
+
+⚡ PikaKit v3.9.134