cortexhawk 3.1.0

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

@@ -0,0 +1,103 @@
+---
+name: api-design
+description: REST API conventions — URL structure, pagination, error responses, versioning, and HATEOAS basics.
+detect: package.json:express package.json:fastify requirements.txt:fastapi pyproject.toml:fastapi
+---
+
+# API Design
+
+## URL Structure
+```
+GET    /api/v1/users          # List (paginated)
+POST   /api/v1/users          # Create
+GET    /api/v1/users/:id      # Read
+PUT    /api/v1/users/:id      # Full update
+PATCH  /api/v1/users/:id      # Partial update
+DELETE /api/v1/users/:id      # Delete
+
+# Nested resources (max 2 levels)
+GET    /api/v1/users/:id/orders
+POST   /api/v1/users/:id/orders
+
+# Filters, sorting, search via query params
+GET    /api/v1/users?status=active&sort=-created_at&q=john
+```
+
+## Pagination
+```json
+// Cursor-based (preferred for large datasets)
+GET /api/v1/items?cursor=abc123&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "def456",
+    "has_more": true,
+    "limit": 20
+  }
+}
+
+// Offset-based (simpler, fine for small datasets)
+GET /api/v1/items?page=2&per_page=20
+
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "per_page": 20,
+    "total": 150,
+    "total_pages": 8
+  }
+}
+```
+
+## Error Response Shape
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "email", "message": "must be a valid email address" },
+      { "field": "age", "message": "must be >= 0" }
+    ]
+  }
+}
+```
+
+## HTTP Status Codes
+| Code | When |
+|---|---|
+| 200 | Success (GET, PUT, PATCH) |
+| 201 | Created (POST) |
+| 204 | No content (DELETE) |
+| 400 | Validation error, malformed request |
+| 401 | Not authenticated |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, state mismatch) |
+| 422 | Semantically invalid (valid JSON, wrong values) |
+| 429 | Rate limited |
+| 500 | Server error (never expose internals) |
+
+## Versioning
+```
+# URL path (simple, explicit)
+/api/v1/users
+/api/v2/users
+
+# Header (cleaner URLs, harder to test)
+Accept: application/vnd.api+json; version=2
+```
+
+Prefer URL path versioning. Only bump major version for breaking changes.
+
+## Checklist
+- Nouns for resources, never verbs (`/users` not `/getUsers`)
+- Plural resource names (`/users` not `/user`)
+- Consistent error shape across all endpoints
+- Pagination on ALL list endpoints — never return unbounded results
+- Rate limiting with `Retry-After` header
+- `Content-Type: application/json` on all responses
+- CORS configured for allowed origins only
+- Idempotency keys on POST endpoints for safe retries

package/skills/frameworks/fastapi/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: fastapi
+description: FastAPI routes, Pydantic models, dependencies, middleware, and async patterns.
+detect: requirements.txt:fastapi pyproject.toml:fastapi
+---
+
+# FastAPI
+
+## Route Patterns
+```python
+from fastapi import FastAPI, HTTPException, Depends, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+class ItemCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    price: float = Field(..., gt=0)
+
+class ItemResponse(BaseModel):
+    id: int
+    name: str
+    price: float
+    model_config = {"from_attributes": True}
+
+@app.get("/items/{item_id}", response_model=ItemResponse)
+async def get_item(item_id: int):
+    item = await db.get(item_id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    return item
+
+@app.post("/items", response_model=ItemResponse, status_code=201)
+async def create_item(item: ItemCreate):
+    return await db.create(item.model_dump())
+```
+
+## Dependencies
+```python
+async def get_current_user(token: str = Depends(oauth2_scheme)):
+    user = await verify_token(token)
+    if not user:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return user
+
+@app.get("/me")
+async def read_me(user: User = Depends(get_current_user)):
+    return user
+```
+
+## Middleware
+```python
+@app.middleware("http")
+async def add_correlation_id(request: Request, call_next):
+    request.state.correlation_id = str(uuid4())
+    response = await call_next(request)
+    response.headers["X-Correlation-ID"] = request.state.correlation_id
+    return response
+```
+
+## Checklist
+- Pydantic models for ALL request/response bodies — never use raw dicts
+- `response_model` on every route to control output shape
+- Use `Depends()` for auth, DB sessions, shared logic — not global state
+- Async routes for I/O-bound work, sync for CPU-bound
+- `HTTPException` with clear status codes and detail messages
+- Background tasks via `BackgroundTasks` for non-blocking work
+- Use `lifespan` context manager for startup/shutdown logic

package/skills/frameworks/nextjs/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: nextjs
+description: Next.js App Router, Server/Client Components, API routes, caching, and data fetching.
+detect: package.json:next
+---
+
+# Next.js (App Router)
+
+## File Conventions
+```
+app/
+├── layout.tsx           # Root layout (required)
+├── page.tsx             # Home page
+├── loading.tsx          # Loading UI (Suspense boundary)
+├── error.tsx            # Error boundary ('use client')
+├── not-found.tsx        # 404 page
+├── api/route.ts         # API route handler
+└── [slug]/page.tsx      # Dynamic route
+```
+
+## Server vs Client Components
+```tsx
+// Server Component (default) — access DB, secrets, no hooks
+export default async function Page() {
+  const data = await db.query('SELECT * FROM items');
+  return <ItemList items={data} />;
+}
+
+// Client Component — interactivity, hooks, browser APIs
+'use client';
+export default function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+## Data Fetching
+```tsx
+// Server Component — fetch with caching
+async function getData() {
+  const res = await fetch('https://api.example.com/data', {
+    next: { revalidate: 3600 } // ISR: revalidate every hour
+  });
+  if (!res.ok) throw new Error('Failed to fetch');
+  return res.json();
+}
+```
+
+## API Routes
+```typescript
+// app/api/items/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const items = await db.findMany();
+  return NextResponse.json(items);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const item = await db.create(body);
+  return NextResponse.json(item, { status: 201 });
+}
+```
+
+## Checklist
+- Default to Server Components — add `'use client'` only when needed (hooks, events, browser APIs)
+- Fetch data in Server Components, pass to Client Components as props
+- Use `loading.tsx` for Suspense boundaries, `error.tsx` for error boundaries
+- API routes in `app/api/` — use `NextRequest`/`NextResponse`
+- Dynamic routes: `[slug]` for single, `[...slug]` for catch-all
+- Metadata: export `metadata` object or `generateMetadata` function
+- Use `redirect()` and `notFound()` from `next/navigation`
+- Environment: `NEXT_PUBLIC_` prefix for client-exposed vars

package/skills/frameworks/python/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: python
+description: Python typing, async/await, packaging, virtual environments, and best practices.
+detect: requirements.txt pyproject.toml
+---
+
+# Python
+
+## Typing
+```python
+from typing import TypeVar, Generic, Protocol
+from collections.abc import Sequence, Callable
+
+# Function annotations
+def process(items: list[str], limit: int = 10) -> dict[str, int]:
+    return {item: len(item) for item in items[:limit]}
+
+# TypeVar for generics
+T = TypeVar('T')
+def first(items: Sequence[T]) -> T | None:
+    return items[0] if items else None
+
+# Protocol for structural typing
+class Readable(Protocol):
+    def read(self) -> str: ...
+
+def load(source: Readable) -> str:
+    return source.read()
+```
+
+## Async/Await
+```python
+import asyncio
+from contextlib import asynccontextmanager
+
+async def fetch_all(urls: list[str]) -> list[dict]:
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_one(session, url) for url in urls]
+        return await asyncio.gather(*tasks)
+
+@asynccontextmanager
+async def get_db():
+    conn = await create_connection()
+    try:
+        yield conn
+    finally:
+        await conn.close()
+```
+
+## Packaging
+```toml
+# pyproject.toml
+[project]
+name = "myproject"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["fastapi>=0.100", "pydantic>=2.0"]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy"]
+
+[tool.ruff]
+line-length = 88
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+```
+
+## Virtual Environments
+```bash
+# Create and activate
+python -m venv .venv
+source .venv/bin/activate    # Linux/macOS
+.venv\Scripts\activate       # Windows
+
+# Modern alternative: uv
+uv venv && uv pip install -r requirements.txt
+```
+
+## Checklist
+- Type hints on all public functions — use `mypy --strict`
+- `list[str]` not `List[str]` (Python 3.9+)
+- `X | None` not `Optional[X]` (Python 3.10+)
+- Dataclasses or Pydantic for structured data — not raw dicts
+- `pathlib.Path` over `os.path` for file operations
+- Context managers for resource management (files, connections, locks)
+- f-strings for formatting — not `.format()` or `%`
+- Use `ruff` for linting + formatting (replaces flake8, isort, black)

package/skills/frameworks/react/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: react
+description: React hooks patterns, state management, memoization, Suspense, and error boundaries.
+detect: package.json:react
+---
+
+# React
+
+## Hooks Patterns
+```tsx
+// Custom hook — extract reusable logic
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+
+// Data fetching hook
+function useQuery<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    fetch(url, { signal: controller.signal })
+      .then(r => r.json()).then(setData)
+      .catch(e => { if (e.name !== 'AbortError') setError(e); })
+      .finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [url]);
+
+  return { data, error, loading };
+}
+```
+
+## Memoization
+```tsx
+// Memo — skip re-render if props unchanged
+const ExpensiveList = memo(function ExpensiveList({ items }: Props) {
+  return items.map(item => <Item key={item.id} {...item} />);
+});
+
+// useMemo — expensive computation
+const sorted = useMemo(() => items.sort(compareFn), [items]);
+
+// useCallback — stable function reference for child props
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []);
+```
+
+## Error Boundaries
+```tsx
+class ErrorBoundary extends Component<Props, { error: Error | null }> {
+  state = { error: null };
+  static getDerivedStateFromError(error: Error) { return { error }; }
+  render() {
+    if (this.state.error) return this.props.fallback;
+    return this.props.children;
+  }
+}
+
+// Usage
+<ErrorBoundary fallback={<ErrorMessage />}>
+  <Suspense fallback={<Loading />}>
+    <AsyncComponent />
+  </Suspense>
+</ErrorBoundary>
+```
+
+## Checklist
+- Custom hooks for shared logic — prefix with `use`
+- `useEffect` cleanup: abort controllers, clear timers, unsubscribe
+- Memo only when profiler shows re-render bottleneck — don't premature optimize
+- Keys must be stable IDs — never use array index for dynamic lists
+- Avoid derived state — compute from props/state directly
+- `useRef` for values that don't trigger re-render (timers, DOM refs, previous values)
+- Colocate state — lift up only when siblings need it
+- Suspense + Error Boundaries for async content

package/skills/frameworks/sveltekit/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: sveltekit
+description: SvelteKit routing, load functions, form actions, hooks, and SSR/CSR patterns.
+detect: package.json:svelte
+---
+
+# SvelteKit
+
+## Routing
+```
+src/routes/
+├── +page.svelte          # Page component
+├── +page.ts              # Universal load (runs server + client)
+├── +page.server.ts       # Server-only load + form actions
+├── +layout.svelte        # Shared layout
+├── +layout.server.ts     # Layout data loading
+├── +error.svelte         # Error boundary
+├── +server.ts            # API endpoint (GET, POST, PUT, DELETE)
+└── [slug]/+page.svelte   # Dynamic route
+```
+
+## Load Functions
+```typescript
+// +page.server.ts — server-only, access DB/secrets
+export const load: PageServerLoad = async ({ params, locals }) => {
+  const item = await db.get(params.id);
+  if (!item) throw error(404, 'Not found');
+  return { item };
+};
+
+// +page.ts — universal, runs on server then client
+export const load: PageLoad = async ({ fetch, params }) => {
+  const res = await fetch(`/api/items/${params.id}`);
+  return { item: await res.json() };
+};
+```
+
+## Form Actions
+```typescript
+// +page.server.ts
+export const actions: Actions = {
+  default: async ({ request, locals }) => {
+    const data = await request.formData();
+    const name = data.get('name');
+    if (!name) return fail(400, { name, missing: true });
+    await db.create({ name });
+    throw redirect(303, '/items');
+  }
+};
+```
+
+## Hooks
+```typescript
+// src/hooks.server.ts
+export const handle: Handle = async ({ event, resolve }) => {
+  const session = await getSession(event.cookies);
+  event.locals.user = session?.user;
+  return resolve(event);
+};
+```
+
+## Checklist
+- Use `+page.server.ts` for DB access, secrets, auth checks
+- Use `+page.ts` for data that can be fetched client-side
+- Form actions for mutations — progressive enhancement by default
+- `throw redirect()` and `throw error()` — don't return them
+- Use `$env/static/private` for server secrets, `$env/static/public` for client vars
+- Prerender static pages: `export const prerender = true`
+- Use `{@html}` sparingly — always sanitize user content

package/skills/frameworks/tailwindcss/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: tailwindcss
+description: Tailwind CSS utility-first patterns, responsive design, dark mode, and custom configuration.
+detect: package.json:tailwindcss
+---
+
+# Tailwind CSS
+
+## Core Patterns
+```html
+<!-- Responsive: mobile-first -->
+<div class="w-full md:w-1/2 lg:w-1/3">
+
+<!-- Dark mode -->
+<div class="bg-white dark:bg-gray-900 text-black dark:text-white">
+
+<!-- States -->
+<button class="bg-blue-500 hover:bg-blue-600 active:bg-blue-700 disabled:opacity-50">
+
+<!-- Focus visible (keyboard only) -->
+<input class="focus-visible:ring-2 focus-visible:ring-blue-500 outline-none">
+
+<!-- Group hover -->
+<div class="group">
+  <span class="group-hover:text-blue-500">Hover parent to change me</span>
+</div>
+```
+
+## Layout
+```html
+<!-- Flexbox -->
+<div class="flex items-center justify-between gap-4">
+
+<!-- Grid -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+
+<!-- Container with padding -->
+<div class="container mx-auto px-4">
+```
+
+## Common Components
+```html
+<!-- Card -->
+<div class="rounded-lg border bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-800">
+
+<!-- Badge -->
+<span class="inline-flex items-center rounded-full bg-blue-100 px-2.5 py-0.5 text-xs font-medium text-blue-800">
+
+<!-- Input -->
+<input class="w-full rounded-md border border-gray-300 px-3 py-2 text-sm placeholder:text-gray-400 focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500">
+```
+
+## Custom Config
+```javascript
+// tailwind.config.js
+export default {
+  content: ['./src/**/*.{js,ts,jsx,tsx,svelte,vue}'],
+  darkMode: 'class',
+  theme: {
+    extend: {
+      colors: { brand: { 500: '#6366f1', 600: '#4f46e5' } },
+      fontFamily: { sans: ['Inter', 'sans-serif'] },
+    },
+  },
+};
+```
+
+## Checklist
+- Mobile-first: write base styles, then `md:`, `lg:`, `xl:` overrides
+- Use `dark:` variant — pair with `class` strategy for toggle support
+- `@apply` in CSS only for highly reused utility combos (buttons, inputs)
+- Prefer `gap-*` over margins between flex/grid children
+- Use `sr-only` for screen-reader-only text
+- Purge unused styles via `content` config — keep bundle small
+- Custom colors in `theme.extend` — don't override defaults

package/skills/frameworks/typescript/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: typescript
+description: TypeScript strict mode, generics, utility types, type guards, and discriminated unions.
+detect: package.json
+---
+
+# TypeScript
+
+## Strict Config
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+## Generics
+```typescript
+// Constrained generic
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Generic with default
+type ApiResponse<T = unknown> = {
+  data: T;
+  status: number;
+  error?: string;
+};
+```
+
+## Utility Types
+```typescript
+Partial<T>          // All props optional
+Required<T>         // All props required
+Pick<T, K>          // Subset of props
+Omit<T, K>          // Remove props
+Record<K, V>        // Key-value map
+ReturnType<F>       // Function return type
+Awaited<T>          // Unwrap Promise
+NonNullable<T>      // Remove null/undefined
+```
+
+## Type Guards
+```typescript
+// Custom type guard
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value;
+}
+
+// Discriminated union
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function handle<T>(result: Result<T>) {
+  if (result.success) {
+    console.log(result.data);    // TypeScript knows data exists
+  } else {
+    console.error(result.error); // TypeScript knows error exists
+  }
+}
+```
+
+## Patterns
+```typescript
+// Branded types for type safety
+type UserId = string & { readonly __brand: 'UserId' };
+function userId(id: string): UserId { return id as UserId; }
+
+// Const assertion for literal types
+const ROLES = ['admin', 'user', 'guest'] as const;
+type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
+
+// Satisfies — validate without widening
+const config = {
+  port: 3000,
+  host: 'localhost',
+} satisfies Record<string, string | number>;
+```
+
+## Checklist
+- `strict: true` always — no exceptions
+- `unknown` over `any` — force type narrowing
+- Discriminated unions for state machines and result types
+- Type guards for runtime validation of external data
+- `as const` for literal types, `satisfies` for validation without widening
+- No type assertions (`as`) unless you've exhausted narrowing options
+- Generic constraints with `extends` — don't leave generics unconstrained