@kinqs/brainrouter-mcp-server 0.3.4

package/skills/agent/sync-skill/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sync-skill
+description: Synchronizes documentation with the actual codebase. Use when code has changed but docs are outdated, before shipping a feature, or when you notice a mismatch between docs (API, Schema, Design) and reality.
+hints: |
+  - Always identify which documentation file (e.g., API.md, Schema.md, README.md) is the primary target for changes.
+  - Review route validation logic (like Zod or Joi schemas) to accurately document constraints.
+  - Parse ORM models or database migrations to capture relationships and field limits in Schema.md.
+  - Scan CSS variables and tailwind/theme configurations to align Design.md design tokens.
+  - Double check if related auxiliary files (like .env.example or package.json) require matching updates.
+---
+
+# Documentation Sync Skill
+
+This skill ensures that your project's "Source of Truth" documents accurately reflect the current state of the codebase.
+
+## Overview
+
+Documentation rot is one of the most common issues in fast-moving engineering projects. When code and documentation diverge, developers build integrations on false assumptions, leading to runtime failures and wasted hours. This skill establishes high-fidelity documentation syncing as a standard part of the implementation flow.
+
+## When to Use
+
+- A route, controller, or public interface signature has been added, modified, or deleted.
+- Database schema changes (migrations, ORM models, or raw SQL structures) have occurred.
+- Environment variables or initialization requirements have been introduced or altered.
+- Styling system design tokens (colors, margins, font hierarchies) have been updated in code.
+
+**When NOT to use:**
+- Internal refactorings or small bug fixes that do not alter the public API, database schemas, or project setup.
+- Writing temporary scripts or local scratch files.
+
+## Workflow
+
+1.  **Analyze & Detect**:
+    - Identify which document needs syncing (`API.md`, `Schema.md`, `Design.md`, `README.md`, etc.).
+    - Scan the relevant source files (e.g., routes files for API, prisma/sql for Schema, CSS/React for Design).
+    - Identify specific discrepancies (missing fields, changed endpoints, new colors).
+
+2.  **Propose Changes**:
+    - Show the user the detected changes and the proposed updates to the documentation.
+    - Ask: "I've detected new endpoints in `routes/user.ts`. Should I add them to `API.md`?"
+
+3.  **Execute Sync**:
+    - Update the documentation files using `replace_file_content` or `multi_replace_file_content`.
+    - Ensure formatting remains consistent with the project's standards.
+
+4.  **Verify**:
+    - Do a final cross-check to ensure no information was missed.
+    - Check if related documents also need updates (e.g., changing a DB field in `Schema.md` might require an update to `API.md`).
+
+## Detailed Instructions
+
+You are the "Chronicler." Your goal is to eliminate "Documentation Rot."
+
+### High-Fidelity API Syncing
+When updating `API.md`:
+- Don't just list the route. Include the required headers, request body structure, and successful/error response examples.
+- Read the validation logic (e.g., Zod, Joi) to ensure the docs list the correct field constraints.
+
+### High-Fidelity Schema Syncing
+When updating `Schema.md`:
+- Read the ORM files (Prisma, TypeORM) or raw SQL migrations.
+- Capture relationships (1:1, 1:N, N:M) accurately in the documentation.
+- Note any default values or constraints (e.g., `isUnique`, `isNullable`).
+
+### High-Fidelity Design Syncing
+When updating `Design.md`:
+- Scan the root CSS or Theme configuration files.
+- If a new color or spacing token was added to the code but isn't in `Design.md`, add it.
+- Ensure the `Active Baseline Configuration` (Variance, Intensity, Density) still reflects the current vibe of the app.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The code is self-documenting, so docs are optional." | Self-documenting code explains *how* it works, but not *why*. External developers, AI agents, and non-technical stakeholders cannot read raw code efficiently. |
+| "I will update the documentation in a subsequent pull request." | Stale documentation starts immediately. By separating documentation from implementation, it is highly likely to be forgotten or postponed indefinitely. |
+| "It takes too long to document schemas manually." | Manual correctness prevents hours of downstream integration issues. Always sync API/DB changes alongside the code that introduces them. |
+
+## Red Flags
+
+- Modifying route signatures or request payloads without checking if `API.md` requires updates.
+- Running database migrations or changing ORM schemas without matching updates to `Schema.md` or dependency docs.
+- Introducing new environment variables without adding them to `.env.example` or updating setup instructions in `README.md`.
+- Leaving standard template placeholder comments or empty sections inside updated documentation.
+
+## Verification
+
+After completing the sync, verify:
+- [ ] Documentation accurately reflects the current state of the codebase.
+- [ ] No placeholder values or boilerplate remains in the synchronized sections.
+- [ ] All request/response payloads, headers, and schemas are complete.
+- [ ] Auxiliary files (e.g., `README.md`, `.env.example`) have been reviewed for consistency.

