@kinqs/brainrouter-mcp-server 0.3.4

package/skills/codebase/code-structure-cleanup/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: code-structure-cleanup
+description: Guides a service-layer extraction pass after an AI-built feature ships. Use when feature code works but contains duplicated mechanics, repeated API calls, or copy-pasted logic across multiple callers. Use when deciding what belongs in shared services vs. domain-specific actions.
+hints: |
+  - Run cleanup AFTER the feature works, never during feature development.
+  - Extract only logic repeated across 2+ callers — never abstract singletons.
+  - Keep domain rules (auth, error classification, status transitions) in actions.
+  - Replace one caller first, verify, then migrate the rest.
+  - Keep the diff small and focused on the feature area only.
+---
+
+# Code Structure Cleanup & Service Layer Architecture
+
+## Overview
+
+AI agents often take the easiest path: they create new functions instead of reusing existing ones. A feature can work while still leaving behind duplicated logic, inconsistent validation, and repeated API calls that future agents will struggle to debug.
+
+The fix is a two-layer architecture: **actions orchestrate domain rules** (the "why/when"), while a **service layer centralizes reusable mechanics** (the "how"). Run the cleanup pass after the feature works — not before, and not during.
+
+## When to Use
+
+- A feature works but the code has duplicated mechanics across multiple files.
+- Multiple callers perform the same low-level operation (email sending, sandbox creation, API calls, data parsing).
+- The agent created similar helper functions in different files.
+- A bug fix in one flow was not propagated to other flows doing the same thing.
+
+**When NOT to use:** Logic used by only one caller — extracting it is over-abstraction. Do not use this as permission to redesign the whole app.
+
+## The Service Layer Pattern
+
+```
+Orchestration Layer (Actions)          Service Layer (Shared Mechanics)
+├── owns business rules                ├── owns reusable operations
+├── owns state transitions             ├── owns provider/SDK interactions
+├── owns auth/ownership checks         ├── owns command execution details
+├── owns failure classification        ├── owns health checks / readiness
+├── owns retries / user-facing errors  └── returns structured results
+└── calls service functions
+```
+
+**Decision rule:**
+- "What this product flow means" → keep in actions
+- "How to do this operation reliably" → move to service layer
+
+### Designing Service Functions
+
+Design as **capability blocks**, not monoliths. Each function should:
+- Accept all required data as **explicit parameters** (no hidden global state)
+- Return **structured outputs** — e.g., `{ ready, previewUrl, proxyPort }`
+- Never reach into the database or domain state directly
+- Make failure explicit (structured results, not swallowed errors)
+
+```ts
+// Good: composable blocks — each caller picks what it needs
+createManagedSandbox(...)
+prepareRepo(...)
+detectPackageManager(...)
+installDependencies(...)
+runBuildCommand(...)
+
+// Bad: one god function that hides all control flow
+doEverythingForSandbox(...)
+```
+
+## Cleanup Process
+
+### Step 1: Run the Cleanup Prompt
+
+```md
+The feature is working. Now do a code-structure cleanup pass.
+
+Goal:
+- Find duplicated runtime mechanics, repeated API calls, repeated parsing, repeated validation.
+- Move repeated mechanics into reusable service-layer functions/modules.
+- Keep domain policy (auth, status transitions, error classification) in the calling route/action.
+- Do not change user-facing behavior.
+- Keep the diff small.
+
+Process:
+1. Inspect the files touched by the feature.
+2. Identify repeated logic and name the duplication clearly.
+3. Propose the smallest service-layer extraction.
+4. Implement it.
+5. Run the relevant tests/typechecks.
+6. Summarize exactly what got simpler.
+```
+
+### Step 2: Migrate Incrementally
+
+1. Write the flow in action code first — establish clear behavior.
+2. Mark repeated operational chunks across callers.
+3. Extract **only** repeated, non-domain chunks to a service function.
+4. Replace **one caller first** → verify tests pass → replace remaining callers.
+5. Run typecheck, lint, and confirm all flows still work.
+
+### Example: Email Service
+
+```ts
+// emailService.ts — shared mechanics (the "how")
+export async function sendWelcomeEmail(params: { to: string; name: string }) {
+  const html = `<h1>Welcome ${params.name}</h1>`;
+  await emailProvider.send(params.to, "Welcome", html);
+}
+
+// userSignup.ts — orchestration (the "when" — different business rule)
+if (user.marketingOptIn) {
+  await sendWelcomeEmail({ to: user.email, name: user.name });
+}
+
+// adminInvite.ts — orchestration (same mechanic, different domain rule)
+await sendWelcomeEmail({ to: invitee.email, name: invitee.name });
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll clean it up later" | Later never comes. AI agents copy existing patterns — duplicated code compounds with every new feature. |
+| "It's only in two places" | Two callers is exactly when to extract. Three callers means the window for clean extraction is closing. |
+| "Cleanup will change behavior" | It should not. Behavior-changing cleanup is a bug fix or refactor — do it separately. |
+| "I'll just refactor the whole module while I'm here" | Unscoped cleanup creates risky diffs and noisy PRs. Stay focused on the feature area. |
+| "The service should handle business logic too" | Services own mechanics, not decisions. Auth, error classification, and policy stay in actions. |
+
+## Red Flags
+
+- A bug fix applied in one flow was not applied to other flows doing the same thing.
+- Helper functions with the same logic scattered across action files.
+- Service functions that directly mutate database tables or domain state.
+- A single "do-everything" service function hiding all control flow.
+- Cleanup and feature development mixed in the same PR.
+- Extracting logic used by only one caller (premature abstraction).
+
+## Verification
+
+After completing the cleanup pass, confirm:
+
+- [ ] User-facing behavior is unchanged (existing tests still pass).
+- [ ] Duplicated mechanics were reduced — callers now share the extracted function.
+- [ ] Calling files became simpler, not more complex.
+- [ ] Domain policy (auth, transitions, error classification) remained in actions.
+- [ ] Typecheck and lint passed.
+- [ ] Diff is focused on the feature area — no unrelated changes mixed in.

package/skills/codebase/concerns-skill/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: concerns-skill
+description: Framework for surfacing and tracking tech debt, known bugs, and security gaps in software codebases.
+hints:
+  - Check openSrc/ or docs for existing tech debt registers and known bugs if available.
+  - Formulate codebase concern reports with specific file paths, line numbers, and factual impact.
+  - Avoid emotional adjectives; use precise engineering terms (e.g. N+1 queries, race conditions).
+  - Provide a clear, actionable fix or mitigation approach for every logged concern.
+  - Update or remove concern entries immediately upon resolution.
+---
+
+# Codebase Concerns Skill
+
+## Overview
+
+This skill governs how known risks, tech debt, and codebase health issues are surfaced and maintained. Load this before making changes to high-risk areas, during phase planning, or when onboarding a new agent context.
+
+## Workflow
+
+- **[CONCERN-001] Always Check Before Changing**
+  - Before modifying a flagged area, read its concern entry to understand risk, workarounds, and safe modification paths.
+  - If no concern entry exists for an area you're about to change, check for fragility signals (complex chains, missing tests, shared mutable state).
+
+- **[CONCERN-002] Concern Entry Format**
+  - Every concern must include: area/component, issue description, why it exists, impact, and fix approach.
+  - Always include **file paths** — concerns without locations are not actionable.
+  - Use specific measurements for performance issues (`500ms p95`, not "slow").
+  - Include reproduction steps for bugs.
+
+- **[CONCERN-003] Categories**
+  - **Tech Debt**: Shortcuts with known impact and a fix path.
+  - **Known Bugs**: Reproducible defects with symptoms, trigger, and workaround.
+  - **Security Considerations**: Risks with current mitigation and recommendations.
+  - **Performance Bottlenecks**: Measured slow paths with root cause and improvement plan.
+  - **Fragile Areas**: Components that break easily — document safe modification steps.
+  - **Scaling Limits**: Capacity numbers and what happens at the limit.
+  - **Dependencies at Risk**: Deprecated, unmaintained, or breaking-change packages.
+  - **Test Coverage Gaps**: Untested paths and the risk they carry.
+
+- **[CONCERN-004] Tone & Accuracy**
+  - Professional, not emotional (`"N+1 query pattern"` not `"terrible queries"`)
+  - Solution-oriented — always suggest a fix approach, not just a problem
+  - Factual — use real numbers, not vague qualifiers
+  - No opinions without evidence; no complaints without solutions
+
+- **[CONCERN-005] Maintenance**
+  - Mark concerns as resolved when the underlying issue is fixed.
+  - Add new concerns as they are discovered — during audits, debugging, or code review.
+  - Include the analysis date on each update.
+  - This is a living document, not a complaint list.
+
+## When to Load This Skill
+
+| Scenario | Action |
+|---|---|
+| About to change auth, middleware, or DB layer | Read **Fragile Areas** and **Security Considerations** |
+| Planning a new feature phase | Read **Tech Debt** and **Scaling Limits** |
+| Debugging an unexpected failure | Read **Known Bugs** |
+| Writing or reviewing tests | Read **Test Coverage Gaps** |
+| Evaluating dependencies | Read **Dependencies at Risk** |
+
+## Required Checks
+
+- [ ] Concern entry has a file path — no location-less concerns.
+- [ ] Performance numbers are actual measurements, not estimates.
+- [ ] Bugs include a reproduction trigger.
+- [ ] Resolved concerns are removed or marked fixed with a date.
+- [ ] New concerns added after any audit or incident.
+
+## When to Use
+- Use when preparing to work on existing codebases, planning refactoring phases, or onboarding onto unfamiliar directories.
+- NOT for styling changes or single-file variable renames unless they are part of a larger architectural risk.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| I don't have time to catalog debt. | Logging debt takes 2 minutes and prevents the next developer from breaking the system. |
+| It's just a temporary hack, no need to log it. | Temporary hacks frequently become permanent; documenting them prevents future blindspots. |
+
+## Red Flags
+- Technical debt or security gaps left unrecorded in codebase documentation.
+- Vague reports like "the DB is slow" without specific query profiles, execution times, or metric traces.
+- Modifying fragile codebase components without checking existing concern registers or tech debt lists first.
+
+## Verification
+After completing the skill, confirm:
+- [ ] All newly identified concerns are logged with precise file paths, triggers, and suggested fix paths.
+- [ ] Any resolved concerns are updated in the tracking documents.
+- [ ] Tone of logged issues is kept entirely factual, metric-driven, and constructive.

package/skills/codebase/conventions-skill/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: conventions-skill
+description: Naming patterns, formatting rules, import order, and module design standards for modern software codebases.
+hints:
+  - Inspect project root configuration files (e.g. .prettierrc, eslint.config.js) to align with existing styling tools.
+  - Check openSrc/ or existing project files for naming patterns and module architecture styles.
+  - Follow kebab-case for system files and PascalCase for UI components (e.g. React components).
+  - Keep functions focused and under 50 lines; extract complex logic into small, reusable helpers.
+  - Eliminate console.log statements before committing, substituting appropriate logging utilities.
+---
+
+# Coding Conventions Skill
+
+## Overview
+
+This skill ensures all new code written in the codebase matches existing style and patterns. Load this before writing new files, adding features, or conducting code reviews.
+
+## Workflow
+
+- **[CONV-001] Naming**
+  - Files: `kebab-case` for all files (`user-service.ts`, `location-controller.ts`)
+  - React components: `PascalCase.tsx` (`SpotCard.tsx`, `AuthGuard.tsx`)
+  - Functions & variables: `camelCase`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Types & Interfaces: `PascalCase`, no `I` prefix (`User`, not `IUser`)
+  - Event handlers: `handleEventName` pattern (`handleSubmit`, `handleDelete`)
+
+- **[CONV-002] Code Style**
+  - Formatter: Prettier (check `.prettierrc`)
+  - Linter: ESLint (check `eslint.config.js`)
+  - Quotes: single quotes for strings
+  - Semicolons: required
+  - Line length: 100 characters max
+  - Indentation: 2 spaces
+  - No `console.log` in committed code — use the project logger
+
+- **[CONV-003] Import Order**
+  1. External packages (`react`, `express`, `zod`)
+  2. Internal modules (`@/lib`, `@/services`, `@/components`)
+  3. Relative imports (`./utils`, `../types`)
+  4. Type imports (`import type {}`) — always last
+  - Blank line between each group; alphabetical within groups
+
+- **[CONV-004] Error Handling**
+  - Throw errors, catch at route/boundary level — not deep in utilities
+  - Custom errors extend `Error` class, named `*Error` (`ValidationError`, `NotFoundError`)
+  - Async functions use `try/catch` — no `.catch()` chains
+  - Always log error context before re-throwing
+
+- **[CONV-005] Function Design**
+  - Keep functions under 50 lines; extract helpers for complex logic
+  - Max 3 parameters — use an options object for 4+
+  - Destructure object parameters in the signature: `function fn({ id, name }: Params)`
+  - Use explicit `return` statements; return early for guard clauses
+
+- **[CONV-006] Module Design**
+  - Named exports preferred; default exports only for React components
+  - Barrel files (`index.ts`) re-export the public API only
+  - Do not export internal helpers from barrel files
+  - Avoid circular dependencies — import from specific files if needed
+
+- **[CONV-007] Comments**
+  - Explain *why*, not *what*
+  - Document business rules and non-obvious algorithms
+  - JSDoc required for public API functions (`@param`, `@returns`, `@throws`)
+  - TODOs: `// TODO: description` — link to issue number if available
+
+## Required Checks
+
+- [ ] File and function names match `CONV-001` patterns.
+- [ ] No `console.log` left in committed code.
+- [ ] Imports are ordered and grouped per `CONV-003`.
+- [ ] All async code uses `try/catch`.
+- [ ] Functions stay under 50 lines.
+
+## When to Use
+- Use when creating new modules, adding endpoints, writing frontend components, or conducting local codebase cleanups and refactoring.
+- NOT for simple documentation-only changes or config modifications.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| I'll format the code manually later. | Automated formatting ensures clean git diffs and prevents formatting noise. |
+| It's just a single console.log for quick debugging. | Forgotten debug logs clutter runtime output in production and create noise. |
+
+## Red Flags
+- Committing code with generic `console.log` statements instead of proper logging mechanisms.
+- Functions exceeding 50-60 lines without being split into cohesive helpers.
+- Inconsistent file naming conventions (e.g. mixing `camelCase` and `kebab-case` filenames in the same folder).
+
+## Verification
+After completing the skill, confirm:
+- [ ] Prettier/ESLint rules have been run and all styling warnings are cleared.
+- [ ] All imported modules are ordered according to standard grouping.
+- [ ] Functions are short, clean, well-scoped, and documented where necessary.

