chore(dev): add .ai/ shared layer for AI customization

.ai/README.md

@@ -0,0 +1,30 @@
+# .ai — Shared AI Customization
+
+Single source of truth for AI customization content used by both GitHub Copilot
+and Claude Code. Each AI system has its own thin wrapper files that reference
+back here.
+
+## Structure
+
+- `instructions/` — Auto-loaded coding standards and guidelines. Maps to
+  Copilot's `.github/instructions/` and Claude Code's `CLAUDE.md @imports`.
+- `skills/` — Reusable workflows invokable by name. Maps to Copilot's
+  `.github/skills/` and Claude Code's `.claude/skills/`.
+- `prompts/` — User-invokable chat prompts (created on demand). Maps to
+  Copilot's `.github/prompts/` and Claude Code's `.claude/skills/`.
+
+## Adding new content
+
+Use the maintenance skills to create new items — they auto-detect which AI
+systems are active and create the appropriate thin wrappers:
+
+- `/ai-add-instruction` — new auto-loaded instruction
+- `/ai-add-prompt` — new user-invokable prompt
+- `/ai-add-skill` — new reusable workflow skill
+
+## Future extraction
+
+The `ai-add-*` maintenance skills in `skills/` are candidates for extraction
+into a Claude plugin and Copilot user-level skills (`~/.copilot/skills/`) once
+they stabilize. When extracted, remove them from here and from the thin wrappers
+in `.github/skills/` and `.claude/skills/`.

.ai/instructions/code-complexity.md

@@ -0,0 +1,81 @@
+# Code Complexity Guidelines
+
+## Core Principles
+
+1. Functions should be small, focused, and do one thing well
+2. Prefer readability over strict metrics
+3. Functions should be pure when possible
+4. Avoid side effects and global state dependencies
+
+## Hard Limits
+
+- **Max 3 parameters** — use object parameter for >3 params or boolean flags
+- **Max 3 nesting levels** — use early returns and guard clauses
+- **Target <30 lines per function** — longer OK if cohesive and clear
+- **Target cyclomatic complexity <15** — higher OK if logic is simple and
+  related
+
+## Examples and Patterns
+
+**Use early returns to reduce nesting:**
+
+```javascript
+// Bad: Deep nesting
+function process(order) {
+  if (order.isValid) {
+    if (order.items.length > 0) {
+      if (order.customer.isActive) {
+        return doWork(order);
+      }
+    }
+  }
+  return null;
+}
+
+// Good: Guard clauses
+function process(order) {
+  if (!order.isValid) return null;
+  if (order.items.length === 0) return null;
+  if (!order.customer.isActive) return null;
+  return doWork(order);
+}
+```
+
+**Use object parameters for related data:**
+
+```javascript
+// Bad: Too many params
+function createUser(name, email, age, address, phone) {}
+
+// Good: Grouped params
+function createUser(userData) {
+  const { name, email, age, address, phone } = userData;
+}
+```
+
+**Extract complex logic into focused functions:**
+
+```javascript
+// Bad: Multiple responsibilities
+function processUserData(user) {
+  validateUser(user);
+  updateDatabase(user);
+  sendWelcomeEmail(user);
+  createUserProfile(user);
+}
+
+// Good: Composed from smaller functions
+function processUserData(user) {
+  validateUser(user);
+  const dbUser = updateDatabase(user);
+  notifyUser(dbUser);
+}
+```
+
+## Checklist
+
+- [ ] Single responsibility
+- [ ] ≤3 parameters
+- [ ] ≤3 nesting levels
+- [ ] Clear, descriptive names
+- [ ] No global state dependencies

.ai/instructions/code-review.md