package/skills/agent/using-agent-skills/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+hints: |
+  - Always consult this skill map first when starting any new development phase.
+  - Make explicit assumptions using the "ASSUMPTIONS I'M MAKING" format before coding.
+  - Present trade-offs immediately when noticing conflicting requirements or specs.
+  - Prioritize code simplicity and write surgical diffs that only touch requested files.
+  - Ensure every step of the lifecycle sequence is verified with concrete runtime evidence.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Don't know what you want yet? ──────→ interview-me
+    ├── Have a rough concept, need variants? → idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   ├── Need better context? ─────→ context-engineering
+    │   ├── Need doc-verified code? ───→ source-driven-development
+    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    ├── Finishing a task/feature? ────→ project-handover-and-walkthrough
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1.  interview-me                → Extract what the user actually wants
+2.  idea-refine                 → Refine vague ideas
+3.  spec-driven-development     → Define what we're building
+4.  planning-and-task-breakdown → Break into verifiable chunks
+5.  context-engineering         → Load the right context
+6.  source-driven-development   → Verify against official docs
+7.  incremental-implementation  → Build slice by slice
+8.  doubt-driven-development    → Cross-examine non-trivial decisions in-flight
+9.  test-driven-development     → Prove each slice works
+10. code-review-and-quality     → Review before merge
+11. git-workflow-and-versioning → Clean commit history
+12. documentation-and-adrs      → Document decisions
+13. project-handover-and-walkthrough → Summarize work with walkthrough.md
+14. shipping-and-launch         → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | [interview-skill](../interview-skill/SKILL.md) | Surface what the user actually wants before any plan, spec, or code exists |
+| Define | [idea-refine-skill](../idea-refine-skill/SKILL.md) | Refine ideas through structured divergent and convergent thinking |
+| Define | [spec-driven-skill](../spec-driven-skill/SKILL.md) | Requirements and acceptance criteria before code |
+| Plan | [planning-skill](../planning-skill/SKILL.md) | Decompose into tasks and track progress via task.md |
+| Build | [incremental-skill](../../lifecycle/incremental-skill/SKILL.md) | Thin vertical slices, test each before expanding |
+| Build | [source-driven-skill](../source-driven-skill/SKILL.md) | Verify against official docs before implementing |
+| Build | [doubt-driven-skill](../doubt-driven-skill/SKILL.md) | Adversarial fresh-context review of every non-trivial decision |
+| Build | [taste-skill](../../design/taste-skill/SKILL.md) | Production-quality UI with accessibility |
+| Build | [api-skill](../../api/api-skill/SKILL.md) | Stable interfaces with clear contracts |
+| Verify | [testing-skill](../../api/testing-skill/SKILL.md) | Failing test first, then make it pass |
+| Verify | [browser-testing-skill](../../qa/browser-testing-skill/SKILL.md) | Chrome DevTools MCP for runtime verification |
+| Verify | [debugging-and-error-recovery](../debugging-and-error-recovery/SKILL.md) | Reproduce → localize → fix → guard |
+| Review | [code-reviewer](../../../agents/code-reviewer.md) | Five-axis review with quality gates |
+| Review | [security-auditor](../../../agents/security-auditor.md) | OWASP prevention, input validation, least privilege |
+| Review | [performance-skill](../../api/performance-skill/SKILL.md) | Measure first, optimize only what matters |
+| Ship | [git-workflow-skill](../../codebase/git-workflow-skill/SKILL.md) | Atomic commits, clean history |
+| Ship | [ci-cd-skill](../../devops/ci-cd-skill/SKILL.md) | Automated quality gates on every change |
+| Ship | [adr-skill](../adr-skill/SKILL.md) | Document the why, not just the what |
+| Ship | [handover-skill](../handover-skill/SKILL.md) | Final walkthrough and handover via walkthrough.md |
+| Ship | [shipping-skill](../../lifecycle/shipping-skill/SKILL.md) | Pre-launch checklist, monitoring, rollback plan |
+

