codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/cross-repo-issues/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: cross-repo-issues
+description: Use when a bug or feature request belongs in an upstream, parent, or dependency repository rather than the current one. Guides detection, mapping, and safe cross-repo issue creation with user confirmation.
+---
+
+# Cross-Repo Issue Creation
+
+## Overview
+
+Not every issue belongs in the repository where it was discovered. Bugs in forked code belong upstream. Problems in a monorepo dependency belong in that dependency's repo. Filing issues in the wrong place wastes maintainer time and delays fixes.
+
+**Core principle:** ALWAYS confirm the target repository with the user before creating an issue elsewhere. Never auto-create issues in repositories you don't own.
+
+**Iron Law:**
+
+```
+NO CROSS-REPO ISSUE CREATION WITHOUT EXPLICIT USER CONFIRMATION
+```
+
+## When to Use
+
+- Bug discovered in forked code that should be reported upstream
+- Issue in a monorepo sub-package that belongs in the package's source repo
+- Bug in a third-party dependency that should be filed in the library's repo
+- Feature request that affects an upstream project
+- Security vulnerability that needs to be reported to the upstream maintainer
+
+**Use this ESPECIALLY when:**
+- Working in a fork and the bug exists in the original repo
+- A monorepo package wraps an external library and the bug is in the library
+- You need to coordinate fixes across multiple repositories
+
+## When NOT to Use
+
+- Issue is local to the current repository (use normal issue workflow)
+- You don't have access to the target repository
+- The upstream project is archived or unmaintained
+- Simple configuration issues that are project-specific
+
+## Configuration
+
+Add `upstreamRepos` to your `codingbuddy.config.json`:
+
+```json
+{
+  "upstreamRepos": {
+    ".": "original-owner/original-repo",
+    "packages/ui": "design-system/ui-kit",
+    "dep:react": "facebook/react"
+  }
+}
+```
+
+### Key Conventions
+
+| Key Pattern | Meaning | Example |
+|-------------|---------|---------|
+| `"."` | Current repo is a fork of this upstream | `"original-owner/repo"` |
+| `"packages/..."` | Monorepo package maps to external repo | `"org/package-repo"` |
+| `"dep:<name>"` | npm/pip dependency maps to its source repo | `"facebook/react"` |
+
+### Minimal Configuration
+
+For a simple fork, only one entry is needed:
+
+```json
+{
+  "upstreamRepos": {
+    ".": "upstream-owner/upstream-repo"
+  }
+}
+```
+
+## The Three Phases
+
+### Phase 1: Detect — Identify Where the Issue Belongs
+
+**Determine if the issue should go to another repository:**
+
+1. **Check the code origin**
+   - Is the buggy code from an upstream repo? (`git log --follow <file>`)
+   - Is it in a vendored or forked dependency?
+   - Does `git remote -v` show an upstream remote?
+
+2. **Check the config mapping**
+   - Read `upstreamRepos` from `codingbuddy.config.json`
+   - Match the affected file path or package name to a mapping key
+   - If no mapping exists, ask the user for the target repo
+
+3. **Verify the issue doesn't already exist upstream**
+   - Search upstream issues: `gh issue list -R <upstream> --search "<keywords>"`
+   - Check for duplicates before creating
+
+**Decision matrix:**
+
+| Scenario | Target Repo | Key |
+|----------|-------------|-----|
+| Bug in forked code | Upstream repo | `"."` |
+| Bug in monorepo sub-package's upstream | Package source repo | `"packages/<name>"` |
+| Bug in third-party dependency | Library repo | `"dep:<package>"` |
+| Bug in your own code | Current repo (stop here) | N/A |
+
+**Completion criteria:**
+- [ ] Target repository identified
+- [ ] Duplicate check completed
+- [ ] Issue is confirmed to belong upstream
+
+### Phase 2: Confirm — Get User Approval
+
+**MANDATORY: Never skip this phase.**
+
+Present the following to the user before proceeding:
+
+```
+Cross-Repo Issue Detected:
+  Source:  <current-repo> (<file-or-package>)
+  Target:  <upstream-repo>
+  Reason:  <why this belongs upstream>
+  Title:   <proposed issue title>
+
+Proceed with creating issue in <upstream-repo>? (y/n)
+```
+
+**Include in the confirmation:**
+- The exact target repository (`owner/repo`)
+- Why the issue belongs there (not here)
+- Proposed issue title and summary
+- Whether user has write access to the target repo
+
+**If user declines:**
+- Offer to create the issue in the current repo instead
+- Add a label like `upstream` or `external-dependency` for tracking
+
+**Completion criteria:**
+- [ ] User explicitly confirmed target repo
+- [ ] User approved issue title and content
+
+### Phase 3: Create — File the Issue
+
+**Create the issue in the confirmed target repository:**
+
+1. **Format the issue body**
+
+```markdown
+## Description
+
+<Clear description of the issue>
+
+## Reproduction
+
+- Repository: <your-repo> (discovered while working on <context>)
+- File/Package: <affected file or package>
+- Steps to reproduce: <steps>
+
+## Expected Behavior
+
+<what should happen>
+
+## Actual Behavior
+
+<what actually happens>
+
+## Environment
+
+- Version: <upstream version in use>
+- OS: <if relevant>
+
+## Additional Context
+
+Discovered in downstream repo: <your-repo-url>
+```
+
+1. **Create the issue**
+
+```bash
+gh issue create -R <owner/repo> \
+  --title "<title>" \
+  --body "<body>"
+```
+
+1. **Link back to current repo (optional)**
+   - Create a tracking issue in current repo referencing the upstream issue
+   - Add label: `blocked-upstream` or `waiting-upstream`
+
+```bash
+gh issue create \
+  --title "Tracking: <upstream-owner/repo>#<number>" \
+  --body "Upstream issue: <url>\nBlocked until upstream fix is available." \
+  --label "blocked-upstream"
+```
+
+**Completion criteria:**
+- [ ] Issue created in target repository
+- [ ] Issue URL shared with user
+- [ ] (Optional) Tracking issue created in current repo
+
+## Quick Reference
+
+| Phase | Action | Verification |
+|-------|--------|-------------|
+| **1. Detect** | Identify target repo from config or code origin | Target repo confirmed |
+| **2. Confirm** | Present plan to user, get explicit approval | User said yes |
+| **3. Create** | File issue via `gh`, link back if needed | Issue URL available |
+
+## Safety Checklist
+
+Before creating any cross-repo issue:
+
+- [ ] Target repo is correct (double-check `owner/repo`)
+- [ ] Issue doesn't already exist upstream (searched)
+- [ ] User explicitly approved the creation
+- [ ] Issue body is professional and includes reproduction steps
+- [ ] No sensitive/proprietary information in the issue body
+- [ ] You have access to create issues in the target repo
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "I'll just create it, the user won't mind" | STOP. Always confirm. Cross-repo actions are visible to external maintainers. |
+| "It's obviously an upstream bug" | Maybe. But confirm the target repo with the user first. |
+| "I'll skip the duplicate check" | Duplicate issues waste maintainer time and hurt your credibility. |
+| "The config mapping is enough confirmation" | Config maps repos, but the user must confirm each issue creation. |
+| "I'll include our internal details for context" | STOP. Review for sensitive information before posting to external repos. |
+| "No config? I'll guess the upstream repo" | Ask the user. Wrong repo = noise for unrelated maintainers. |
+
+## Examples
+
+### Fork → Upstream
+
+```
+Config: { "upstreamRepos": { ".": "expressjs/express" } }
+
+Detected: Bug in request parsing (inherited from upstream)
+Target:   expressjs/express
+Action:   Confirm with user → Create issue in expressjs/express
+```
+
+### Monorepo Package → Source Repo
+
+```
+Config: { "upstreamRepos": { "packages/icons": "design-org/icon-library" } }
+
+Detected: Missing icon in packages/icons (sourced from design-org/icon-library)
+Target:   design-org/icon-library
+Action:   Confirm with user → Create issue in design-org/icon-library
+```
+
+### Dependency → Library Repo
+
+```
+Config: { "upstreamRepos": { "dep:zod": "colinhacks/zod" } }
+
+Detected: Validation bug in zod usage
+Target:   colinhacks/zod
+Action:   Confirm with user → Search existing issues → Create if new
+```

package/.ai-rules/skills/database-migration/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: database-migration
 description: Use when performing database schema changes, data migrations, large table modifications, or when zero-downtime deployment is required - guides systematic, reversible database changes with rollback planning
+disable-model-invocation: true
 ---
 
 # Database Migration

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