@xonovex/skills 0.1.0

package/skills/git-guidelines/reference/worktree-create.md

@@ -0,0 +1,42 @@
+# worktree-create: Create Feature Worktree
+
+**Guideline:** Create worktree with feature branch for isolated development without affecting current worktree.
+
+**Rationale:** Enables parallel feature development in separate directories, avoiding context switching and stash complications that plague single-worktree workflows.
+
+**Example:**
+
+```bash
+# From services directory with master branch
+cd /home/user/project/services
+
+# Create worktree for auth-flow feature
+# Creates: ../services-feature-auth-flow directory
+# Creates: services/feature/auth-flow branch (off master)
+git worktree add ../services-feature-auth-flow -b services/feature/auth-flow master
+
+# Config stores the merge target
+git config branch.services/feature/auth-flow.mergeBackTo master
+
+# Navigate to new worktree and start development
+cd ../services-feature-auth-flow
+npm install
+npm run typecheck
+
+# Commit work independently without affecting main worktree
+git add services/auth/login.ts
+git commit -m "feat: Add LoginFlow component"
+
+# Later, merge back to source
+cd ../services
+git merge services/feature/auth-flow --no-ff
+git push origin master
+```
+
+**Techniques:**
+- Detect worktree name from directory basename
+- Get source branch from arg or `git branch --show-current`
+- Sanitize feature name to kebab-case format
+- Create directory `../<worktree>-feature-<name>` and branch `<worktree>/feature/<name>`
+- Create worktree: `git worktree add <dir> -b <branch> <source-branch>`
+- Store merge target in git config: `git config branch.<branch>.mergeBackTo <source-branch>`

package/skills/git-guidelines/reference/worktree-merge.md

@@ -0,0 +1,45 @@
+# worktree-merge: Merge Feature Worktree Back to Source
+
+**Guideline:** Merge feature worktree branch back to source branch after validation passes to complete the feature development cycle.
+
+**Rationale:** Completing the merge integrates changes to main codebase and enables cleanup of the temporary feature worktree while maintaining code quality.
+
+**Example:**
+
+```bash
+# In feature worktree after validation passes
+cd ../services-feature-auth-flow
+npm run typecheck && npm run lint && npm run build && npm run test
+# All pass ✓
+
+# Merge to source worktree
+MERGE_SOURCE=$(git config branch.services/feature/auth-flow.mergeBackTo)
+# MERGE_SOURCE = master
+
+cd ../services
+git pull origin master
+git merge services/feature/auth-flow --no-ff
+# Merge commit created
+
+# Validate merged result
+npm run typecheck && npm run lint
+# All pass ✓
+
+# Push to remote
+git push origin master
+
+# Optional: Clean up feature worktree
+cd ../services
+git worktree remove ../services-feature-auth-flow
+git branch -d services/feature/auth-flow
+```
+
+**Techniques:**
+- Verify validation passed
+- Read source: `git config branch.<branch>.mergeBackTo`
+- Navigate to source worktree directory
+- Update source: `git pull origin <source-branch>`
+- Merge: `git merge <feature-branch> --no-ff`
+- Handle conflicts (auto-resolve simple, manual review complex)
+- Validate merged result: `npm run typecheck && npm run lint`
+- Push: `git push origin <source-branch>`

package/skills/git-guidelines/reference/worktree-validate.md

@@ -0,0 +1,44 @@
+# worktree-validate: Pre-Merge Validation Checkpoint
+
+**Guideline:** Validate feature worktree before merge by running typecheck, lint, build, and tests to ensure stability.
+
+**Rationale:** Running validation before merge catches issues early, ensures quality standards are met, and verifies the feature aligns with plan criteria when configured.
+
+**Example:**
+
+```bash
+# In feature worktree
+cd ../services-feature-auth-flow
+
+# Run validation checks
+npm run typecheck
+# ✓ PASS (0 errors)
+
+npm run lint
+# ✓ PASS (0 errors)
+
+npm run build
+# ✓ PASS (bundle 245 KB)
+
+npm run test
+# ✓ PASS (42 tests, 0 failures, 95% coverage)
+
+# Check plan criteria if configured
+git config branch.services/feature/auth-flow.plan
+# "Implement email+password flow with TOTP and backup codes"
+
+# Verify plan success criteria met:
+# ✓ Email validation (part of LoginFlow)
+# ✓ TOTP verification (part of LoginFlow)
+# ✓ Backup codes support (in VerificationFlow)
+
+# Overall status: READY TO MERGE
+# All validation passed, all plan criteria met
+```
+
+**Techniques:**
+- Verify in feature worktree
+- Check commits complete
+- Run validation in sequence: `npm run typecheck`, `npm run lint`, `npm run build`, `npm run test`
+- Check plan criteria if associated
+- Report results