@@ -0,0 +1,94 @@
+# Copilot Code Review Instructions
+
+Important: This file is intended solely for Copilot and AI agents performing
+code reviews on GitHub. It should not be used by coding assistants or agents
+when implementing code.
+
+## Purpose
+
+Reviews should focus on new or modified code in the PR, not pre-existing issues.
+Comments should be actionable and specific to what changed.
+
+## Core Principles
+
+1. **Review Only New or Modified Code**
+   - Do not comment on issues that existed before the current changes (e.g.,
+     file length, missing JSDoc, legacy patterns).
+   - Focus feedback on code that was added, changed, or deleted in the pull
+     request.
+
+2. **No Retroactive Enforcement**
+   - Don't flag existing violations unless the change introduces a new issue or
+     significantly worsens what's already there.
+   - Example: A file already has 400 lines and the PR adds 10 more. Don't
+     complain about file length. If the PR adds 100+ lines, suggest splitting
+     only the new code.
+
+3. **Actionable Feedback**
+   - Be specific about what changed.
+   - Skip generic complaints about the codebase.
+
+4. **Respect Project-Specific Exceptions**
+   - If project instructions allow exceptions or best-effort patterns, don't
+     enforce stricter rules.
+
+5. **No Blame for Existing Code**
+   - Do not attribute responsibility for existing issues to the current author
+     or PR.
+
+## Examples
+
+- **File Size**:  
+  If a file is already over a recommended line limit and the PR adds more lines,
+  do not flag the file size. Only suggest splitting if the change introduces a
+  new violation.
+
+- **JSDoc/Comments**:  
+  Only require JSDoc for new functions or modified functions that already have
+  JSDoc. Don't force adding JSDoc to legacy code just because it was touched.
+
+- **Tests**:  
+  Require tests for new features or changes, not for untouched existing code.
+
+- **Naming/Patterns**:  
+  Flag naming or pattern issues only in new/modified code.
+
+- **Security**:  
+  Always flag security vulnerabilities in new or modified code, regardless of
+  existing code state.
+
+## Reference to Other Instruction Files
+
+Other instruction files (`code-complexity`, `comments`, `jsdoc-tsdoc`,
+`plan-writing`, `security`, `unit-tests`) are primarily for coding agents
+implementing changes. Use them as guidelines during reviews, but apply standards
+only to new or modified code — don't flag pre-existing issues unless the change
+makes them worse.
+
+## Handling Slight Regressions (Suggestion vs Requirement)
+
+When a change slightly worsens an existing issue, favor suggestions over
+requirements unless the regression is serious:
+
+- **Critical or security-sensitive**: Require fixes for security
+  vulnerabilities, data leaks, or critical bugs before merging.
+- **High-impact performance or correctness**: Require a fix or follow-up plan
+  (open an issue, link to PR).
+- **Low-impact or cosmetic**: Suggest improvements (styling, file length,
+  non-critical JSDoc) but mark as optional.
+- **Easy to fix**: If the fix is quick, request it directly rather than
+  deferring.
+
+When in doubt, suggest rather than require. Explain why for requirements; offer
+examples for suggestions. Link to instruction files when relevant (`jsdoc-tsdoc`,
+`code-complexity`).
+
+## Checklist
+
+- [ ] Feedback is limited to new/changed code
+- [ ] No comments on pre-existing issues unless made worse by the PR
+- [ ] Suggestions are actionable for the current author
+- [ ] No blame or requests to fix existing code
+- [ ] Project-specific instructions and exceptions are respected
+- [ ] Slight regressions handled appropriately (suggestion vs requirement)
+- [ ] Security issues always flagged, regardless of existing code state

.ai/instructions/comments.md

@@ -0,0 +1,61 @@
+# Comments and Documentation
+
+## Core Principles
+
+1. **Default: no comment** — Add comments only when absolutely necessary.
+2. **Only why, never what** — Explain the reason or decision, not what the code
+   does
+3. **Never comment about removed/refactored/changed code** — Comments describe
+   present code only
+4. **Never mention LLM actions** — Avoid phrases like "imported function", "removed code",
+   "refactored", etc.
+5. **Code should be self-documenting** — Prefer making code clearer over adding comments.
+
+## When Comments Are Allowed
+
+Add a why-comment only when the reader would genuinely struggle to understand
+the decision without it:
+
+- **Non-obvious decisions**: Why this approach over alternatives
+- **Edge cases**: Why special handling is needed
+- **Performance trade-offs**: Why we accept certain costs
+- **Magic numbers**: Why this specific value
+
+## Examples and Patterns
+
+```javascript
+// BAD: Describing what code does
+// Loop through items and sum prices
+const total = items.reduce((sum, item) => sum + item.price, 0);
+
+// BAD: Redundant with function name
+// Calculate the total
+function calculateTotal() {}
+
+// BAD: Describing removed code
+// Removed the old validation logic
+
+// BAD: Mentioning refactoring
+// Refactored to use new helper function
+
+// BAD: LLM action commentary
+// Imported the helper function
+// Updated this section per requirements
+
+// GOOD: Explains WHY
+// Using reduce instead of forEach to avoid mutation
+const total = items.reduce((sum, item) => sum + item.price, 0);
+
+// GOOD: Explains non-obvious decision
+// 0.7 threshold balances precision/recall based on historical data analysis
+const DETECTION_THRESHOLD = 0.7;
+```
+
+## Checklist
+
+- [ ] No comment added unless truly necessary
+- [ ] Comment explains why, never what
+- [ ] No mention of removed/refactored/changed code
+- [ ] No LLM action descriptions ("imported", "removed", "refactored")
+- [ ] Comment is about present behavior only
+- [ ] Could not make code clearer instead of commenting