@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/express-nodejs/references/typescript-integration.md

@@ -1,357 +0,0 @@
-# Express TypeScript Integration
-
-## Project Setup
-
-### tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022"],
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}
-```
-
-### Required Dependencies
-
-```json
-{
-  "dependencies": {
-    "express": "^5.0.0",
-    "helmet": "^7.0.0",
-    "cors": "^2.8.5",
-    "express-rate-limit": "^7.0.0",
-    "zod": "^3.22.0",
-    "pino": "^8.0.0",
-    "pino-http": "^9.0.0"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.0",
-    "@types/cors": "^2.8.0",
-    "@types/node": "^20.0.0",
-    "typescript": "^5.4.0",
-    "tsx": "^4.0.0",
-    "vitest": "^1.0.0",
-    "supertest": "^6.0.0",
-    "@types/supertest": "^6.0.0"
-  }
-}
-```
-
-## Typed Request Handlers
-
-Express provides generic types for `Request` that allow typing params, body, query, and response.
-
-```typescript
-import { Request, Response, RequestHandler } from 'express';
-
-// Type parameters: Request<Params, ResBody, ReqBody, ReqQuery>
-interface CreateUserBody {
-  email: string;
-  name: string;
-  role: 'admin' | 'editor' | 'viewer';
-}
-
-interface UserResponse {
-  id: string;
-  email: string;
-  name: string;
-  role: string;
-  createdAt: string;
-}
-
-const createUser: RequestHandler<{}, UserResponse, CreateUserBody> = async (req, res) => {
-  // req.body is typed as CreateUserBody
-  const { email, name, role } = req.body;
-
-  const user = await userService.create({ email, name, role });
-
-  // res.json expects UserResponse
-  res.status(201).json(user);
-};
-```
-
-### Typed Path Parameters
-
-```typescript
-interface UserParams {
-  id: string;
-}
-
-const getUser: RequestHandler<UserParams> = async (req, res) => {
-  const { id } = req.params; // typed as string
-  const user = await userService.findById(id);
-  res.json(user);
-};
-
-// With multiple params
-interface OrgRepoParams {
-  orgId: string;
-  repoId: string;
-}
-
-const getRepo: RequestHandler<OrgRepoParams> = async (req, res) => {
-  const { orgId, repoId } = req.params;
-  // Both typed as string
-};
-```
-
-### Typed Query Parameters
-
-```typescript
-interface SearchQuery {
-  q?: string;
-  page?: string;
-  limit?: string;
-  sort?: 'asc' | 'desc';
-}
-
-const searchUsers: RequestHandler<{}, unknown, unknown, SearchQuery> = async (req, res) => {
-  const { q, page = '1', limit = '20', sort = 'asc' } = req.query;
-  // All typed correctly
-};
-```
-
-## Declaration Merging
-
-Extend the Express `Request` interface to add custom properties set by middleware.
-
-```typescript
-// src/types/express.d.ts
-declare global {
-  namespace Express {
-    interface Request {
-      user?: {
-        id: string;
-        email: string;
-        role: 'admin' | 'editor' | 'viewer';
-      };
-      requestId: string;
-      log: import('pino').Logger;
-    }
-  }
-}
-
-export {};
-```
-
-Now middleware and handlers can access `req.user`, `req.requestId`, and `req.log` with full type safety.
-
-```typescript
-// In middleware
-const authenticate: RequestHandler = async (req, res, next) => {
-  const payload = jwt.verify(token, secret) as JwtPayload;
-  req.user = {
-    id: payload.sub!,
-    email: payload.email,
-    role: payload.role,
-  };
-  next();
-};
-
-// In handler -- no casting needed
-const getProfile: RequestHandler = async (req, res) => {
-  const userId = req.user!.id; // TypeScript knows the shape
-  const profile = await profileService.get(userId);
-  res.json(profile);
-};
-```
-
-## App/Server Separation
-
-Separate app construction from listening for testability.
-
-```typescript
-// src/app.ts -- exports the configured app
-import express from 'express';
-import { errorHandler } from './middleware/error-handler';
-import { usersRouter } from './routes/users';
-
-export function createApp(deps: Dependencies) {
-  const app = express();
-
-  app.use(express.json({ limit: '100kb' }));
-  app.use('/api/v1/users', usersRouter(deps));
-  app.use(errorHandler);
-
-  return app;
-}
-
-// src/server.ts -- starts listening
-import { createApp } from './app';
-import { loadConfig } from './config';
-
-async function main() {
-  const config = loadConfig();
-  const deps = await initDependencies(config);
-  const app = createApp(deps);
-
-  const server = app.listen(config.port, () => {
-    console.log(`Server running on port ${config.port}`);
-  });
-
-  // Graceful shutdown
-  process.on('SIGTERM', () => {
-    server.close(() => {
-      deps.db.end();
-      process.exit(0);
-    });
-  });
-}
-
-main().catch(console.error);
-```
-
-## Typed Router Factory
-
-Create routers as factory functions that receive dependencies.
-
-```typescript
-// src/routes/users.ts
-import { Router } from 'express';
-import { validate } from '../middleware/validate';
-import { createUserSchema, updateUserSchema } from '../schemas/user';
-
-export function usersRouter(deps: Dependencies): Router {
-  const router = Router();
-  const { userService, authMiddleware, authorize } = deps;
-
-  router.use(authMiddleware);
-
-  router.get('/', async (req, res) => {
-    const users = await userService.list(req.query);
-    res.json(users);
-  });
-
-  router.post('/', validate({ body: createUserSchema }), async (req, res) => {
-    const user = await userService.create(req.body);
-    res.status(201).json(user);
-  });
-
-  router.get('/:id', async (req, res) => {
-    const user = await userService.findById(req.params.id);
-    res.json(user);
-  });
-
-  router.put('/:id', validate({ body: updateUserSchema }), async (req, res) => {
-    const user = await userService.update(req.params.id, req.body);
-    res.json(user);
-  });
-
-  router.delete('/:id', authorize('admin'), async (req, res) => {
-    await userService.delete(req.params.id);
-    res.status(204).end();
-  });
-
-  return router;
-}
-```
-
-## Zod Schema Integration
-
-Use Zod for runtime validation that also provides TypeScript types.
-
-```typescript
-import { z } from 'zod';
-
-// Define schema
-export const createUserSchema = z.object({
-  email: z.string().email(),
-  name: z.string().min(1).max(100),
-  role: z.enum(['admin', 'editor', 'viewer']),
-});
-
-// Extract TypeScript type from schema
-export type CreateUserDto = z.infer<typeof createUserSchema>;
-// { email: string; name: string; role: 'admin' | 'editor' | 'viewer' }
-
-// Use in service layer
-class UserService {
-  async create(data: CreateUserDto): Promise<User> {
-    // data is typed from the zod schema
-    return this.repo.insert(data);
-  }
-}
-```
-
-## Typed Error Middleware
-
-```typescript
-import { ErrorRequestHandler } from 'express';
-
-// Express requires all 4 parameters to be declared
-export const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
-  // TypeScript ensures proper typing
-  if (err instanceof AppError) {
-    res.status(err.statusCode).json({
-      code: err.code,
-      message: err.message,
-    });
-    return;
-  }
-
-  req.log?.error({ err }, 'Unhandled error');
-  res.status(500).json({
-    code: 'INTERNAL_ERROR',
-    message: 'An unexpected error occurred',
-  });
-};
-```
-
-## Environment Configuration with Type Safety
-
-```typescript
-import { z } from 'zod';
-
-const envSchema = z.object({
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-  PORT: z.coerce.number().default(3000),
-  DATABASE_URL: z.string().url(),
-  JWT_SECRET: z.string().min(32),
-  CORS_ORIGINS: z.string().transform((s) => s.split(',')),
-  RATE_LIMIT_MAX: z.coerce.number().default(100),
-  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
-});
-
-export type Config = z.infer<typeof envSchema>;
-
-export function loadConfig(): Config {
-  const result = envSchema.safeParse(process.env);
-  if (!result.success) {
-    console.error('Invalid environment configuration:');
-    console.error(result.error.flatten().fieldErrors);
-    process.exit(1);
-  }
-  return result.data;
-}
-```
-
-## Common TypeScript Patterns
-
-| Pattern | When to Use |
-| --- | --- |
-| `RequestHandler<Params, ResBody, ReqBody, Query>` | Typed route handlers |
-| `ErrorRequestHandler` | Error middleware (4 params) |
-| `declare global { namespace Express {} }` | Declaration merging for req extensions |
-| `z.infer<typeof schema>` | Derive types from Zod schemas |
-| Factory functions for routers | Dependency injection in routes |
-| App/server separation | Testability with supertest |

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/fastapi/evals/assertions.md

@@ -1,21 +0,0 @@
-# FastAPI Skill Assertions
-
-## Eval 1: Authenticated API with Pydantic Validation
-
-| # | Assertion | Type | Expected Value | Rationale |
-|---|-----------|------|----------------|-----------|
-| 1 | Uses OAuth2PasswordBearer | contains | `OAuth2PasswordBearer` | Token-based authentication must use OAuth2PasswordBearer to integrate with FastAPI's security scheme and auto-generate the OpenAPI securitySchemes section. |
-| 2 | Defines Pydantic BaseModel | contains | `BaseModel` | All request and response types must inherit from Pydantic BaseModel for automatic validation, serialization, and OpenAPI schema generation. |
-| 3 | Uses Depends() | contains | `Depends(` | Shared logic (auth, DB sessions, pagination) must use Depends() for dependency injection, enabling per-request caching and test overrides. |
-| 4 | Declares response_model | contains | `response_model` | Path operations must specify response_model to enforce Pydantic serialization, filter internal fields, and keep the OpenAPI contract accurate. |
-| 5 | Raises HTTPException | contains | `HTTPException` | Error responses must use HTTPException with specific status codes for consistent JSON error formatting that matches consumer expectations. |
-
-## Eval 2: Async Background Tasks
-
-| # | Assertion | Type | Expected Value | Rationale |
-|---|-----------|------|----------------|-----------|
-| 1 | Uses AsyncSession | contains | `AsyncSession` | Async endpoints must use SQLAlchemy 2.0 AsyncSession to avoid blocking the event loop with synchronous database I/O. |
-| 2 | Uses BackgroundTasks | contains | `BackgroundTasks` | Fire-and-forget work must use FastAPI's BackgroundTasks to execute after the response is sent, keeping endpoint latency low. |
-| 3 | Declares async def | contains | `async def` | Endpoint functions performing async I/O must be declared as async def so FastAPI runs them on the event loop instead of a thread pool. |
-| 4 | Overrides dependencies in tests | contains | `dependency_overrides` | Tests must use app.dependency_overrides to replace real database and auth dependencies with test doubles for isolation. |
-| 5 | Uses httpx | contains | `httpx` | Async HTTP calls and async test clients must use httpx for non-blocking I/O and proper ASGI lifecycle testing. |

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/fastapi/evals/evals.json

@@ -1,66 +0,0 @@
-[
-  {
-    "name": "authenticated-api-with-pydantic",
-    "description": "Validate that the skill produces a FastAPI application with JWT authentication, Pydantic v2 models with proper validation, dependency injection for auth, and correct response models.",
-    "prompt": "Create a FastAPI application for a user profile service. Implement JWT authentication using OAuth2PasswordBearer with a dependency that decodes tokens and returns the current user. Define Pydantic v2 models for UserCreate (with email validation and password constraints), UserResponse (excluding password), and UserUpdate. Create endpoints for registration, login (returns JWT), get current profile, and update profile. Use response_model on all endpoints and proper HTTPException for errors.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "OAuth2PasswordBearer",
-        "description": "Must use OAuth2PasswordBearer for token-based authentication that integrates with the OpenAPI security scheme."
-      },
-      {
-        "type": "contains",
-        "value": "BaseModel",
-        "description": "Must define Pydantic BaseModel subclasses for request validation and response serialization."
-      },
-      {
-        "type": "contains",
-        "value": "Depends(",
-        "description": "Must use Depends() for dependency injection of authentication, database sessions, and shared logic."
-      },
-      {
-        "type": "contains",
-        "value": "response_model",
-        "description": "Must declare response_model on path operations to enforce Pydantic serialization and prevent internal field leakage."
-      },
-      {
-        "type": "contains",
-        "value": "HTTPException",
-        "description": "Must raise HTTPException with specific status codes for authentication failures, not-found, and validation errors."
-      }
-    ]
-  },
-  {
-    "name": "async-background-tasks",
-    "description": "Validate that the skill produces correct async endpoint patterns with SQLAlchemy async sessions, background tasks, and proper dependency lifecycle management.",
-    "prompt": "Build a FastAPI notification service with async endpoints. Use SQLAlchemy 2.0 AsyncSession for database access with a yield dependency that manages the session lifecycle. Create an endpoint that accepts a notification payload, stores it in the database, and uses BackgroundTasks to send the notification via an async HTTP call with httpx. Include the async database session dependency, the Pydantic models, and an async test using httpx.AsyncClient with dependency overrides for the database session.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "AsyncSession",
-        "description": "Must use SQLAlchemy 2.0 AsyncSession for non-blocking database access in async endpoints."
-      },
-      {
-        "type": "contains",
-        "value": "BackgroundTasks",
-        "description": "Must use FastAPI BackgroundTasks for fire-and-forget work that runs after the response is sent."
-      },
-      {
-        "type": "contains",
-        "value": "async def",
-        "description": "Must declare endpoint functions as async def when performing async I/O operations."
-      },
-      {
-        "type": "contains",
-        "value": "dependency_overrides",
-        "description": "Must use app.dependency_overrides in tests to replace real dependencies with test doubles."
-      },
-      {
-        "type": "contains",
-        "value": "httpx",
-        "description": "Must use httpx (AsyncClient or ASGITransport) for async HTTP calls and async test client."
-      }
-    ]
-  }
-]

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/frontend-design/evals/assertions.md

@@ -1,49 +0,0 @@
-# Frontend Design Eval Assertions
-
-## Eval 1: Design System Component (Button)
-
-This eval tests the core design system workflow: building a reusable component with proper token usage, accessibility, state management, and composable API.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `aria-` — ARIA attribute usage | Buttons must communicate state (disabled, busy, expanded) to assistive technologies. Visual indicators alone exclude screen reader users. |
-| 2 | contains | `--` — CSS custom property tokens | Hardcoded values create maintenance debt and break theme switching. Tokens enforce system-wide consistency from a single source. |
-| 3 | contains | `disabled` — Disabled state handling | A disabled button must prevent interaction, remove from tab order or mark as aria-disabled, and be visually distinct. Missing any of these creates confusion. |
-| 4 | contains | `loading` — Loading state support | Users need feedback during async operations. A loading button must show a spinner, suppress clicks, and announce the busy state to screen readers. |
-| 5 | contains | `variant` — Variant prop for visual styles | A single component must serve multiple semantic contexts (primary action, destructive action, secondary option) through a typed prop rather than ad-hoc class overrides. |
-
-### What a passing response looks like
-
-- A `Button` component with TypeScript props interface defining `variant`, `size`, `loading`, `disabled`, `icon`, and `children`.
-- CSS custom properties (`--button-bg`, `--button-color`, `--button-radius`) mapped to variant-specific values.
-- Disabled state: `aria-disabled="true"`, visual opacity change, pointer-events removed.
-- Loading state: spinner element, `aria-busy="true"`, click handler suppressed.
-- Focus styles: visible outline using `:focus-visible` that is not removed globally.
-- At least primary, secondary, ghost, and danger variant styles with distinct visual treatment.
-
----
-
-## Eval 2: Accessible Form Pattern
-
-This eval tests accessible form construction: label associations, validation feedback, keyboard flow, error handling, and responsive layout.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `htmlFor` — Label-input association | Without programmatic label association, screen readers cannot announce what a field is for. This is the most common accessibility failure in forms. |
-| 2 | contains | `aria-describedby` — Error message linking | Error messages must be announced when their field receives focus. Without aria-describedby, screen reader users have no way to discover field-level errors. |
-| 3 | contains | `role` — ARIA roles for dynamic content | Dynamic feedback (error summaries, strength indicators) must use roles like alert or status to trigger screen reader announcements without focus changes. |
-| 4 | contains | `required` — Required field indication | Required fields must be marked with the required attribute or aria-required so that the requirement is communicated programmatically, not just visually with an asterisk. |
-| 5 | contains | `onSubmit` — Form submission handling | Proper form handling prevents default submission, validates all fields, and moves focus to the first error so that users do not have to hunt for what went wrong. |
-
-### What a passing response looks like
-
-- All `<input>` elements have associated `<label>` elements with matching `htmlFor`/`id` pairs.
-- Error messages wrapped in elements with `id` values referenced by `aria-describedby` on the input.
-- Password strength indicator using `role="status"` or `role="progressbar"` with `aria-valuenow`.
-- Required fields marked with `required` attribute and visual indicator.
-- Form `onSubmit` handler that validates, prevents default, and focuses the first invalid field.
-- Responsive layout using CSS Grid or Flexbox that collapses from two columns to one on narrow viewports.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/frontend-design/evals/evals.json

@@ -1,68 +0,0 @@
-{
-  "evals": [
-    {
-      "name": "design-system-component-button",
-      "description": "Validate that the skill produces a design system Button component with proper token usage, accessibility, interaction states, and composable API following component architecture best practices.",
-      "input": "Create a production-grade Button component for a design system. It must support variants (primary, secondary, ghost, danger), sizes (sm, md, lg), loading state with spinner, disabled state, icon support (leading and trailing), and full accessibility. Use design tokens for all visual values. Provide the component in React with TypeScript.",
-      "assertions": [
-        {
-          "type": "contains",
-          "value": "aria-",
-          "description": "The Button must include ARIA attributes (aria-disabled, aria-busy, aria-label) to communicate state to assistive technologies beyond visual indicators."
-        },
-        {
-          "type": "contains",
-          "value": "--",
-          "description": "Visual values must reference CSS custom properties (design tokens) rather than hardcoded hex colors, pixel values, or magic numbers."
-        },
-        {
-          "type": "contains",
-          "value": "disabled",
-          "description": "The component must handle the disabled state both visually and functionally, preventing click events and conveying the state to screen readers."
-        },
-        {
-          "type": "contains",
-          "value": "loading",
-          "description": "The component must support a loading state that shows a spinner, disables interaction, and communicates the busy state via aria-busy."
-        },
-        {
-          "type": "contains",
-          "value": "variant",
-          "description": "The component must accept a variant prop to switch between visual styles (primary, secondary, ghost, danger) so that usage context drives appearance."
-        }
-      ]
-    },
-    {
-      "name": "accessible-form-pattern",
-      "description": "Validate that the skill produces an accessible form with proper label associations, validation feedback, keyboard navigation, error handling, and responsive layout.",
-      "input": "Create a registration form with fields for full name, email, password, and password confirmation. Include inline validation with accessible error messages, a password strength indicator, proper label associations, keyboard navigation support, and a responsive two-column layout that collapses to single column on mobile. Use semantic HTML and ARIA where needed. Implement in React with TypeScript.",
-      "assertions": [
-        {
-          "type": "contains",
-          "value": "htmlFor",
-          "description": "Every form field must have a label element with htmlFor (or for) attribute matching the input id to create a programmatic association for screen readers."
-        },
-        {
-          "type": "contains",
-          "value": "aria-describedby",
-          "description": "Error messages must be linked to their input fields via aria-describedby so that screen readers announce the error when the field receives focus."
-        },
-        {
-          "type": "contains",
-          "value": "role",
-          "description": "The form must use ARIA roles (alert, status, or progressbar) for dynamic content like error summaries or the password strength indicator."
-        },
-        {
-          "type": "contains",
-          "value": "required",
-          "description": "Required fields must be marked with the required attribute or aria-required so that the requirement is communicated to both visual users and assistive technologies."
-        },
-        {
-          "type": "contains",
-          "value": "onSubmit",
-          "description": "The form must handle submission with proper validation, preventing default form behavior and managing focus to the first error field on validation failure."
-        }
-      ]
-    }
-  ]
-}

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/gin-golang/SKILL.md

@@ -1,81 +0,0 @@
----
-name: gin-golang
-description: "Use when building Gin-based Go services, including routing, middleware chains, request validation, structured errors, context propagation, and deployment hardening."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-# Gin Web Framework
-
-## Purpose
-
-Production-grade guidance for building robust HTTP APIs using the Gin web framework for Go. Gin provides a martini-like API with radix-tree routing, middleware composition, and built-in request binding and validation, all with performance close to net/http.
-
-## When to Use
-
-- Building REST APIs, CRUD services, or BFF layers with Gin.
-- Designing middleware chains for authentication, logging, rate limiting, and recovery.
-- Validating request payloads using Gin's binding and `validator/v10` tags.
-- Structuring large Gin applications with router groups and modular handler packages.
-- Writing integration tests for Gin handlers and middleware.
-- Deploying Gin services behind reverse proxies with health checks and graceful shutdown.
-
-## Instructions
-
-1. **Set Gin mode based on environment** -- call `gin.SetMode(gin.ReleaseMode)` in production and `gin.SetMode(gin.DebugMode)` during development. Debug mode logs every request to stdout and enables route debugging, which leaks internal structure and adds overhead in production.
-
-2. **Create the engine with `gin.New()` and add middleware explicitly** -- prefer `gin.New()` over `gin.Default()` so you control exactly which middleware runs. Add `gin.Recovery()` first, then structured logging, then auth. `gin.Default()` silently adds Logger and Recovery, which may not match your production logging format.
-
-3. **Organize routes with `router.Group()` and apply group-level middleware** -- group related endpoints under versioned prefixes (e.g., `/api/v1`) and attach authentication or rate-limiting middleware at the group level. This avoids repeating middleware declarations per route and makes authorization boundaries explicit.
-
-4. **Validate requests with struct binding tags** -- define request structs with `binding:"required"`, `binding:"min=1,max=100"`, and custom validators. Use `c.ShouldBindJSON()` (not `c.BindJSON()`) to avoid automatic 400 responses that bypass your error format. Handle the returned error to produce consistent structured error responses.
-
-5. **Use `c.ShouldBind*` methods consistently, never mix `Bind` and `ShouldBind`** -- `Bind*` methods write a 400 response and abort on failure, removing your control over error formatting. `ShouldBind*` returns the error for you to handle. Pick one convention project-wide to prevent inconsistent error surfaces.
-
-6. **Return structured JSON error responses from a central error handler** -- write a `handleError(c *gin.Context, err error)` helper or use `gin.CustomRecoveryWithWriter` to map errors to a consistent `{"code": ..., "message": ..., "details": ...}` envelope. Register sentinel errors and typed errors for known failure conditions so the handler can assign the right HTTP status.
-
-7. **Pass request-scoped values through `c.Set()` and `c.Get()` or `c.MustGet()`** -- store the authenticated user, request ID, or trace span in the Gin context within middleware. Retrieve with type-safe wrapper functions. Do not use global variables because Gin recycles context objects in its pool.
-
-8. **Write middleware as `gin.HandlerFunc` with explicit `c.Next()` and `c.Abort()`** -- call `c.Next()` to continue the chain and `c.Abort()` to stop it. For timing middleware, record the start time before `c.Next()` and compute duration after. For auth middleware, abort with a 401 JSON response before `c.Next()` if the token is invalid.
-
-9. **Handle panics with `gin.Recovery()` or a custom recovery middleware** -- recovery middleware catches panics and converts them to 500 responses. Place it as the outermost middleware. For custom recovery, use `gin.CustomRecoveryWithWriter(writer, recoveryFunc)` to log stack traces to your structured logger instead of stderr.
-
-10. **Implement graceful shutdown with `http.Server` wrapping the Gin engine** -- create an `http.Server{Handler: router}`, start it in a goroutine, listen for OS signals, then call `server.Shutdown(ctx)` with a deadline context. Do not call `router.Run()` directly in production because it provides no shutdown hook.
-
-11. **Test handlers with `httptest.NewRecorder` and `gin.CreateTestContext`** -- for unit tests, use `gin.CreateTestContext(recorder)` to get an isolated context with full middleware control. For integration tests, register routes on a test engine and use `httptest.NewRequest` with `router.ServeHTTP`. Assert on response status, headers, and decoded JSON body.
-
-12. **Trust proxy headers only from known sources** -- call `router.SetTrustedProxies([]string{"10.0.0.0/8"})` or `router.SetTrustedProxies(nil)` to disable. The default trusts all proxies, which lets attackers spoof `X-Forwarded-For` and bypass IP-based rate limiting or geo-restrictions.
-
-13. **Register custom validators for domain-specific rules** -- get the validator engine with `binding.Validator.Engine().(*validator.Validate)` and call `RegisterValidation("slug", slugValidator)`. Use custom validators for business rules like UUID format, currency codes, or enum membership instead of validating in handler logic.
-
-14. **Configure timeouts and limits on the underlying `http.Server`** -- set `ReadTimeout`, `WriteTimeout`, `IdleTimeout`, and `MaxHeaderBytes`. Gin does not set these by default, and missing timeouts allow slowloris attacks and resource exhaustion under sustained load.
-
-15. **Use `c.Stream()` for server-sent events and large responses** -- for SSE or chunked responses, use `c.Stream(func(w io.Writer) bool { ... })` to write data incrementally. This avoids buffering the entire response in memory and supports real-time data push patterns.
-
-16. **Keep Gin at the boundary -- handlers parse, delegate, format** -- handler functions should call `ShouldBind`, invoke a service-layer function, and call `c.JSON()`. Business logic must not import `gin`. This separation enables unit testing without HTTP context and makes the service layer reusable across transport mechanisms.
-
-## Output Format
-
-Produces Go source files with Gin handler signatures, grouped route registration, binding structs with validation tags, middleware functions, and table-driven handler tests. Includes `go.mod` dependencies and deployment configuration where applicable.
-
-## References
-
-Load only what the current step needs.
-
-| File | Load when |
-| --- | --- |
-| `references/routing.md` | Route registration, groups, parameter binding, or path patterns need detail. |
-| `references/middleware.md` | Middleware authoring, ordering, built-in middleware, or custom recovery is in scope. |
-| `references/validation.md` | Request binding, validation tags, custom validators, or error formatting is needed. |
-| `references/testing.md` | Handler testing, integration tests, or test context setup is needed. |
-| `references/deployment.md` | Graceful shutdown, reverse proxy config, Docker builds, or health checks are in scope. |
-
-## Copilot Platform Notes
-
-- Skill files are stored under `.github/prompts/` (prompt files) and `.github/instructions/` (instruction files).
-- Copilot does not support subagent spawning — all skill guidance executes within the current conversation context.
-- User arguments are provided as natural language input in the prompt, not through a `$ARGUMENTS` variable.
-- Frontmatter keys `context`, `agent`, and `allowed-tools` are not supported; guidance is advisory only.
-- Reference files can be included via `#file:references/<name>.md` syntax in Copilot Chat.