package/skills/hono-guidelines/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: hono-guidelines
+description: >-
+  Trigger on `*.ts` files with Hono imports or `@hono/` packages. Use when building Hono 4.0+ API servers. Apply for validation, middleware, error handling, WebSockets. Keywords: Hono, middleware, Zod validator, error handling, WebSocket.
+---
+
+# Hono Coding Guidelines
+
+## Requirements
+
+- Hono ≥ 4.0, @hono/node-server, @hono/zod-validator, TypeScript ≥ 5.8
+
+## Essentials
+
+- **Factory functions** - Use for testability and domain organization, see [reference/application-structure.md](reference/application-structure.md)
+- **Type-safe validation** - Cast `c.req.valid` properly, handle errors with Zod, see [reference/validation-type-safety.md](reference/validation-type-safety.md)
+- **Middleware configuration** - Use factories for CORS, composition with `some()`/`every()`/`except()`, see [reference/middleware-patterns.md](reference/middleware-patterns.md), [reference/middleware-combine.md](reference/middleware-combine.md)
+- **WebSocket helpers** - Keep object references to maintain `this` binding, see [reference/websocket-support.md](reference/websocket-support.md)
+- **Error responses** - Use RFC 7807 Problem Details format, see [reference/error-handling.md](reference/error-handling.md)
+- **Security middleware** - Apply `secureHeaders()` for security headers, see [reference/security-middleware.md](reference/security-middleware.md)
+- **Cookie handling** - Set secure options explicitly, use signed cookies, see [reference/cookie-handling.md](reference/cookie-handling.md)
+- **Platform portability** - Use `env(c)` for environment, `getRuntimeKey()` for detection, see [reference/platform-runtime.md](reference/platform-runtime.md)
+
+## Example
+
+```typescript
+import {Hono} from "hono";
+import {secureHeaders} from "hono/secure-headers";
+
+export function createApp() {
+  const app = new Hono();
+  app.use("*", secureHeaders());
+  app.route("/api/v1", v1Router);
+  return app;
+}
+```
+
+## Progressive disclosure
+
+- Read [reference/application-structure.md](reference/application-structure.md) - When organizing a new Hono application
+- Read [reference/validation-type-safety.md](reference/validation-type-safety.md) - When losing type safety after validation
+- Read [reference/middleware-patterns.md](reference/middleware-patterns.md) - When creating reusable middleware or configuring CORS
+- Read [reference/websocket-support.md](reference/websocket-support.md) - When implementing WebSocket endpoints
+- Read [reference/error-handling.md](reference/error-handling.md) - When standardizing error responses across routes
+- Read [reference/security-middleware.md](reference/security-middleware.md) - When configuring auth, CSRF, or security headers
+- Read [reference/cookie-handling.md](reference/cookie-handling.md) - When managing sessions or sensitive cookies
+- Read [reference/context-storage.md](reference/context-storage.md) - When accessing Context outside handlers
+- Read [reference/middleware-combine.md](reference/middleware-combine.md) - When composing complex middleware logic
+- Read [reference/platform-runtime.md](reference/platform-runtime.md) - When deploying across multiple runtimes

package/skills/hono-guidelines/reference/application-structure.md

