@valentia-ai-skills/framework 1.0.0

package/skills/global/api-design/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: api-design
+description: >
+  Organization-wide API design standards for REST and GraphQL APIs. Use this skill
+  whenever writing, reviewing, or designing API endpoints, routes, controllers,
+  resolvers, request/response schemas, error responses, pagination, filtering,
+  versioning, or any server-side request handling. Triggers on: "API", "endpoint",
+  "route", "controller", "REST", "GraphQL", "request", "response", "status code",
+  "pagination", "filtering", "versioning", "CRUD", "resource", "middleware",
+  "interceptor", "guard", "serializer", "DTO". Applies to all backend stacks.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# API Design Standards
+
+## Overview
+
+Consistent API design across all teams ensures that frontend developers, mobile
+developers, and third-party consumers can predictably interact with any service
+in the organization. These standards apply to both REST and GraphQL APIs.
+
+## 1. URL Structure (REST)
+
+### Resource Naming
+- Use **plural nouns** for resources: `/users`, `/orders`, `/products`
+- Use **kebab-case** for multi-word resources: `/order-items`, `/user-profiles`
+- Nest resources to express relationships (max 2 levels deep)
+- Never use verbs in URLs — HTTP methods express the action
+
+✅ Good:
+```
+GET    /users                    # list users
+GET    /users/:id                # get single user
+POST   /users                    # create user
+PATCH  /users/:id                # partial update
+DELETE /users/:id                # delete user
+GET    /users/:id/orders         # list user's orders
+GET    /users/:id/orders/:orderId # specific order for user
+```
+
+❌ Bad:
+```
+GET    /getUsers                 # verb in URL
+GET    /user/list                # singular + verb
+POST   /createUser               # verb in URL
+GET    /users/:id/orders/:orderId/items/:itemId/reviews  # too deep (3 levels)
+```
+
+### Nesting Rule
+If nesting exceeds 2 levels, flatten with query parameters:
+```
+# Instead of: GET /users/:id/orders/:orderId/items
+# Use:        GET /order-items?orderId=123
+```
+
+## 2. HTTP Methods & Status Codes
+
+### Method Usage
+| Method | Purpose | Idempotent | Request Body |
+|--------|---------|------------|-------------|
+| GET | Read resource(s) | Yes | No |
+| POST | Create resource | No | Yes |
+| PATCH | Partial update | Yes | Yes (partial) |
+| PUT | Full replace | Yes | Yes (complete) |
+| DELETE | Remove resource | Yes | No |
+
+### Status Code Reference
+
+**Success:**
+| Code | When to Use |
+|------|------------|
+| 200 | Successful GET, PATCH, PUT |
+| 201 | Successful POST (resource created) |
+| 204 | Successful DELETE (no response body) |
+
+**Client Errors:**
+| Code | When to Use |
+|------|------------|
+| 400 | Invalid request body / validation failure |
+| 401 | Not authenticated (missing/invalid token) |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, version mismatch) |
+| 422 | Semantically invalid (valid JSON but bad data) |
+| 429 | Rate limited |
+
+**Server Errors:**
+| Code | When to Use |
+|------|------------|
+| 500 | Unexpected server error |
+| 502 | Bad gateway / upstream failure |
+| 503 | Service unavailable (maintenance, overload) |
+
+### Common Mistakes
+- ❌ Returning 200 for errors with `{ success: false }` — use proper status codes
+- ❌ Returning 500 for validation errors — use 400 or 422
+- ❌ Returning 403 when you mean 401 — 401 = "who are you?", 403 = "you can't do that"
+
+## 3. Request & Response Format
+
+### Standard Response Envelope
+
+All API responses follow this structure:
+
+**Success (single resource):**
+```json
+{
+  "data": {
+    "id": "usr_abc123",
+    "email": "alice@example.com",
+    "name": "Alice",
+    "createdAt": "2026-03-19T10:30:00Z"
+  }
+}
+```
+
+**Success (collection):**
+```json
+{
+  "data": [
+    { "id": "usr_abc123", "name": "Alice" },
+    { "id": "usr_def456", "name": "Bob" }
+  ],
+  "pagination": {
+    "page": 1,
+    "pageSize": 20,
+    "totalItems": 156,
+    "totalPages": 8
+  }
+}
+```
+
+**Error:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request data",
+    "details": [
+      { "field": "email", "message": "Must be a valid email address" },
+      { "field": "age", "message": "Must be at least 13" }
+    ]
+  }
+}
+```
+
+### Rules
+- Always wrap data in a `data` key (even single resources)
+- Always wrap errors in an `error` key with `code`, `message`, and optional `details`
+- Use ISO 8601 for all dates: `2026-03-19T10:30:00Z`
+- Use camelCase for JSON keys
+- Use prefixed IDs where possible: `usr_abc123`, `ord_def456`
+- Never expose internal database IDs or auto-increment integers to clients
+
+## 4. Pagination
+
+### Standard: Offset-Based (default)
+```
+GET /users?page=2&pageSize=20
+```
+
+Response includes `pagination` object (see above).
+
+### Alternative: Cursor-Based (for large datasets)
+```
+GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
+```
+
+Response:
+```json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTQzfQ",
+    "hasMore": true
+  }
+}
+```
+
+### Rules
+- Default page size: 20
+- Maximum page size: 100
+- Always include total count for offset pagination
+- Use cursor pagination for feeds, timelines, or datasets > 10K records
+
+## 5. Filtering & Sorting
+
+### Filtering
+```
+GET /users?status=active&role=admin
+GET /orders?createdAfter=2026-01-01&createdBefore=2026-03-01
+GET /products?minPrice=10&maxPrice=100
+```
+
+### Sorting
+```
+GET /users?sort=createdAt:desc
+GET /products?sort=price:asc,name:asc
+```
+
+Format: `field:direction` with comma separation for multiple sorts.
+
+## 6. Versioning
+
+### URL-Based Versioning (preferred)
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Rules
+- Version in the URL path, not headers
+- Only bump major version for breaking changes
+- Support previous version for minimum 6 months after deprecation
+- Add `Sunset` header to deprecated versions:
+  ```
+  Sunset: Sat, 01 Oct 2026 00:00:00 GMT
+  ```
+
+## 7. Rate Limiting
+
+All APIs must implement rate limiting:
+
+- Include rate limit headers in every response:
+  ```
+  X-RateLimit-Limit: 100
+  X-RateLimit-Remaining: 95
+  X-RateLimit-Reset: 1679290800
+  ```
+- Return 429 when limit exceeded
+- Default limits: 100 requests/minute per authenticated user
+
+## Checklist
+
+Before finalizing any API code:
+- [ ] URLs use plural nouns, kebab-case, no verbs
+- [ ] Correct HTTP methods and status codes
+- [ ] Response wrapped in `data` or `error` envelope
+- [ ] Dates in ISO 8601 format
+- [ ] JSON keys in camelCase
+- [ ] Pagination included for list endpoints
+- [ ] Input validation on all endpoints (see security-baseline skill)
+- [ ] No internal IDs exposed to clients
+- [ ] Rate limiting headers present
+- [ ] API versioned in URL path

package/skills/global/api-design/tests/test-prompts.md

@@ -0,0 +1,25 @@
+## Test 1: CRUD Endpoint Design
+**Prompt**: "Design the REST API endpoints for a blog post system with posts, comments, and tags"
+**Expected**:
+- Plural nouns: /posts, /comments, /tags
+- Proper nesting: /posts/:id/comments (max 2 levels)
+- All CRUD methods with correct status codes
+- Response envelope with data/error pattern
+- Pagination on list endpoints
+
+## Test 2: Error Handling
+**Prompt**: "Write the error handling middleware for an Express API that returns consistent error responses"
+**Expected**:
+- Error envelope: { error: { code, message, details } }
+- Correct status codes (400 for validation, 401 for auth, 404 for not found)
+- No stack traces or internal details exposed
+- Proper differentiation between 401 and 403
+
+## Test 3: Complex Query Endpoint
+**Prompt**: "Build a product search endpoint with filtering by price range, category, and rating, with sorting and pagination"
+**Expected**:
+- Query params: minPrice, maxPrice, category, minRating
+- Sort format: sort=price:asc
+- Offset pagination with page, pageSize, totalItems
+- Default and max page sizes enforced
+- Input validation on all query params

package/skills/global/code-standards/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: code-standards
+description: >
+  Organization-wide coding standards and conventions. Use this skill whenever
+  writing, reviewing, or refactoring ANY code — regardless of language or stack.
+  Triggers on: writing functions, classes, components, modules, variables,
+  constants, files, folders, imports, exports, or any code structure. Also
+  triggers when asked to "clean up", "refactor", "fix style", "rename",
+  "restructure", or "organize" code. This skill applies to ALL programming
+  languages and stacks used in the organization.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Code Standards
+
+## Overview
+
+These are the organization-wide coding conventions that every team must follow.
+They ensure consistency across all projects, make code reviews faster, and
+reduce cognitive load when developers move between teams.
+
+## 1. Naming Conventions
+
+### Variables & Functions
+- Use `camelCase` for variables, functions, and method names
+- Use descriptive names — optimize for readability, not brevity
+- Boolean variables start with `is`, `has`, `can`, `should`
+- Functions that return booleans follow the same prefix pattern
+- Event handlers prefixed with `handle` (components) or `on` (props)
+
+✅ Good:
+```
+const isUserActive = true;
+const hasPermission = checkPermission(user);
+function calculateTotalPrice(items) { ... }
+function handleFormSubmit(event) { ... }
+```
+
+❌ Bad:
+```
+const active = true;          // unclear what is active
+const flag = check(u);        // meaningless names
+function calc(i) { ... }      // too abbreviated
+function submit(e) { ... }    // missing handle prefix
+```
+
+### Classes & Types
+- Use `PascalCase` for classes, interfaces, types, enums
+- Interfaces do NOT use `I` prefix (no `IUser`, just `User`)
+- Type aliases use `PascalCase`
+- Enum members use `UPPER_SNAKE_CASE`
+
+✅ Good:
+```
+class UserService { ... }
+interface UserProfile { ... }
+type ApiResponse<T> = { ... }
+enum UserRole { ADMIN, EDITOR, VIEWER }
+```
+
+❌ Bad:
+```
+class userService { ... }     // wrong case
+interface IUserProfile { ... } // no I prefix
+enum UserRole { admin, Editor } // inconsistent casing
+```
+
+### Files & Folders
+- Use `kebab-case` for file and folder names
+- One primary export per file
+- File name matches the primary export (in kebab-case)
+- Test files: `{filename}.test.{ext}` or `{filename}.spec.{ext}`
+
+✅ Good:
+```
+user-service.ts       → exports class UserService
+calculate-price.ts    → exports function calculatePrice
+user-profile.tsx      → exports component UserProfile
+user-service.test.ts  → tests for UserService
+```
+
+❌ Bad:
+```
+UserService.ts        // PascalCase file name
+utils.ts              // vague, multi-export dumping ground
+helpers/misc.ts       // meaningless names
+```
+
+### Constants
+- Use `UPPER_SNAKE_CASE` for true constants (compile-time values)
+- Use `camelCase` for runtime constants (values that don't change but are computed)
+
+```
+const MAX_RETRY_COUNT = 3;           // true constant
+const API_BASE_URL = "/api/v1";      // true constant
+const defaultConfig = loadConfig();   // runtime constant
+```
+
+## 2. File Structure
+
+### Maximum File Length
+- **Hard limit**: 300 lines per file
+- If a file exceeds 300 lines, it must be split into smaller modules
+- Exception: generated files, data fixtures, and type definitions
+
+### Import Order (enforced)
+Group imports in this order, separated by blank lines:
+1. External packages (node_modules)
+2. Internal packages / aliases (@ paths)
+3. Relative imports (../ and ./)
+4. Type-only imports
+5. Side-effect imports
+
+```typescript
+// 1. External
+import express from "express";
+import { z } from "zod";
+
+// 2. Internal
+import { UserService } from "@/services/user-service";
+import { logger } from "@/lib/logger";
+
+// 3. Relative
+import { formatDate } from "../utils/date";
+import { Button } from "./button";
+
+// 4. Types
+import type { User } from "@/types/user";
+
+// 5. Side effects
+import "./styles.css";
+```
+
+### Export Rules
+- Prefer named exports over default exports (except React components)
+- One primary export per file
+- Re-export from index files for clean public APIs
+
+## 3. Functions
+
+### Size & Complexity
+- Maximum 40 lines per function
+- Maximum 3 levels of nesting
+- Maximum 4 parameters (use an options object for more)
+- Single responsibility — each function does ONE thing
+
+### Parameter Objects
+When a function needs more than 4 parameters, use a typed options object:
+
+✅ Good:
+```typescript
+interface CreateUserOptions {
+  name: string;
+  email: string;
+  role: UserRole;
+  department: string;
+  managerId?: string;
+}
+
+function createUser(options: CreateUserOptions) { ... }
+```
+
+❌ Bad:
+```typescript
+function createUser(name, email, role, dept, managerId, isActive) { ... }
+```
+
+### Return Early
+Use early returns to reduce nesting:
+
+✅ Good:
+```typescript
+function processOrder(order: Order) {
+  if (!order) return null;
+  if (!order.isValid) return { error: "Invalid order" };
+  if (order.isPaid) return order;
+  
+  return processPayment(order);
+}
+```
+
+❌ Bad:
+```typescript
+function processOrder(order: Order) {
+  if (order) {
+    if (order.isValid) {
+      if (!order.isPaid) {
+        return processPayment(order);
+      } else {
+        return order;
+      }
+    } else {
+      return { error: "Invalid order" };
+    }
+  }
+  return null;
+}
+```
+
+## 4. Error Handling
+
+- Never swallow errors silently — always log or rethrow
+- Use custom error classes for domain-specific errors
+- Include context in error messages (what failed, with what input)
+- Use try/catch at service boundaries, not around every line
+
+✅ Good:
+```typescript
+try {
+  const user = await userService.findById(userId);
+} catch (error) {
+  logger.error("Failed to fetch user", { userId, error: error.message });
+  throw new UserNotFoundError(`User ${userId} not found`, { cause: error });
+}
+```
+
+❌ Bad:
+```typescript
+try {
+  const user = await userService.findById(userId);
+} catch (e) {
+  // silently ignored
+}
+```
+
+## 5. Comments
+
+- Code should be self-documenting — comments explain WHY, not WHAT
+- Use JSDoc/docstrings for public APIs and exported functions
+- Delete commented-out code — that's what git history is for
+- TODO comments must include a ticket number: `// TODO(PROJ-123): description`
+
+## 6. Formatting Checklist
+
+Before finalizing any code output, verify:
+- [ ] All names follow the casing conventions above
+- [ ] File is under 300 lines
+- [ ] Functions are under 40 lines with ≤ 3 nesting levels
+- [ ] Imports are grouped in the correct order
+- [ ] No silent error swallowing
+- [ ] No commented-out code
+- [ ] Boolean variables use is/has/can/should prefix

package/skills/global/code-standards/tests/test-prompts.md

@@ -0,0 +1,26 @@
+## Test 1: New Function Creation
+**Prompt**: "Write a function that fetches a user from the database by email, checks if they're active, and returns their profile with recent orders"
+**Expected**: 
+- Function named descriptively (e.g., `getUserProfileWithOrders`)
+- Parameters use camelCase
+- Boolean check uses `isActive` pattern
+- Error handling with context
+- Under 40 lines, early returns
+
+## Test 2: Refactoring Messy Code
+**Prompt**: "Refactor this: `function do_stuff(a, b, c, d, e, f) { try { if (a) { if (b) { if (c) { return process(d, e, f); } } } } catch(e) {} }`"
+**Expected**:
+- Renamed to descriptive name
+- Parameters grouped into options object (>4 params)
+- Nesting reduced via early returns
+- Error handling added (not swallowed)
+- camelCase naming
+
+## Test 3: File Organization
+**Prompt**: "Create a user registration module with validation, database save, email notification, and audit logging"
+**Expected**:
+- Split into multiple files (not one 500-line file)
+- kebab-case file names
+- Proper import ordering
+- Named exports
+- Each file has single responsibility