package/skills/codebase/doc-management-skill/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: doc-management-skill
+description: Guidelines for reading living project documentation using MCP tools.
+hints:
+  - Query project-level documentation using list_template_docs and get_template_doc to discover existing specifications.
+  - Utilize specific section parameters in get_template_doc to read target content efficiently.
+  - Load reference guidelines (e.g. security-checklist, testing-patterns) using get_reference to respect engineering checklists.
+  - Restrict actions to read-only when interacting with documentation via MCP to avoid modifying architectural blueprints.
+  - Fall back to checking openSrc/ or standard project directories (e.g., docs/, doc/) if MCP tools are not available.
+---
+
+# Doc Management Skill
+
+## Overview
+This skill defines the workflow for interacting with project documentation. The Global BrainRouter `docs/` folder contains universal templates. However, the actual living documentation for a user's project resides strictly in their **local project's** `docs/` directory. The MCP tools (`list_template_docs` and `get_template_doc`) only load the local project documents. Documentation via MCP is entirely read-only to prevent unexpected modifications to the user's local architectural blueprints or the server's templates.
+
+## When to Use
+Use this skill whenever you need to understand existing architectural decisions, read API endpoint specifications, check database schemas, load persistent project context from the living documentation, or consult project reference checklists/patterns.
+
+## Workflow
+
+1. **Discover Docs**: Run `list_template_docs` to see the current living documents available for the local project.
+2. **Read Docs**: Run `get_template_doc` to read existing documentation sections to gain important context before working on tasks.
+3. **Read References**: Run `get_reference` to load specific checklists and patterns (e.g., `security-checklist`, `accessibility-checklist`, `orchestration-patterns`) from the `references/` directory.
+
+## Usage
+
+When you are asked to read documentation or reference constraints for the current project:
+1. Always prioritize using the MCP tools (`list_template_docs`, `get_template_doc`, `get_reference`) to locate and load information. 
+   - `get_template_doc` expects the doc name (e.g. `api`, `design`, `schema`, `hooks`, `strategy`, `deployment`).
+   - Use the `section` parameter with `get_template_doc` to target specific headings for larger documents.
+   - `get_reference` expects the name of the reference file without extension (e.g., `security-checklist`, `testing-patterns`).
+2. Do not attempt to update or create documents via standard file writes or non-existent MCP tools.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll just try to use a generic write tool to create docs/API.md" | Modifying or creating docs is intentionally restricted in the MCP context. Read only. |
+
+## Red Flags
+- Attempting to edit docs instead of reading them.
+- Assuming you can update the docs based on outdated context.
+
+## Verification
+- [ ] Did you properly locate the needed documentation using `list_template_docs`?
+- [ ] Did you read the existing documentation section using `get_template_doc` to gain context?