@@ -0,0 +1,53 @@
+# application-structure: Application Factory and Router Organization
+
+**Guideline:** Use factory functions to create Hono applications instead of exporting instances, and organize routes into separate router files by domain.
+
+**Rationale:** Factory functions enable testability by creating fresh instances per test, support dependency injection, and improve isolation. Domain-based router organization provides clear separation of concerns and reduces merge conflicts in team environments.
+
+**Example:**
+
+```typescript
+// src/app.ts - Main application factory
+import {Hono} from "hono";
+import {cors} from "hono/cors";
+import {logger} from "hono/logger";
+import {v1Router} from "./routes/v1/index.js";
+import {v2Router} from "./routes/v2/index.js";
+
+export function createApp() {
+  const app = new Hono();
+
+  // Global middleware
+  app.use("*", logger());
+  app.use("*", cors());
+
+  // Mount routers by version
+  app.route("/api/v1", v1Router);
+  app.route("/api/v2", v2Router);
+
+  return app;
+}
+
+// src/routes/v1/users.ts - Domain router
+import {Hono} from "hono";
+import {zValidator} from "@hono/zod-validator";
+import * as controller from "../../controllers/users.controller.js";
+import {CreateUserSchema} from "../../schemas/users.js";
+
+export const usersRouter = new Hono();
+
+usersRouter.post(
+  "/",
+  zValidator("json", CreateUserSchema),
+  controller.createUser,
+);
+```
+
+**Techniques:**
+- Create `createApp()` factory function instead of exporting instances
+- Configure global middleware inside the factory
+- Mount domain routers using `app.route()`
+- Organize routers in separate files by domain (users, items, etc.)
+- Import controllers from dedicated controller files
+- Keep route definitions focused on routing logic only
+- Export factory functions for testability

package/skills/hono-guidelines/reference/context-storage.md

