codingbuddy-rules 4.5.0 → 5.0.0

package/.ai-rules/skills/deepsearch/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: deepsearch
+description: Use when simple grep/glob is insufficient and you need comprehensive, multi-pass codebase understanding
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Deep Search
+
+## Overview
+
+Single-pass searches miss connections. Grep finds strings, not understanding.
+
+**Core principle:** ALWAYS search in multiple passes with increasing precision. A single query never gives the full picture.
+
+**Violating the letter of this process is violating the spirit of thorough search.**
+
+## The Iron Law
+
+```
+NO CONCLUSIONS WITHOUT CROSS-REFERENCED EVIDENCE FROM MULTIPLE PASSES
+```
+
+If you haven't completed at least Phases 1-3, your understanding is incomplete.
+
+## When to Use
+
+Use when simple grep/glob is **insufficient**:
+- Understanding how a feature works end-to-end
+- Tracing data flow across multiple files/modules
+- Finding all usages and side effects before refactoring
+- Detecting dead code or unused exports
+- Mapping dependency chains
+- Understanding implicit relationships (event emitters, dynamic imports, reflection)
+- Auditing a pattern's usage across the codebase
+
+**Use this ESPECIALLY when:**
+- Initial search returns too many or too few results
+- You need to understand "everything that touches X"
+- The codebase uses indirection (dependency injection, plugins, event systems)
+- You're about to make a breaking change
+- You need confidence that nothing was missed
+
+**Don't use when:**
+- You know the exact file and symbol (use direct read)
+- A single grep gives you the complete answer
+- You're looking up a specific API signature
+
+## The Four Phases
+
+You MUST complete each phase before drawing conclusions.
+
+### Phase 1: Broad Search — Cast a Wide Net
+
+**Goal:** Discover all potentially relevant files and symbols.
+
+1. **Start with Multiple Search Strategies**
+   - Search by name: function names, class names, variable names
+   - Search by pattern: string literals, error messages, log statements
+   - Search by structure: file naming conventions, directory patterns
+   - Search by type: imports, exports, type definitions
+
+2. **Use Varied Query Terms**
+   - Don't stop at the first query term
+   - Try synonyms, abbreviations, related concepts
+   - Search for both the interface and the implementation
+   - Include test files — they reveal intended usage
+
+3. **Record Everything**
+   - Note every file that appears relevant
+   - Note unexpected hits — they often reveal hidden connections
+   - Note files that *should* have matched but didn't
+
+**Output:** A list of all candidate files and symbols to investigate.
+
+### Phase 2: Narrow Focus — Understand Each Hit
+
+**Goal:** Read and understand each candidate in context.
+
+1. **Classify Each Result**
+   - Definition vs. usage vs. re-export
+   - Direct dependency vs. indirect dependency
+   - Active code vs. dead code vs. test code
+
+2. **Read Surrounding Context**
+   - Don't just read the matching line — read the function/class
+   - Check imports at the top of the file
+   - Check exports at the bottom
+   - Read adjacent functions for related logic
+
+3. **Build a Symbol Map**
+   - Where is it defined?
+   - Where is it imported?
+   - Where is it called/used?
+   - What calls it? (reverse dependency)
+
+4. **Identify Indirection**
+   - Dynamic imports (`import()`, `require()`)
+   - String-based lookups (registries, plugin systems)
+   - Event-driven connections (emit/on patterns)
+   - Dependency injection (constructor injection, providers)
+   - Configuration-driven behavior (feature flags, env vars)
+
+### Phase 3: Cross-Reference — Connect the Dots
+
+**Goal:** Map relationships between all discovered symbols and files.
+
+1. **Trace Data Flow**
+   - Follow data from source to sink
+   - Input → transform → output for each function in the chain
+   - Note where data shape changes (serialization, mapping)
+
+2. **Trace Control Flow**
+   - What triggers this code path?
+   - What conditions must be true?
+   - What error paths exist?
+   - What happens on failure?
+
+3. **Identify Dependency Chains**
+   - A imports B imports C — trace the full chain
+   - Circular dependencies — note them explicitly
+   - Shared dependencies — what else depends on the same module?
+
+4. **Check for Side Effects**
+   - Global state mutations
+   - File system operations
+   - Database writes
+   - External API calls
+   - Cache invalidation
+
+5. **Verify Completeness**
+   - For every "used by" reference, verify the reverse "depends on"
+   - Look for orphaned code that nothing references
+   - Check for dynamic/runtime references that static search misses
+
+### Phase 4: Validate — Confirm Your Understanding
+
+**Goal:** Prove your mental model is correct.
+
+1. **Test Your Hypothesis**
+   - "If I change X, these files should be affected: [list]"
+   - "This function is called in these scenarios: [list]"
+   - "This code path is triggered by: [list]"
+   - Verify each claim with evidence from the code
+
+2. **Check for Gaps**
+   - Are there files you expected to find but didn't?
+   - Are there connections that seem missing?
+   - Does the architecture diagram match the actual code?
+
+3. **Look for Dead Code**
+   - Exported but never imported
+   - Defined but never called
+   - Imported but never used
+   - Behind feature flags that are always off
+
+4. **Verify with Tests**
+   - Do existing tests confirm your understanding?
+   - Do test descriptions match your mental model?
+   - Are there test cases for edge cases you identified?
+
+5. **Summarize Findings**
+   - List all files involved and their roles
+   - Draw the dependency graph (text or description)
+   - Note any risks, dead code, or inconsistencies found
+   - Provide confidence level: high / medium / low
+
+## Red Flags — STOP and Search Deeper
+
+If you catch yourself thinking:
+- "This is probably the only place it's used"
+- "I found one result, that must be it"
+- "The naming convention tells me everything"
+- "I don't need to check test files"
+- "Dynamic imports won't matter here"
+- "This module is self-contained"
+- "I can skip Phase 3, the connections are obvious"
+
+**ALL of these mean: STOP. You're making assumptions. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Grep found it, I'm done" | Grep finds strings, not relationships. Continue to Phase 2. |
+| "Only one file imports this" | Check for dynamic imports, re-exports, and test files. |
+| "The naming is clear enough" | Names lie. Read the implementation. |
+| "Tests aren't relevant" | Tests reveal intended behavior and edge cases. Always check. |
+| "This is a small codebase" | Small codebases have hidden complexity too. Follow the process. |
+| "I'll trace the rest later" | Incomplete understanding leads to broken refactors. Trace now. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Broad Search** | Multiple strategies, varied terms, record all | Complete candidate list |
+| **2. Narrow Focus** | Classify, read context, build symbol map | Understand each hit |
+| **3. Cross-Reference** | Trace data/control flow, find dependencies | Map all relationships |
+| **4. Validate** | Test hypothesis, check gaps, verify with tests | Confirmed mental model |
+
+## Search Strategy Checklist
+
+Use this checklist to ensure thorough coverage:
+
+- [ ] Searched by symbol name (exact and substring)
+- [ ] Searched by string literals and error messages
+- [ ] Searched by file/directory naming patterns
+- [ ] Checked imports and exports
+- [ ] Checked test files for usage examples
+- [ ] Checked configuration files
+- [ ] Traced dynamic/runtime references
+- [ ] Verified reverse dependencies
+- [ ] Looked for event-driven connections
+- [ ] Checked for dead/unused code