package/skills/api/a11y-skill/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: a11y-skill
+description: WCAG 2.1 AA accessibility mandates for the frontend. Use when implementing or reviewing user interface components, form inputs, modals, or motion effects.
+hints: |
+  - Always use semantic HTML tags (like button, main, nav, section) instead of styled divs.
+  - Ensure every interactive element is keyboard-focusable with visible focus-visible indicators.
+  - Associate all input fields with clear label tags and connect error messages via aria-describedby.
+  - Implement focus-traps for modals and popovers, restoring focus on close.
+  - Audit color contrast ratios and respect prefers-reduced-motion media queries for transitions.
+---
+
+# Accessibility (A11Y) Skill
+
+## Overview
+
+User interfaces must meet WCAG 2.1 Level AA standards. Accessibility is a first-class citizen in modern interface design, ensuring that apps are robust, accessible, and compliant for all users, including those using assistive technologies.
+
+## Workflow
+
+- **Semantic HTML Only**
+  - Use `<button>` for actions, `<a>` for navigation.
+  - Never use `div` or `span` for interactive elements without proper ARIA roles and keyboard listeners.
+  - Maintain a logical heading hierarchy (`h1` -> `h2` -> `h3`).
+
+- **Interactive Elements**
+  - Every interactive element must be keyboard-reachable (Tab) and operable (Enter/Space).
+  - Use `aria-label` for icon-only buttons.
+  - Never remove focus outlines without providing a high-contrast `:focus-visible` alternative.
+
+- **Forms & Inputs**
+  - Every input must have an associated `<label>`.
+  - Use `aria-describedby` to link error messages to their respective inputs.
+  - Use `aria-invalid="true"` for fields with errors.
+
+- **Visual & Motion**
+  - Maintain a 4.5:1 contrast ratio for normal text.
+  - Respect `prefers-reduced-motion` for all animations.
+  - Do not rely on color alone to convey status (use icons or text labels).
+
+- **Focus Management**
+  - Modals must trap focus while open.
+  - Focus must return to the triggering element upon modal closure.
+
+## Implementation Pattern (React)
+
+```tsx
+<button
+  aria-label="Close modal"
+  className="focus-visible:ring-2 focus-visible:ring-dd-accent"
+  onClick={onClose}
+>
+  <XIcon aria-hidden="true" />
+</button>
+```
+
+## When to Use
+
+- Designing, building, or refactoring user interfaces, navigation menus, and page structures.
+- Creating interactive components such as modals, dropdowns, popovers, or forms.
+- Adding custom styling focus effects, animations, or state indicators.
+
+**When NOT to use:**
+- Developing purely headless CLI tools, server backend APIs, or cron jobs that lack user interfaces.
+- Running internal unit tests that do not involve DOM rendering or browser-based UI.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Accessibility is a nice-to-have we can add later." | Retrofitting accessibility is extremely expensive as it requires changing DOM structures and component behaviors. Day-one accessibility ensures robust interfaces. |
+| "A styled div with an onClick handler is good enough." | Styled divs lack default keyboard interactivity (Tab focus, Enter/Space activation) and screen reader support, completely blocking disabled users. |
+| "Default browser focus outlines look ugly, so I'll disable them." | Disabling focus outlines makes the app unusable for keyboard-only users. Always replace default outlines with premium custom `:focus-visible` styles. |
+
+## Red Flags
+
+- Interactive elements constructed from `<div>` or `<span>` without ARIA roles, `tabindex="0"`, or keyboard event listeners.
+- Using `outline: none` or `outline: 0` in CSS without providing a visible focus alternative.
+- Icon-only buttons lacking `aria-label` or descriptive visually-hidden text.
+- Form inputs without corresponding `<label>` tags or using placeholder attributes as the sole label.
+
+## Verification
+
+After completing the UI implementation, verify:
+- [ ] Tab key navigation succeeds through all interactive elements in logical order.
+- [ ] No keyboard focus traps exist (user can navigate into and out of all controls).
+- [ ] Screen reader roles and accessibility trees are checked (using Chrome DevTools or axe audits).
+- [ ] All inputs have associated labels and announce error states correctly using ARIA attributes.
+- [ ] Interactive modals restrict focus to their active contents and restore focus on exit.