@@ -0,0 +1,46 @@
+# context-storage: Access Context Globally with AsyncLocalStorage
+
+**Guideline:** Use `contextStorage()` middleware with `getContext()` to access Hono Context outside route handlers, enabling cleaner service layer code without parameter drilling.
+
+**Rationale:** AsyncLocalStorage provides global access to the current request context without parameter drilling through the call stack, enabling clean separation between routing and business logic while automatically cleaning up context after requests.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {contextStorage, getContext} from "hono/context-storage";
+
+const app = new Hono();
+
+// Enable context storage early
+app.use(contextStorage());
+
+// Set request metadata
+app.use("*", async (c, next) => {
+  c.set("requestId", crypto.randomUUID());
+  c.set("tenantId", c.req.header("X-Tenant-ID"));
+  await next();
+});
+
+app.get("/items", (c) => {
+  const items = itemsService.list(); // No context passed
+  return c.json(items);
+});
+
+// In service layer (separate file)
+export function list() {
+  const c = getContext();
+  const tenantId = c.get("tenantId");
+  const requestId = c.get("requestId");
+
+  logger.info(`[${requestId}] Listing items for tenant ${tenantId}`);
+  return db.items.findMany({where: {tenantId}});
+}
+```
+
+**Techniques:**
+- Import `contextStorage` and `getContext` from `hono/context-storage`
+- Apply `contextStorage()` middleware early in middleware chain
+- Call `getContext()` anywhere during request handling to access context
+- For Cloudflare Workers enable `nodejs_compat` flag
+- Use sparingly as explicit parameters are more testable

package/skills/hono-guidelines/reference/cookie-handling.md

@@ -0,0 +1,63 @@
+# cookie-handling: Secure Cookie Configuration and Signed Cookies
+
+**Guideline:** Set secure cookie options explicitly, use signed cookies for sensitive data, and follow browser-enforced prefix requirements for additional security.
+
+**Rationale:** Cookies require careful configuration to ensure HTTPS-only transmission, prevent JavaScript access, defend against CSRF, and verify integrity. Cookie prefixes enforce additional security guarantees, while signed cookies prevent tampering and provide strong integrity verification for sensitive client-side state.
+
+**Example:**
+
+```typescript
+import {
+  getCookie,
+  getSignedCookie,
+  setCookie,
+  setSignedCookie,
+} from "hono/cookie";
+
+// Standard secure cookie
+app.post("/login", (c) => {
+  setCookie(c, "session", sessionId, {
+    secure: true,
+    httpOnly: true,
+    sameSite: "Strict",
+    maxAge: 86400, // 1 day
+    path: "/",
+  });
+  return c.json({success: true});
+});
+
+// Signed cookie for integrity (async)
+app.post("/preferences", async (c) => {
+  await setSignedCookie(c, "prefs", JSON.stringify(prefs), "secret-key", {
+    secure: true,
+    httpOnly: true,
+    sameSite: "Lax",
+  });
+  return c.json({saved: true});
+});
+
+// Verify signed cookie
+app.get("/preferences", async (c) => {
+  const prefs = await getSignedCookie(c, "secret-key", "prefs");
+  if (prefs === false) {
+    return c.json({error: "Invalid signature"}, 400);
+  }
+  return c.json(JSON.parse(prefs ?? "{}"));
+});
+
+// Host-prefixed cookie (strictest)
+setCookie(c, "__Host-session", token, {
+  secure: true,
+  path: "/",
+  // domain must NOT be set for __Host- prefix
+});
+```
+
+**Techniques:**
+- Import cookie helpers from `hono/cookie` (setCookie, getCookie, setSignedCookie, getSignedCookie)
+- Always set `secure: true` and `httpOnly: true` for sensitive cookies
+- Use `sameSite: 'Strict'` for maximum CSRF protection or `'Lax'` for better compatibility
+- Use `setSignedCookie` (async) for cookies requiring integrity verification
+- Verify signed cookies with `getSignedCookie` and check for false value on tampering
+- Use `__Host-` prefix for strictest cookie restrictions (requires `secure: true` and `path: '/'`)
+- Keep `maxAge` under 400 days to respect browser limits

package/skills/hono-guidelines/reference/error-handling.md

@@ -0,0 +1,69 @@
+# error-handling: RFC 7807 Problem Details for Consistent Error Responses
+
+**Guideline:** Use RFC 7807 Problem Details format for all error responses to provide consistent, structured, machine-readable error information across your API.
+
+**Rationale:** RFC 7807 provides a standard structure recognized across HTTP APIs, enabling clients to parse errors consistently with machine-readable field-level validation details and request context. Built-in extensibility and separation between human and machine-readable fields improves debugging and error handling.
+
+**Example:**
+
+```typescript
+import type {Context} from "hono";
+import type {z} from "zod";
+
+export interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  issues?: {
+    path: string[];
+    message: string;
+    code?: string;
+  }[];
+}
+
+export function badRequest(c: Context, error: z.ZodError): Response {
+  const problem: ProblemDetails = {
+    type: "about:blank#bad-request",
+    title: "Bad Request",
+    status: 400,
+    detail: "Request validation failed",
+    instance: c.req.path,
+    issues: error.issues.map((issue) => ({
+      path: issue.path.map(String),
+      message: issue.message,
+      code: issue.code,
+    })),
+  };
+
+  return new Response(JSON.stringify(problem), {
+    status: 400,
+    headers: {"Content-Type": "application/json"},
+  });
+}
+
+export function notFound(c: Context, detail: string): Response {
+  const problem: ProblemDetails = {
+    type: "about:blank#not-found",
+    title: "Not Found",
+    status: 404,
+    detail,
+    instance: c.req.path,
+  };
+
+  return new Response(JSON.stringify(problem), {
+    status: 404,
+    headers: {"Content-Type": "application/json"},
+  });
+}
+```
+
+**Techniques:**
+- Define `ProblemDetails` TypeScript interface matching RFC 7807 spec
+- Include required fields: type, title, status
+- Include optional fields: detail, instance, custom extensions
+- For validation errors add `issues` array with field-level details
+- Create helper functions for common error types (badRequest, notFound, etc.)
+- Return proper HTTP status codes matching the status field
+- Set `Content-Type: application/json` header

package/skills/hono-guidelines/reference/middleware-combine.md

@@ -0,0 +1,47 @@
+# middleware-combine: Composing Middleware with some, every, except
+
+**Guideline:** Use the `combine` module (`some`, `every`, `except`) to compose complex middleware logic for conditional execution and access control.
+
+**Rationale:** The combine module provides declarative composition of complex requirements: `some()` implements OR logic for alternative auth methods, `every()` implements AND logic for layered checks, and `except()` skips middleware for specific paths, enabling cleaner code than nested conditionals.
+
+**Example:**
+
+```typescript
+import {basicAuth} from "hono/basic-auth";
+import {bearerAuth} from "hono/bearer-auth";
+import {every, except, some} from "hono/combine";
+
+// Accept either basic auth OR bearer token
+app.use(
+  "/api/*",
+  some(
+    basicAuth({verifyUser: verifyBasicAuth}),
+    bearerAuth({verifyToken: verifyBearerToken}),
+  ),
+);
+
+// Must be authenticated AND have admin role
+app.use(
+  "/admin/*",
+  every(bearerAuth({verifyToken: verifyToken}), async (c, next) => {
+    const user = c.get("user");
+    if (user.role !== "admin") {
+      return c.json({error: "Forbidden"}, 403);
+    }
+    await next();
+  }),
+);
+
+// Apply rate limiting to all routes EXCEPT health checks
+app.use("*", except("/health", rateLimiter({max: 100, window: 60})));
+
+// Multiple path exclusions
+app.use("*", except(["/health", "/metrics", "/ready"], authMiddleware()));
+```
+
+**Techniques:**
+- Import `some`, `every`, `except` from `hono/combine`
+- Use `some()` for alternative auth methods (OAuth OR API key)
+- Use `every()` for layered requirements (authenticated AND has role)
+- Use `except()` for path-based middleware exclusions
+- Combine module handlers with other Hono middleware seamlessly

package/skills/hono-guidelines/reference/middleware-patterns.md

@@ -0,0 +1,58 @@
+# middleware-patterns: CORS Configuration and Custom Middleware
+
+**Guideline:** Configure CORS differently for development and production, and use middleware factory functions to ensure proper `this` binding and parameterization.
+
+**Rationale:** Environment-specific CORS balances development convenience with production security. Middleware factories ensure correct context binding in async operations, enable parameterization, and provide consistent patterns across applications through proper closure over configuration values.
+
+**Example:**
+
+```typescript
+import type {Context, Next} from "hono";
+import {cors} from "hono/cors";
+
+// Environment-specific CORS
+const isDevelopment = process.env.NODE_ENV === "development";
+
+if (isDevelopment) {
+  // Development: Permissive
+  app.use(
+    "*",
+    cors({
+      origin: "*",
+      allowMethods: ["GET", "POST", "PUT", "DELETE"],
+      maxAge: 86_400, // 24 hours
+    }),
+  );
+} else {
+  // Production: Restrictive
+  app.use(
+    "*",
+    cors({
+      origin: ["https://app.example.com"],
+      allowMethods: ["GET", "POST", "PUT", "DELETE"],
+      credentials: true,
+      maxAge: 600, // 10 minutes
+    }),
+  );
+}
+
+// Custom middleware factory with proper binding
+function requestId() {
+  return async (c: Context, next: Next) => {
+    const id = crypto.randomUUID();
+    c.set("requestId", id);
+    c.header("X-Request-ID", id);
+    await next();
+  };
+}
+
+app.use("*", requestId());
+```
+
+**Techniques:**
+- Import CORS from `hono/cors` and configure based on environment
+- For development use `origin: "*"` for permissive access
+- For production specify allowed origins explicitly
+- Create middleware factory function that returns `async (c, next) => {...}`
+- Call factory function when registering: `app.use("*", requestId())`
+- Never destructure methods from helpers that rely on `this` binding

package/skills/hono-guidelines/reference/platform-runtime.md

@@ -0,0 +1,41 @@
+# platform-runtime: Platform-Specific Runtime Detection
+
+**Guideline:** Use `env()` for unified environment variables and `getRuntimeKey()` for platform-specific code paths.
+
+**Rationale:** Hono runs on different runtimes with different APIs and behaviors. Unified helpers enable portable code across all platforms.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {env, getRuntimeKey} from "hono/adapter";
+import {getConnInfo} from "hono/cloudflare-workers";
+
+const app = new Hono();
+
+// Unified environment access
+app.get("/config", (c) => {
+  const {DATABASE_URL} = env<{DATABASE_URL: string}>(c);
+  return c.json({configured: !!DATABASE_URL});
+});
+
+// Platform-specific logic
+app.use("*", async (c, next) => {
+  const runtime = getRuntimeKey();
+  c.header("X-Runtime", runtime === "workerd" ? "cloudflare" : runtime);
+  await next();
+});
+
+// Connection info
+app.get("/ip", (c) => {
+  const info = getConnInfo(c);
+  return c.json({ip: info.remote.address});
+});
+```
+
+**Techniques:**
+- Import `env` and `getRuntimeKey` from `hono/adapter`
+- Use `env(c)` instead of `process.env` or `Deno.env`
+- Check runtime with `getRuntimeKey()` for platform-specific logic
+- Import connection info from platform-specific paths
+- Handle platform differences (Deno cache requires `wait: true`, Node.js needs compression middleware)