package/skills/codebase/git-workflow-skill/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: git-workflow-skill
+description: Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.
+hints:
+  - Formulate small, atomic commits addressing single logical changes (typically under 100 lines).
+  - Use conventional commit formats (feat:, fix:, refactor:, test:) explaining the "why" instead of the "what".
+  - Inspect stages using git diff --staged to review and purge accidentally staged secrets or temporary comments.
+  - Separate formatting or styling adjustments from behavioral logic updates in distinct commits.
+  - Utilize short-lived feature branches, avoiding long-lived branches that diverge from the main branch.
+---
+
+# Git Workflow and Versioning
+
+## Overview
+
+Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation. With AI agents generating code at high speed, disciplined version control is the mechanism that keeps changes manageable, reviewable, and reversible.
+
+## When to Use
+
+Always. Every code change flows through git.
+
+## Workflow
+
+### Trunk-Based Development (Recommended)
+
+Keep `main` always deployable. Work in short-lived feature branches that merge back within 1-3 days. Long-lived development branches are hidden costs — they diverge, create merge conflicts, and delay integration. DORA research consistently shows trunk-based development correlates with high-performing engineering teams.
+
+```
+main ──●──●──●──●──●──●──●──●──●──  (always deployable)
+        ╲      ╱  ╲    ╱
+         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)
+```
+
+This is the recommended default. Teams using gitflow or long-lived branches can adapt the principles (atomic commits, small changes, descriptive messages) to their branching model — the commit discipline matters more than the specific branching strategy.
+
+- **Dev branches are costs.** Every day a branch lives, it accumulates merge risk.
+- **Release branches are acceptable.** When you need to stabilize a release while main moves forward.
+- **Feature flags > long branches.** Prefer deploying incomplete work behind flags rather than keeping it on a branch for weeks.
+
+### 1. Commit Early, Commit Often
+
+Each successful increment gets its own commit. Don't accumulate large uncommitted changes.
+
+```
+Work pattern:
+  Implement slice → Test → Verify → Commit → Next slice
+
+Not this:
+  Implement everything → Hope it works → Giant commit
+```
+
+Commits are save points. If the next change breaks something, you can revert to the last known-good state instantly.
+
+### 2. Atomic Commits
+
+Each commit does one logical thing:
+
+```
+# Good: Each commit is self-contained
+git log --oneline
+a1b2c3d Add task creation endpoint with validation
+d4e5f6g Add task creation form component
+h7i8j9k Connect form to API and add loading state
+m1n2o3p Add task creation tests (unit + integration)
+
+# Bad: Everything mixed together
+git log --oneline
+x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
+```
+
+### 3. Descriptive Messages
+
+Commit messages explain the *why*, not just the *what*:
+
+```
+# Good: Explains intent
+feat: add email validation to registration endpoint
+
+Prevents invalid email formats from reaching the database.
+Uses Zod schema validation at the route handler level,
+consistent with existing validation patterns in auth.ts.
+
+# Bad: Describes what's obvious from the diff
+update auth.ts
+```
+
+**Format:**
+```
+<type>: <short description>
+
+<optional body explaining why, not what>
+```
+
+**Types:**
+- `feat` — New feature
+- `fix` — Bug fix
+- `refactor` — Code change that neither fixes a bug nor adds a feature
+- `test` — Adding or updating tests
+- `docs` — Documentation only
+- `chore` — Tooling, dependencies, config
+
+### 4. Keep Concerns Separate
+
+Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit — and ideally a separate PR:
+
+```
+# Good: Separate concerns
+git commit -m "refactor: extract validation logic to shared utility"
+git commit -m "feat: add phone number validation to registration"
+
+# Bad: Mixed concerns
+git commit -m "refactor validation and add phone number field"
+```
+
+**Separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion.
+
+### 5. Size Your Changes
+
+Target ~100 lines per commit/PR. Changes over ~1000 lines should be split. See the splitting strategies in `code-review-and-quality` for how to break down large changes.
+
+```
+~100 lines  → Easy to review, easy to revert
+~300 lines  → Acceptable for a single logical change
+~1000 lines → Split into smaller changes
+```
+
+## Branching Strategy
+
+### Feature Branches
+
+```
+main (always deployable)
+  │
+  ├── feature/task-creation    ← One feature per branch
+  ├── feature/user-settings    ← Parallel work
+  └── fix/duplicate-tasks      ← Bug fixes
+```
+
+- Branch from `main` (or the team's default branch)
+- Keep branches short-lived (merge within 1-3 days) — long-lived branches are hidden costs
+- Delete branches after merge
+- Prefer feature flags over long-lived branches for incomplete features
+
+### Branch Naming
+
+```
+feature/<short-description>   → feature/task-creation
+fix/<short-description>       → fix/duplicate-tasks
+chore/<short-description>     → chore/update-deps
+refactor/<short-description>  → refactor/auth-module
+```
+
+## Working with Worktrees
+
+For parallel AI agent work, use git worktrees to run multiple branches simultaneously:
+
+```bash
+# Create a worktree for a feature branch
+git worktree add ../project-feature-a feature/task-creation
+git worktree add ../project-feature-b feature/user-settings
+
+# Each worktree is a separate directory with its own branch
+# Agents can work in parallel without interfering
+ls ../
+  project/              ← main branch
+  project-feature-a/    ← task-creation branch
+  project-feature-b/    ← user-settings branch
+
+# When done, merge and clean up
+git worktree remove ../project-feature-a
+```
+
+Benefits:
+- Multiple agents can work on different features simultaneously
+- No branch switching needed (each directory has its own branch)
+- If one experiment fails, delete the worktree — nothing is lost
+- Changes are isolated until explicitly merged
+
+## The Save Point Pattern
+
+```
+Agent starts work
+    │
+    ├── Makes a change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    ├── Makes another change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    └── Feature complete → All commits form a clean history
+```
+
+This pattern means you never lose more than one increment of work. If an agent goes off the rails, `git reset --hard HEAD` takes you back to the last successful state.
+
+## Change Summaries
+
+After any modification, provide a structured summary. This makes review easier, documents scope discipline, and surfaces unintended changes:
+
+```
+CHANGES MADE:
+- src/routes/tasks.ts: Added validation middleware to POST endpoint
+- src/lib/validation.ts: Added TaskCreateSchema using Zod
+
+THINGS I DIDN'T TOUCH (intentionally):
+- src/routes/auth.ts: Has similar validation gap but out of scope
+- src/middleware/error.ts: Error format could be improved (separate task)
+
+POTENTIAL CONCERNS:
+- The Zod schema is strict — rejects extra fields. Confirm this is desired.
+- Added zod as a dependency (72KB gzipped) — already in package.json
+```
+
+This pattern catches wrong assumptions early and gives reviewers a clear map of the change. The "DIDN'T TOUCH" section is especially important — it shows you exercised scope discipline and didn't go on an unsolicited renovation.
+
+## Pre-Commit Hygiene
+
+Before every commit:
+
+```bash
+# 1. Check what you're about to commit
+git diff --staged
+
+# 2. Ensure no secrets
+git diff --staged | grep -i "password\|secret\|api_key\|token"
+
+# 3. Run tests
+npm test
+
+# 4. Run linting
+npm run lint
+
+# 5. Run type checking
+npx tsc --noEmit
+```
+
+Automate this with git hooks:
+
+```json
+// package.json (using lint-staged + husky)
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md}": ["prettier --write"]
+  }
+}
+```
+
+## Handling Generated Files
+
+- **Commit generated files** only if the project expects them (e.g., `package-lock.json`, Prisma migrations)
+- **Don't commit** build output (`dist/`, `.next/`), environment files (`.env`), or IDE config (`.vscode/settings.json` unless shared)
+- **Have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem`
+
+## Using Git for Debugging
+
+```bash
+# Find which commit introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-commit>
+# Git checkouts midpoints; run your test at each to narrow down
+
+# View what changed recently
+git log --oneline -20
+git diff HEAD~5..HEAD -- src/
+
+# Find who last changed a specific line
+git blame src/services/task.ts
+
+# Search commit messages for a keyword
+git log --grep="validation" --oneline
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll commit when the feature is done" | One giant commit is impossible to review, debug, or revert. Commit each slice. |
+| "The message doesn't matter" | Messages are documentation. Future you (and future agents) will need to understand what changed and why. |
+| "I'll squash it all later" | Squashing destroys the development narrative. Prefer clean incremental commits from the start. |
+| "Branches add overhead" | Short-lived branches are free and prevent conflicting work from colliding. Long-lived branches are the problem — merge within 1-3 days. |
+| "I'll split this change later" | Large changes are harder to review, riskier to deploy, and harder to revert. Split before submitting, not after. |
+| "I don't need a .gitignore" | Until `.env` with production secrets gets committed. Set it up immediately. |
+
+## Red Flags
+
+- Large uncommitted changes accumulating
+- Commit messages like "fix", "update", "misc"
+- Formatting changes mixed with behavior changes
+- No `.gitignore` in the project
+- Committing `node_modules/`, `.env`, or build artifacts
+- Long-lived branches that diverge significantly from main
+- Force-pushing to shared branches
+
+## Required Checks
+
+For every commit:
+
+- [ ] Commit does one logical thing
+- [ ] Message explains the why, follows type conventions
+- [ ] Tests pass before committing
+- [ ] No secrets in the diff
+- [ ] No formatting-only changes mixed with behavior changes
+- [ ] `.gitignore` covers standard exclusions
+
+## Verification
+After completing the skill, confirm:
+- [ ] All staged files are reviewed with `git diff --staged` to confirm formatting is separated from behavior changes.
+- [ ] Commit message is conventional, descriptive, and accurately conveys the "why".
+- [ ] Clean working directory achieved and test passes before pushing.