package/.ai-rules/skills/deployment-checklist/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: deployment-checklist
 description: Use before deploying to staging or production. Covers pre-deploy validation, environment verification, rollback planning, health checks, and post-deploy monitoring.
+disable-model-invocation: true
 ---
 
 # Deployment Checklist

package/.ai-rules/skills/error-analysis/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: error-analysis
 description: Use when encountering error messages, stack traces, or unexpected application behavior. Provides structured analysis to understand root cause before attempting any fix.
+allowed-tools: Read, Grep, Glob, Bash(git:*)
 ---
 
 # Error Analysis

package/.ai-rules/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete and you need to decide how to integrate the work - merge, PR, or cleanup
+disable-model-invocation: true
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide the completion of development work on a branch — decide how to integrate, verify readiness, execute the choice, and clean up.
+
+**Core principle:** Verify before you ship. Present options, don't assume. Clean up after yourself.
+
+## The Iron Law
+
+```
+NO MERGE WITHOUT GREEN TESTS AND CLEAN STATUS
+```
+
+If tests fail or uncommitted changes exist, STOP. Fix first. No exceptions.
+
+**Corollary:** Never push directly to main/master. Always use a PR for protected branches.
+
+## When to Use
+
+- Implementation is complete on a feature branch
+- All planned tasks are done (or intentionally deferred)
+- Ready to integrate work back to base branch
+- Need to decide: merge, PR, or abandon
+- End of an executing-plans or subagent-driven-development session
+- Wrapping up work in a git worktree
+
+## When NOT to Use
+
+- Work is still in progress (keep working)
+- You haven't run tests yet (run them first)
+- You're on the main/master branch (nothing to finish)
+
+## Phase 1: Pre-Completion Checklist
+
+**MANDATORY. Complete every item before proceeding.**
+
+### Must Pass (blocking)
+
+```bash
+# 1. All tests pass
+npm test                    # or: yarn test, pytest, go test ./...
+
+# 2. No type errors
+npx tsc --noEmit            # or equivalent for your language
+
+# 3. No uncommitted changes
+git status                  # must be clean
+
+# 4. Branch is up to date with base
+git fetch origin
+git merge-base --is-ancestor origin/<base> HEAD  # exit 0 = up to date
+```
+
+- [ ] All tests pass (zero failures)
+- [ ] No type errors (`tsc --noEmit` or equivalent)
+- [ ] Working directory clean (`git status` shows nothing)
+- [ ] No untracked files that should be committed
+- [ ] Branch is up to date with base branch
+
+### Should Check (non-blocking)
+
+- [ ] Linting passes (eslint/prettier or equivalent)
+- [ ] No TODO/FIXME left in new code
+- [ ] Commits are logically grouped (not a mess of WIP)
+- [ ] Commit messages follow project conventions
+
+### Context-Dependent
+
+- [ ] If in worktree: confirmed correct worktree
+- [ ] If linked to issue: issue number in branch name or commits
+- [ ] If PR already exists: PR is up to date with latest commits
+
+**Any blocking item fails? STOP. Fix it. Re-run the checklist.**
+
+## Phase 2: Decision Tree
+
+```dot
+digraph decision {
+    rankdir=TB;
+    node [shape=diamond, style=filled, fillcolor="#ffffcc"];
+
+    start [label="Pre-completion\nchecklist passed?", shape=diamond];
+    keep [label="Work worth\nkeeping?"];
+    protected [label="Target branch\nprotected?"];
+    review [label="Changes need\nreview?"];
+    simple [label="Single commit,\npersonal branch?"];
+
+    stop [label="STOP\nFix issues first", fillcolor="#ffcccc", shape=box];
+    abandon [label="PATH C\nCleanup / Abandon", fillcolor="#ffcccc", shape=box];
+    pr [label="PATH B\nCreate PR", fillcolor="#ccffcc", shape=box];
+    merge [label="PATH A\nMerge Directly", fillcolor="#ccccff", shape=box];
+
+    start -> keep [label="yes"];
+    start -> stop [label="no"];
+    keep -> abandon [label="no"];
+    keep -> protected [label="yes"];
+    protected -> pr [label="yes"];
+    protected -> review [label="no"];
+    review -> pr [label="yes"];
+    review -> simple [label="no"];
+    simple -> merge [label="yes"];
+    simple -> pr [label="no"];
+}
+```
+
+### Quick Reference
+
+| Condition | Path |
+|-----------|------|
+| Checklist fails | **STOP** — fix first |
+| Work not worth keeping | **PATH C** — Cleanup/Abandon |
+| Target branch is protected | **PATH B** — Create PR |
+| Changes need review | **PATH B** — Create PR |
+| Simple change, personal branch | **PATH A** — Merge Directly |
+| Unsure which path | **PATH B** — Create PR (safe default) |
+
+## Phase 3: Execute Choice
+
+### PATH A: Merge Directly
+
+For simple, single-commit changes on unprotected personal branches.
+
+```bash
+# 1. Update base branch
+git checkout <base>
+git pull origin <base>
+
+# 2. Merge feature branch
+git merge <feature-branch>
+
+# 3. Push
+git push origin <base>
+```
+
+**WARNING:** Never use PATH A if `<base>` is main/master or any protected branch. Use PATH B instead.
+
+**When to use:** Solo work, unprotected branch, trivial change, no review needed.
+
+**If merge conflicts arise:** Resolve conflicts, run tests again, then commit. If conflicts are complex, abort with `git merge --abort` and switch to PATH B.
+
+### PATH B: Create PR (Recommended Default)
+
+The safe default for most workflows. Use the `pr-all-in-one` skill if available.
+
+```bash
+# 1. Push feature branch
+git push -u origin <feature-branch>
+
+# 2. Create PR (adjust title and body as needed)
+gh pr create \
+  --title "feat: description of change" \
+  --body "## Summary
+- What changed and why
+
+## Test plan
+- [ ] Tests pass
+- [ ] Manual verification done
+
+Closes #<issue-number>"
+```
+
+**Squash before PR (if commits are messy):**
+```bash
+# Clean up commits (use interactive rebase for manual control,
+# or --autosquash for automated fixup commits)
+git rebase -i origin/<base>
+# Then force-push (ALWAYS use --force-with-lease, NEVER --force)
+git push --force-with-lease
+```
+
+**When to use:** Team projects, protected branches, changes needing review, anything non-trivial.
+
+### PATH C: Cleanup / Abandon
+
+For experimental, superseded, or failed work.
+
+**Before abandoning, check for salvageable work:**
+```bash
+# Review what would be lost
+git log origin/<base>..HEAD --oneline
+git diff origin/<base>..HEAD --stat
+
+# Cherry-pick specific commits if needed
+git checkout <base>
+git cherry-pick <commit-hash>
+```
+
+Then proceed to Phase 4 cleanup.
+
+## Phase 4: Post-Completion Cleanup
+
+### After Merge or PR Creation
+
+```bash
+# 1. Switch to base branch
+git checkout <base>
+git pull origin <base>
+
+# 2. Delete local branch (-d is safe; use -D only if unmerged and intentional)
+git branch -d <feature-branch>
+
+# 3. Delete remote branch (if merged or abandoned)
+git push origin --delete <feature-branch>
+```
+
+### If in a Git Worktree
+
+**IMPORTANT: Remove worktree BEFORE deleting the branch.**
+
+```bash
+# 1. Leave the worktree directory
+cd <main-repo-path>
+
+# 2. Remove the worktree
+git worktree remove <worktree-path>
+
+# 3. Prune stale worktree references
+git worktree prune
+
+# 4. NOW delete the branch (-d is safe; use -D only if unmerged and intentional)
+git branch -d <feature-branch>
+```
+
+**Why this order matters:** You cannot delete a branch that is checked out in a worktree. Attempting to do so will fail. Always remove the worktree first.
+
+### Verification
+
+```bash
+# Confirm cleanup
+git branch                    # feature branch should be gone
+git branch -r                 # remote branch should be gone
+git worktree list             # no stale worktrees
+```
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests mostly pass" | Mostly ≠ all. Fix the failures. |
+| "I'll clean up commits later" | Later never comes. Squash now. |
+| "Direct push is faster" | Fast now, broken later. Use a PR. |
+| "It's just a small change" | Small changes break things too. Follow the checklist. |
+| "I'll delete the branch later" | Stale branches accumulate. Clean up now. |
+| "The worktree is fine to leave" | Orphaned worktrees waste disk and cause confusion. Remove it. |
+| "Force push is fine here" | Use `--force-with-lease`. Always. No exceptions. |
+| "No one reviews my PRs anyway" | The PR is the review record. Create it anyway. |
+| "I'll rebase after merge" | Rebase before. Conflicts after merge are worse. |
+
+## Red Flags — STOP
+
+- Tests failing or skipped
+- Uncommitted changes in working directory
+- Pushing directly to main/master
+- Using `git push --force` (use `--force-with-lease`)
+- Deleting a branch before removing its worktree
+- Merging without updating base branch first
+- Skipping the pre-completion checklist
+- "Just this once" thinking
+
+**Any red flag means: STOP. Go back to Phase 1.**
+
+## Verification Checklist
+
+Before marking branch work as complete:
+
+- [ ] Pre-completion checklist passed (Phase 1)
+- [ ] Decision made and executed (Phase 2 + 3)
+- [ ] Local branch deleted
+- [ ] Remote branch deleted (if applicable)
+- [ ] Worktree removed (if applicable)
+- [ ] On base branch with latest changes
+- [ ] No stale worktree references
+
+Can't check all boxes? You're not done yet.

package/.ai-rules/skills/frontend-design/SKILL.md

@@ -40,3 +40,8 @@ Interpret creatively and make unexpected choices that feel genuinely designed fo
 **IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
 
 Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+## Additional resources
+
+- [CSS design patterns](references/css-patterns.md) — Typography systems, color tokens, layout patterns, animations, and texture techniques
+- [Component template](examples/component-template.tsx) — Production-grade React component with staggered animations, CSS variables, and accessibility