package/skills/api/api-skill/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: api-skill
+description: Mandatory middleware, validation boilerplate, error safe-listing, and performance rules for fast, consistent, and secure endpoints.
+hints: |
+  - Verify existing API routes, schemas, and specs in the project before drafting new endpoints.
+  - Implement a strong validation layer (e.g. Zod, Joi) covering all incoming body, query, and path parameters.
+  - Apply security middleware, rate-limiting, and authentication gates to all non-public endpoints.
+  - Safe-list user-visible errors and never leak database stack traces or internal secrets to the client.
+  - Optimize query performance by selecting explicit columns and using cursor-based pagination for lists.
+---
+
+# API Standards Skill
+
+## Overview
+
+This skill ensures every network endpoint is fast, consistent, secure, and well-designed. Standardizing input validation, error mapping, rate limiting, and database interactions prevents security vulnerabilities and performance bottlenecks at the entry point of the application.
+
+## Workflow
+
+### 1. Document & Align Check
+Before crafting or modifying any endpoint, review the project's active API specification files (e.g., `API.md`, `openapi.yaml`, or `docs/api/`). Ensure your endpoints adhere exactly to the defined naming schemes, payload structures, and architectural standards.
+
+### 2. Implement the "Security Shield" Ingress
+Use the following pattern for every new route to guarantee input hygiene, authentication, and rate limiting:
+
+```typescript
+import { Request, Response } from 'express';
+import { z } from 'zod';
+import { redisRateLimit } from '../../middleware/rateLimit';
+import { requireAuth } from '../../middleware/auth';
+import { sendSuccess, ErrorResponses } from '../../utils/response';
+
+// 1. Define Input Schema
+const InputSchema = z.object({
+  id: z.string().uuid(),
+  // ... other fields
+});
+
+export const myNewEndpoint = [
+  // 2. Apply Rate Limit
+  redisRateLimit({ windowMs: 60000, max: 10 }), 
+  
+  // 3. Authenticate
+  requireAuth, 
+  
+  async (req: Request, res: Response) => {
+    try {
+      // 4. Validate Input
+      const data = InputSchema.parse(req.body);
+      
+      // 5. Derive Identity
+      const userId = req.user.id; 
+
+      // ... Business Logic ...
+
+      return sendSuccess(res, { result });
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return ErrorResponses.badRequest(res, 'Invalid input', 'VALIDATION_ERROR');
+      }
+      console.error('API Error:', error);
+      return ErrorResponses.internalError(res);
+    }
+  }
+];
+```
+
+## Error Safe-Listing
+
+Map all internal system errors to secure, generic client-facing errors. Never leak raw database queries, connection failures, or environment details.
+
+| Internal Code / Error Type | HTTP Status | Visible to Client? | Exposed Client Code |
+|---|---|---|---|
+| `ZodError` / Input validation | 400 Bad Request | Yes (with field details) | `VALIDATION_ERROR` |
+| Missing Session Token / Expired | 401 Unauthorized | Yes | `AUTH_REQUIRED` |
+| Insufficient Permissions / Roles | 403 Forbidden | Yes | `FORBIDDEN` |
+| Database Entity Missing | 404 Not Found | Yes | `NOT_FOUND` |
+| Raw Database Exception (`DB_ERROR`) | 500 Internal Error | **NO** | `INTERNAL_ERROR` |
+| Third-Party API Failure | 500 Internal Error | **NO** | `INTERNAL_ERROR` |
+
+---
+
+## Performance Rules
+
+- **No `SELECT *`**: Always explicitly select the required columns. Scanning and returning unused database fields wastes database memory and network bandwidth.
+- **Cursors Only**: Use cursor-based keys (`before`/`after` or comparable token indices) for list pagination. Avoid `OFFSET` pagination, which degrades rapidly as tables grow.
+- **Cache-Aside Pattern**: Wrap resource-intensive, read-heavy query operations (like listings, configs, or stats) in cached gets/sets (e.g., Redis) with explicit TTLs.
+
+---
+
+## When to Use
+
+- Implementing new REST, GraphQL, or RPC endpoints in backend routers.
+- Modifying existing request/response structures or validation schemas.
+- Refactoring data fetch APIs, database pagination, caching logic, or error handling.
+
+**When NOT to use:**
+- Internal utility functions, helper libraries, or offline CLI commands that do not expose public network endpoints.
+- Developing pure client-side markup or styling layout elements.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll add validation and security middlewares later." | Security and input validation are baseline requirements, not post-implementation decorations. Out-of-order security leads to leaked data. |
+| "Leaking internal stack traces helps me debug faster in staging." | Stack traces and DB messages leak structural details about database models, schemas, and packages, giving attackers vectors to exploit. |
+| "Offset pagination is easier to implement." | Offset pagination (`LIMIT/OFFSET`) scales poorly. As datasets grow, the database must scan millions of rows to discard them, causing severe latency degradation. |
+
+## Red Flags
+
+- Request handler reading raw untrusted `req.body` variables without structural validation.
+- Database query executing `SELECT *` or lack of explicit select fields.
+- Returning raw server errors or database exceptions directly in JSON response blocks.
+- Pagination endpoints that do not accept cursor boundaries or rely solely on page offsets.
+
+## Verification
+
+After completing the API endpoint, verify:
+- [ ] Route uses the "Security Shield" pattern (Rate limits, Authentication, Validation).
+- [ ] Zod or equivalent validation schemas strictly validate all parameters (body, query, params).
+- [ ] Malformed or invalid payloads return safe `VALIDATION_ERROR` responses with 400 statuses.
+- [ ] System logs stack traces on exceptions, but clients receive a generic `INTERNAL_ERROR` 500 status.
+- [ ] Large list responses enforce cursor-based pagination and select explicit database columns.