package/skills/hono-guidelines/reference/security-middleware.md

@@ -0,0 +1,60 @@
+# security-middleware: Built-in Security Middleware Configuration
+
+**Guideline:** Use Hono's built-in security middleware for authentication, CSRF protection, and security headers, applying `secureHeaders()` first in the middleware chain.
+
+**Rationale:** Hono provides battle-tested security middleware implementations for basic auth, bearer tokens, JWT verification, CSRF protection, and IP restriction with consistent configuration patterns and type safety, eliminating the need for external dependencies.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {basicAuth} from "hono/basic-auth";
+import {bearerAuth} from "hono/bearer-auth";
+import {csrf} from "hono/csrf";
+import {ipRestriction} from "hono/ip-restriction";
+import {secureHeaders} from "hono/secure-headers";
+
+const app = new Hono();
+
+// Apply secure headers first
+app.use("*", secureHeaders());
+
+// CSRF protection for form submissions
+app.use("/forms/*", csrf());
+
+// Bearer auth with custom verification
+app.use(
+  "/api/*",
+  bearerAuth({
+    verifyToken: async (token, c) => {
+      return await tokenService.verify(token);
+    },
+  }),
+);
+
+// Basic auth for admin routes
+app.use(
+  "/admin/*",
+  basicAuth({
+    verifyUser: (username, password, c) => {
+      return username === "admin" && password === process.env.ADMIN_PASSWORD;
+    },
+  }),
+);
+
+// IP restriction for internal routes
+app.use(
+  "/internal/*",
+  ipRestriction({
+    denyList: [],
+    allowList: ["192.168.0.0/16", "10.0.0.0/8"],
+  }),
+);
+```
+
+**Techniques:**
+- Import middleware from `hono/` subpaths (basicAuth, bearerAuth, csrf, secureHeaders, ipRestriction)
+- Apply security headers first in middleware chain to protect all routes
+- Use custom verifiers for dynamic authentication logic
+- Configure CSRF protection for form-based applications
+- Restrict IPs for admin and internal routes using CIDR notation

package/skills/hono-guidelines/reference/validation-type-safety.md

@@ -0,0 +1,43 @@
+# validation-type-safety: Request Validation and Type Safety with Zod
+
+**Guideline:** Cast `c.req.valid` to specify return types and cast validation errors to `z.ZodError` to restore type safety when using Hono's base Context type.
+
+**Rationale:** Hono's Context type without generic validation types returns `any` from `c.req.valid()`, losing type safety. Type assertions restore compile-time type checking without complex nested generics, enabling autocomplete and error detection while keeping signatures simple.
+
+**Example:**
+
+```typescript
+import {zValidator} from "@hono/zod-validator";
+import type {Context} from "hono";
+import type {z} from "zod";
+import {CreateUserSchema, type CreateUser} from "../schemas/users.js";
+
+// Controller with type-safe validation
+export function createUser(c: Context) {
+  // Cast c.req.valid to specify return type
+  const data = (c.req.valid as (target: string) => CreateUser)("json");
+
+  // Now `data` has full type information
+  const user = userService.create(data);
+  return c.json(user, 201);
+}
+
+usersRouter.post(
+  "/",
+  zValidator("json", CreateUserSchema, (result, c) => {
+    if (!result.success) {
+      // Cast to z.ZodError for type-safe error processing
+      return badRequest(c, result.error as z.ZodError);
+    }
+  }),
+  controller.createUser,
+);
+```
+
+**Techniques:**
+- Define Zod schemas for request payloads with TypeScript type exports
+- In controllers using base `Context`, cast `c.req.valid` with target parameter
+- Specify the return type in the cast (e.g., `CreateUser`)
+- In zValidator error handlers, cast `result.error` to `z.ZodError`
+- Use typed validation errors in error response functions
+- Apply same pattern to query params and path params