codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/frontend-design/references/css-patterns.md

@@ -0,0 +1,243 @@
+# CSS Design Patterns Reference
+
+Reusable CSS patterns for building distinctive, production-grade interfaces. These patterns avoid generic "AI slop" aesthetics and prioritize intentional design choices.
+
+## Typography Systems
+
+### Font Pairing Strategy
+
+```css
+/* Display + Body pairing — choose contrast, not similarity */
+:root {
+  --font-display: 'Playfair Display', serif;      /* Headlines: high personality */
+  --font-body: 'Source Sans 3', sans-serif;        /* Body: high readability */
+  --font-mono: 'JetBrains Mono', monospace;        /* Code: developer-friendly */
+}
+
+/* Typographic scale (Major Third — ratio 1.25) */
+:root {
+  --text-xs:  0.64rem;   /* 10.24px */
+  --text-sm:  0.8rem;    /* 12.8px  */
+  --text-base: 1rem;     /* 16px    */
+  --text-md:  1.25rem;   /* 20px    */
+  --text-lg:  1.563rem;  /* 25px    */
+  --text-xl:  1.953rem;  /* 31.25px */
+  --text-2xl: 2.441rem;  /* 39px    */
+  --text-3xl: 3.052rem;  /* 48.83px */
+}
+```
+
+### Fluid Typography
+
+```css
+/* Responsive type that scales smoothly between breakpoints */
+h1 {
+  font-size: clamp(2rem, 1rem + 3vw, 4rem);
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+}
+
+p {
+  font-size: clamp(1rem, 0.9rem + 0.25vw, 1.125rem);
+  line-height: 1.65;
+  max-width: 65ch; /* Optimal reading width */
+}
+```
+
+## Color Systems
+
+### HSL-Based Theme Tokens
+
+```css
+/* HSL gives intuitive control over lightness/saturation variants */
+:root {
+  --hue-primary: 230;
+  --hue-accent: 350;
+
+  --color-primary: hsl(var(--hue-primary), 65%, 50%);
+  --color-primary-light: hsl(var(--hue-primary), 65%, 95%);
+  --color-primary-dark: hsl(var(--hue-primary), 65%, 30%);
+
+  --color-accent: hsl(var(--hue-accent), 80%, 55%);
+
+  --color-surface: hsl(0, 0%, 100%);
+  --color-surface-raised: hsl(0, 0%, 98%);
+  --color-text: hsl(0, 0%, 12%);
+  --color-text-muted: hsl(0, 0%, 45%);
+}
+
+/* Dark mode — adjust lightness, not hue */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-primary: hsl(var(--hue-primary), 70%, 65%);
+    --color-surface: hsl(0, 0%, 8%);
+    --color-surface-raised: hsl(0, 0%, 14%);
+    --color-text: hsl(0, 0%, 92%);
+    --color-text-muted: hsl(0, 0%, 60%);
+  }
+}
+```
+
+## Layout Patterns
+
+### Asymmetric Grid
+
+```css
+/* Break the 12-column monotony */
+.asymmetric-grid {
+  display: grid;
+  grid-template-columns: 2fr 1fr;
+  gap: clamp(1.5rem, 3vw, 4rem);
+}
+
+/* Overlap elements for depth */
+.overlap-layout {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+}
+.overlap-layout > .primary {
+  grid-column: 1 / 9;
+  grid-row: 1;
+}
+.overlap-layout > .accent {
+  grid-column: 7 / 13;
+  grid-row: 1;
+  margin-top: 4rem; /* Intentional offset */
+  z-index: 1;
+}
+```
+
+### Container Queries
+
+```css
+/* Component-level responsive design */
+.card-container {
+  container-type: inline-size;
+  container-name: card;
+}
+
+@container card (min-width: 400px) {
+  .card { flex-direction: row; }
+  .card__image { width: 40%; }
+}
+
+@container card (min-width: 700px) {
+  .card { gap: 2rem; }
+  .card__image { width: 50%; }
+}
+```
+
+## Motion & Animation
+
+### Staggered Reveal
+
+```css
+/* Page load animation with staggered children */
+@keyframes reveal-up {
+  from {
+    opacity: 0;
+    transform: translateY(1.5rem);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.stagger-reveal > * {
+  opacity: 0;
+  animation: reveal-up 0.6s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+
+.stagger-reveal > *:nth-child(1) { animation-delay: 0.1s; }
+.stagger-reveal > *:nth-child(2) { animation-delay: 0.2s; }
+.stagger-reveal > *:nth-child(3) { animation-delay: 0.3s; }
+.stagger-reveal > *:nth-child(4) { animation-delay: 0.4s; }
+```
+
+### Hover Interactions
+
+```css
+/* Magnetic lift with shadow depth */
+.interactive-card {
+  transition:
+    transform 0.25s cubic-bezier(0.33, 1, 0.68, 1),
+    box-shadow 0.25s ease;
+}
+
+.interactive-card:hover {
+  transform: translateY(-4px);
+  box-shadow:
+    0 4px 6px -1px rgba(0, 0, 0, 0.06),
+    0 10px 15px -3px rgba(0, 0, 0, 0.08),
+    0 20px 25px -5px rgba(0, 0, 0, 0.04);
+}
+
+.interactive-card:active {
+  transform: translateY(-1px);
+  transition-duration: 0.1s;
+}
+```
+
+## Background & Texture
+
+### Gradient Mesh
+
+```css
+/* Multi-stop gradient for organic feel */
+.gradient-mesh {
+  background:
+    radial-gradient(ellipse at 20% 50%, hsla(200, 80%, 70%, 0.3), transparent 50%),
+    radial-gradient(ellipse at 80% 20%, hsla(340, 80%, 70%, 0.2), transparent 50%),
+    radial-gradient(ellipse at 50% 80%, hsla(260, 60%, 60%, 0.25), transparent 50%),
+    hsl(0, 0%, 98%);
+}
+```
+
+### Noise Texture Overlay
+
+```css
+/* Subtle grain for depth — use a tiny noise PNG or SVG data URI */
+.grain-overlay::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)' opacity='0.04'/%3E%3C/svg%3E");
+  pointer-events: none;
+  z-index: 1;
+}
+```
+
+## Utility Patterns
+
+### Accessible Focus Styles
+
+```css
+/* Visible focus ring that works on any background */
+:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 3px;
+  border-radius: 2px;
+}
+
+/* Remove default outline only when :focus-visible is supported */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+### Scroll-Triggered Animations
+
+```css
+/* Native CSS scroll-driven animations (modern browsers) */
+@keyframes fade-in-up {
+  from { opacity: 0; transform: translateY(2rem); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.scroll-reveal {
+  animation: fade-in-up linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 40%;
+}
+```

package/.ai-rules/skills/git-master/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: git-master
+description: Use when performing git operations - commits, rebasing, cherry-picking, history cleanup, or conflict resolution. Ensures atomic commits, clean history, and consistent commit message style.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Git Master
+
+## Overview
+
+Messy git history obscures intent, makes debugging harder, and wastes reviewer time. Clean history tells the story of WHY changes were made, not just WHAT changed.
+
+**Core principle:** Every commit should be a single, complete, logical change that can be understood, reverted, or cherry-picked independently.
+
+**Violating the letter of this process is violating the spirit of clean version control.**
+
+## The Iron Law
+
+```
+ONE LOGICAL CHANGE PER COMMIT. NO EXCEPTIONS.
+```
+
+If a commit does two things, it should be two commits. If a commit is incomplete, it should not exist yet.
+
+**No exceptions:**
+- "I'll split it later" → Split it now
+- "It's a small extra change" → Separate commit
+- "They're related" → Related is not identical
+
+## When to Use
+
+Use for ANY git operation beyond trivial:
+- Creating commits (single or multiple)
+- Rebasing branches (interactive or standard)
+- Cherry-picking commits across branches
+- Cleaning up history (amend, squash, fixup)
+- Resolving merge conflicts
+- Preparing branches for review
+
+**Use this ESPECIALLY when:**
+- Repository has established commit conventions
+- Branch has messy work-in-progress commits before PR
+- Cherry-picking between release branches
+- Resolving complex merge conflicts
+- History needs cleanup before merging
+
+**Don't skip when:**
+- "It's just a quick fix" (quick fixes deserve clean commits too)
+- "Nobody reads commit history" (future-you does, during `git bisect`)
+- "I'll squash on merge anyway" (squash merges lose valuable context)
+
+## When NOT to Use
+
+- **Initial prototyping** — Experiment freely, clean up before PR
+- **Throwaway branches** — No need for perfect history on disposable work
+- **Automated commits** — CI/CD generated commits follow their own patterns
+
+## The Six Phases
+
+### Phase 1: Style Detection
+
+**BEFORE making any commit, understand the repo's conventions:**
+
+1. **Analyze Recent History**
+   ```bash
+   git log --oneline -20
+   ```
+
+2. **Detect Commit Message Pattern**
+
+   | Pattern | Example | Convention |
+   |---------|---------|------------|
+   | **Conventional Commits** | `feat(auth): add OAuth2 flow` | `type(scope): description` |
+   | **Imperative mood** | `Add user validation` | Verb-first, present tense |
+   | **Ticket prefix** | `[PROJ-123] Fix login bug` | `[TICKET] description` |
+   | **Emoji prefix** | `:bug: Fix null pointer` | Emoji + description |
+   | **Freeform** | `Fixed the login thing` | No consistent pattern |
+
+3. **Match the Detected Style**
+   - Use the same pattern for your commits
+   - If no pattern detected, default to Conventional Commits
+   - Never mix styles within a PR
+
+**Completion criteria:**
+- [ ] `style_detected` — Commit message pattern identified
+- [ ] `convention_noted` — Will follow detected convention
+
+### Phase 2: Atomic Commits
+
+**Every commit must be atomic — one logical change, complete and self-contained.**
+
+1. **Stage Selectively**
+   ```bash
+   # Stage specific files, not everything
+   git add src/auth/login.ts src/auth/login.test.ts
+
+   # For partial file staging
+   git add -p src/utils/helpers.ts
+   ```
+
+   **Never use `git add .` or `git add -A` unless you have verified every change belongs together.**
+
+2. **Verify Staged Content**
+   ```bash
+   git diff --cached    # Review what you're about to commit
+   git diff             # Check what's NOT staged
+   ```
+
+3. **Write the Commit Message**
+
+   **Structure:**
+   ```
+   <type>(<scope>): <what changed> (max 72 chars)
+
+   <why this change was needed>
+   <any important context>
+
+   Refs: #issue-number (if applicable)
+   ```
+
+   **Good vs Bad:**
+
+   | Bad | Good |
+   |-----|------|
+   | `fix stuff` | `fix(auth): prevent session timeout on token refresh` |
+   | `WIP` | `feat(cart): add quantity validation for checkout` |
+   | `updates` | `refactor(api): extract retry logic into shared middleware` |
+   | `fix tests` | `test(auth): cover edge case for expired JWT tokens` |
+
+4. **Verify Atomicity**
+   - Does this commit do exactly ONE thing?
+   - Could someone revert JUST this commit safely?
+   - Does the codebase compile/pass tests at this commit?
+
+**Completion criteria:**
+- [ ] `changes_staged_selectively` — No unrelated changes staged
+- [ ] `message_follows_convention` — Matches repo's detected style
+- [ ] `commit_is_atomic` — Single logical change
+
+### Phase 3: Rebase Workflows
+
+**Use rebase to maintain a clean, linear history.**
+
+1. **Standard Rebase (update branch)**
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   ```
+
+2. **Interactive Rebase (clean up commits)**
+   ```bash
+   git rebase -i HEAD~N    # N = number of commits to review
+   ```
+
+   **Action guide:**
+
+   | Action | When to Use |
+   |--------|-------------|
+   | `pick` | Keep commit as-is |
+   | `reword` | Fix commit message only |
+   | `squash` | Merge into previous, combine messages |
+   | `fixup` | Merge into previous, discard message |
+   | `drop` | Remove commit entirely |
+
+3. **Safe Rebase Checklist**
+   - [ ] Branch is NOT shared with others (or team agrees on force-push)
+   - [ ] All changes are committed (no uncommitted work)
+   - [ ] You understand what each commit does before reordering
+
+   > **AI Agent Note:** Interactive commands (`rebase -i`, `add -p`) require terminal interaction. AI agents without interactive input support should use non-interactive alternatives (e.g., `git rebase --onto`, `git add <specific-files>`) or prepare the rebase todo list programmatically.
+
+4. **If Rebase Goes Wrong**
+   ```bash
+   git rebase --abort          # Cancel in-progress rebase
+   git reflog                  # Find pre-rebase state
+   git reset --hard HEAD@{N}   # Restore (DESTRUCTIVE — uncommitted changes lost)
+   ```
+
+**Completion criteria:**
+- [ ] `history_is_linear` — No unnecessary merge commits
+- [ ] `commits_are_clean` — WIP commits squashed
+
+### Phase 4: Cherry-Pick
+
+**Safely move individual commits between branches.**
+
+1. **Before Cherry-Picking**
+   - Identify the exact commit(s): `git log --oneline source-branch`
+   - Verify the commit is self-contained (atomic)
+   - Check for dependencies on other commits
+
+2. **Execute Cherry-Pick**
+   ```bash
+   git cherry-pick <commit-hash>
+
+   # For multiple commits
+   git cherry-pick <hash1> <hash2> <hash3>
+
+   # For a range
+   git cherry-pick <older-hash>..<newer-hash>
+   ```
+
+3. **Handle Cherry-Pick Conflicts**
+   ```bash
+   # View conflicting files
+   git status
+
+   # Resolve conflicts, then
+   git add <resolved-files>
+   git cherry-pick --continue
+
+   # Or abort if too complex
+   git cherry-pick --abort
+   ```
+
+4. **Verify After Cherry-Pick**
+   - Tests pass on the target branch
+   - No unintended side effects
+   - Commit message still makes sense in new context
+
+**Completion criteria:**
+- [ ] `commit_identified` — Correct commit(s) selected
+- [ ] `conflicts_resolved` — All conflicts handled
+- [ ] `tests_pass` — Target branch is green
+
+### Phase 5: History Cleanup
+
+**Fix mistakes without breaking history for others.**
+
+1. **Amend Last Commit**
+   ```bash
+   # Add forgotten changes
+   git add <forgotten-file>
+   git commit --amend
+
+   # Fix message only
+   git commit --amend -m "corrected message"
+   ```
+   **Only amend unpushed commits.** Amending pushed commits requires force-push.
+
+2. **Fixup Older Commits**
+   ```bash
+   # Create a fixup commit
+   git commit --fixup=<target-hash>
+
+   # Auto-squash during rebase
+   git rebase -i --autosquash HEAD~N
+   ```
+
+3. **Recovery with Reflog**
+   ```bash
+   # View recent HEAD movements
+   git reflog
+
+   # Restore accidentally deleted commit
+   git cherry-pick <reflog-hash>
+
+   # Restore to a previous state (DESTRUCTIVE — all uncommitted changes are lost)
+   git reset --hard HEAD@{N}
+   ```
+
+4. **Safety Rules**
+   - Never rewrite history on shared branches without team agreement
+   - Always verify `git reflog` shows the state you want to restore
+   - Create a backup branch before destructive operations: `git branch backup-before-cleanup`
+
+**Completion criteria:**
+- [ ] `history_corrected` — Mistakes fixed
+- [ ] `no_shared_history_rewritten` — Shared branches untouched
+- [ ] `backup_created` — Safety branch exists for risky operations
+
+### Phase 6: Conflict Resolution
+
+**Resolve merge conflicts systematically, not by guessing.**
+
+1. **Understand the Conflict**
+   ```bash
+   # See which files conflict
+   git status
+
+   # See what both sides changed
+   git diff --merge
+   git log --merge --oneline
+   ```
+
+2. **Resolve Each File**
+   - Read BOTH sides of the conflict markers
+   - Understand WHY each side made their change
+   - Choose the resolution that preserves BOTH intents
+   - If unsure, check the original commits for context
+
+3. **Resolution Strategies**
+
+   | Situation | Strategy |
+   |-----------|----------|
+   | One side is clearly correct | Take that side |
+   | Both changes needed | Combine manually |
+   | Changes are incompatible | Consult the other author |
+   | Complex logic conflict | Write a new implementation that satisfies both |
+
+4. **After Resolving**
+   ```bash
+   git add <resolved-files>
+   git commit    # or git rebase --continue / git merge --continue
+   ```
+
+5. **Verify Resolution**
+   - Run tests — conflicts often introduce subtle bugs
+   - Review the merge commit diff — ensure nothing was lost
+   - Check that both features still work as intended
+
+**Completion criteria:**
+- [ ] `all_conflicts_resolved` — No remaining conflict markers
+- [ ] `both_intents_preserved` — No changes silently dropped
+- [ ] `tests_pass` — Resolution doesn't break anything
+
+## Verification Checklist
+
+Before completing any git operation:
+
+- [ ] Commit message matches repo's detected convention
+- [ ] Each commit contains exactly one logical change
+- [ ] No `git add .` used without reviewing all changes
+- [ ] Shared branch history not rewritten without team agreement
+- [ ] Tests pass at every commit (not just the last one)
+- [ ] No conflict markers left in code (`<<<<<<<`, `=======`, `>>>>>>>`)
+- [ ] Backup branch created before destructive operations
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "I'll clean up the history later" | Later never comes. Clean it now. |
+| "Just one big commit is fine" | Big commits are impossible to review, revert, or bisect. |
+| "Nobody reads commit messages" | `git blame` and `git bisect` users do. Future-you does. |
+| "Force push is fine, I'm the only one on this branch" | Verify first. CI, bots, and reviewers may have fetched. |
+| "The merge conflict is obvious, just take mine" | Obvious conflicts hide subtle logic bugs. Read both sides. |
+| "I'll squash on merge anyway" | Squash loses the story. Clean history beats squashed history. |
+| "Rebase is scary, I'll just merge" | Merge commits obscure linear history. Learn rebase. |
+| "This commit message is good enough" | Future readers have zero context. Be specific. |
+
+**ALL of these mean: STOP. Follow the relevant phase.**
+
+## Related Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `refactoring` | Refactoring produces commits — use git-master for commit hygiene |
+| `test-driven-development` | TDD cycle maps to atomic commits: one test + impl per commit |
+| `pr-all-in-one` | PR preparation requires clean history — git-master feeds into it |
+| `deployment-checklist` | Deploy from clean branches with verified history |
+
+## Related Agents
+
+| Agent | When to Involve |
+|-------|----------------|
+| Code Reviewer | When commit organization affects review quality |
+| DevOps Engineer | When branch strategy impacts CI/CD pipeline |

package/.ai-rules/skills/incident-response/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: incident-response
 description: Use when production incident occurs, alerts fire, service degradation detected, or on-call escalation needed - guides systematic organizational response before technical fixes
+disable-model-invocation: true
 ---
 
 # Incident Response

package/.ai-rules/skills/legacy-modernization/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: legacy-modernization
 description: Use when modernizing legacy code or migrating outdated patterns to current best practices. Covers assessment, strangler fig pattern, incremental migration, and risk management.
+argument-hint: [target-module-or-path]
 ---
 
 # Legacy Modernization

package/.ai-rules/skills/mcp-builder/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: mcp-builder
 description: Use when building or extending MCP (Model Context Protocol) servers. Covers NestJS-based server design, Tools/Resources/Prompts capability design, transport implementation (stdio/SSE), and testing strategies.
+argument-hint: [capability-name]
 ---
 
 # MCP Builder
@@ -354,3 +355,9 @@ Server:
 | No error handling in tools | Always catch and return isError: true |
 | Breaking stdio with console.log | Use stderr for logs: `process.stderr.write(...)` |
 | Hardcoded paths | Use env vars or config injection |
+
+## Additional resources
+
+- [Tool implementation example](examples/tool-example.ts) — Complete MCP Tool handler with schema, validation, and error handling
+- [Resource implementation example](examples/resource-example.ts) — Complete MCP Resource handler with URI routing and templates
+- [MCP protocol quick reference](references/protocol-spec.md) — JSON-RPC message formats, capability methods, transport modes, and error codes