package/skills/api/auth-skill/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: auth-skill
+description: Identity, JWT rules, session management, and security logic for authentication. Use when building or modifying login, registration, password resets, token generation, or authentication middlewares.
+hints: |
+  - Ensure JWT payloads remain clean of any Personally Identifiable Information (PII).
+  - Verify WebAuthn/Passkey signatures, origins, and authenticator counters strictly.
+  - Implement a session "Kill Switch" that blacklists active session IDs on password changes.
+  - Enforce httpOnly, secure, and sameSite cookie attributes for refresh tokens.
+  - Apply brute-force protection using rate limiters on all authentication and password reset routes.
+---
+
+# Authentication & Security Skill
+
+## Overview
+
+This skill governs the identity, session, and credential lifecycle of users. Authentication is the primary security gate of the application; failure to adhere to these rules results in severe security vulnerabilities `[SEC-202]`.
+
+## Workflow
+
+- **[AUTH-001] JWT Payload Hygiene**
+  - Only include: `sub` (userId), `sid` (sessionId), `role`, and `exp`.
+  - **Never** include: Email, full name, phone number, or any other Personally Identifiable Information (PII) in the JWT.
+
+- **[AUTH-002] Passkey Lifecycle**
+  - Use `@simplewebauthn/server` or an equivalent secure library for all WebAuthn flows.
+  - Registration: Verify `challenge` and matching hostname `origin`.
+  - Authentication: Verify the signature and ensure the `counter` is strictly incrementing to detect cloned authenticators.
+
+- **[AUTH-003] The "Kill Switch" Mechanism**
+  - If a user changes their password or requests "Log out from all devices," all active sessions (`user_sessions` table) must be immediately deleted.
+  - Admins can revoke any session by `sessionId`, which must immediately block the associated Access Token via a real-time Redis blacklist.
+
+- **[AUTH-004] Brute-Force Shield**
+  - Apply `redisRateLimit` or standard IP rate-limiting to all Auth routes (login, register, password reset).
+  - Failed attempts should trigger exponential backoff to prevent automated dictionary attacks.
+
+## Implementation Details
+
+### Session Revocation Pattern
+When revoking a session, perform these steps:
+1. Delete the row from the active sessions table (e.g., `user_sessions`).
+2. Add `sid` to a Redis `revoked_sessions` set with a TTL matching the remaining JWT expiry.
+3. Middleware `requireAuth` must check this Redis set on every request to block revoked but not-yet-expired tokens.
+
+---
+
+## When to Use
+
+- Building or modifying authentication systems (OAuth, standard login/signup, Passkeys/WebAuthn).
+- Designing session lifecycles, refresh token rotations, or JWT signing strategies.
+- Setting up access control gates, route guards, and identity middlewares.
+- Implementing password recovery, email verification, or account deletion flows.
+
+**When NOT to use:**
+- Internal communications between microservices inside a secure VPC where authentication is managed at the network or service-mesh layer.
+- Static client-side routing where page access control is handled solely as a UX/UI enhancement rather than a security boundary.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Storing the user email in the JWT makes it easy to read in the frontend." | JWTs are base64-encoded, not encrypted. Storing emails or names in a JWT exposes PII to anyone inspecting the token, violating data privacy regulations. |
+| "A session table is enough; we don't need real-time revocation checking." | Access tokens (JWTs) remain valid until they expire. Without a real-time Redis blacklist or short-lived token validation, active attackers cannot be locked out. |
+| "I'll store the refresh token in LocalStorage for simplicity." | Storing session secrets in LocalStorage makes them fully accessible to cross-site scripting (XSS) attacks. Refresh tokens must only live in httpOnly cookies. |
+
+## Red Flags
+
+- Refresh tokens stored in standard cookies without `httpOnly: true` or `secure: true` attributes.
+- Storing full names, phone numbers, or passwords inside JWT payload bodies.
+- Failing to increment or verify WebAuthn authenticator counters during Passkey authentication.
+- Auth endpoints (login, register, reset) that do not enforce active rate-limiting middleware.
+
+## Verification
+
+After completing the authentication setup, verify:
+- [ ] JWT payloads are inspected and confirm they only contain non-sensitive identifiers (`sub`, `sid`, `role`, `exp`).
+- [ ] Password resets successfully revoke all active database sessions and invalidate outstanding access tokens.
+- [ ] Refresh tokens are confirmed to be delivered via secure, httpOnly, sameSite cookies.
+- [ ] Brute-force requests against auth endpoints are actively blocked by rate limiters.
+- [ ] WebAuthn registration/authentication processes verify signatures, origins, and anti-cloning counters.