codingbuddy-rules 4.5.0 → 5.0.0

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

package/.ai-rules/skills/mcp-builder/examples/resource-example.ts

@@ -0,0 +1,233 @@
+/**
+ * MCP Resource Implementation Example
+ *
+ * Demonstrates a complete Resource handler following the MCP specification.
+ * Resources are read-only data exposed via URI that the AI can read.
+ *
+ * Key patterns:
+ * - URI-based addressing with scheme://path convention
+ * - Resource templates for dynamic URIs
+ * - List + Read separation
+ * - Proper MIME type handling
+ */
+
+import { Injectable } from '@nestjs/common';
+
+// --- 1. Define Static Resources ---
+
+export const staticResources = [
+  {
+    uri: 'config://project',
+    name: 'Project Configuration',
+    description: 'Current project settings including tech stack, conventions, and build config',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'docs://changelog',
+    name: 'Changelog',
+    description: 'Project changelog with recent changes and version history',
+    mimeType: 'text/markdown',
+  },
+];
+
+// --- 2. Define Resource Templates (Dynamic URIs) ---
+
+export const resourceTemplates = [
+  {
+    uriTemplate: 'rules://{ruleName}',
+    name: 'AI Rule',
+    description: 'Retrieve a specific AI coding rule by name (e.g., "core", "project")',
+    mimeType: 'text/markdown',
+  },
+  {
+    uriTemplate: 'agents://{agentName}',
+    name: 'Agent Definition',
+    description: 'Retrieve a specialist agent definition by name (e.g., "solution-architect")',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'skills://{skillName}',
+    name: 'Skill Content',
+    description: 'Retrieve a skill definition by name (e.g., "mcp-builder", "api-design")',
+    mimeType: 'text/markdown',
+  },
+];
+
+// --- 3. Result Types ---
+
+interface ResourceContent {
+  uri: string;
+  mimeType: string;
+  text: string;
+}
+
+// --- 4. Implement the Resource Handler ---
+
+@Injectable()
+export class ResourceHandler {
+  constructor(
+    private readonly rulesService: RulesService,
+    private readonly agentsService: AgentsService,
+    private readonly configService: ConfigService,
+  ) {}
+
+  /**
+   * List all available resources (static + dynamic discovered).
+   * Called by MCP client via resources/list.
+   */
+  async listResources(): Promise<typeof staticResources> {
+    // Static resources are always available
+    const resources = [...staticResources];
+
+    // Dynamically discover available rules
+    const ruleNames = await this.rulesService.listRuleNames();
+    for (const name of ruleNames) {
+      resources.push({
+        uri: `rules://${name}`,
+        name: `Rule: ${name}`,
+        description: `AI coding rule: ${name}`,
+        mimeType: 'text/markdown',
+      });
+    }
+
+    return resources;
+  }
+
+  /**
+   * Read a specific resource by URI.
+   * Called by MCP client via resources/read.
+   */
+  async readResource(uri: string): Promise<ResourceContent> {
+    // Parse the URI scheme and path
+    const match = uri.match(/^(\w+):\/\/(.+)$/);
+    if (!match) {
+      throw new ResourceNotFoundError(`Invalid resource URI format: ${uri}`);
+    }
+
+    const [, scheme, path] = match;
+
+    switch (scheme) {
+      case 'config':
+        return this.readConfig(uri, path);
+      case 'docs':
+        return this.readDocs(uri, path);
+      case 'rules':
+        return this.readRule(uri, path);
+      case 'agents':
+        return this.readAgent(uri, path);
+      case 'skills':
+        return this.readSkill(uri, path);
+      default:
+        throw new ResourceNotFoundError(`Unknown resource scheme: ${scheme}`);
+    }
+  }
+
+  private async readConfig(uri: string, path: string): Promise<ResourceContent> {
+    if (path !== 'project') {
+      throw new ResourceNotFoundError(`Unknown config resource: ${path}`);
+    }
+
+    const config = await this.configService.getProjectConfig();
+    return {
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify(config, null, 2),
+    };
+  }
+
+  private async readDocs(uri: string, path: string): Promise<ResourceContent> {
+    if (path !== 'changelog') {
+      throw new ResourceNotFoundError(`Unknown docs resource: ${path}`);
+    }
+
+    const changelog = await this.rulesService.readFile('CHANGELOG.md');
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: changelog,
+    };
+  }
+
+  private async readRule(uri: string, ruleName: string): Promise<ResourceContent> {
+    const content = await this.rulesService.getRule(ruleName);
+    if (!content) {
+      throw new ResourceNotFoundError(`Rule not found: ${ruleName}`);
+    }
+
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: content,
+    };
+  }
+
+  private async readAgent(uri: string, agentName: string): Promise<ResourceContent> {
+    const agent = await this.agentsService.getAgent(agentName);
+    if (!agent) {
+      throw new ResourceNotFoundError(`Agent not found: ${agentName}`);
+    }
+
+    return {
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify(agent, null, 2),
+    };
+  }
+
+  private async readSkill(uri: string, skillName: string): Promise<ResourceContent> {
+    const content = await this.rulesService.getSkill(skillName);
+    if (!content) {
+      throw new ResourceNotFoundError(`Skill not found: ${skillName}`);
+    }
+
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: content,
+    };
+  }
+}
+
+// --- 5. Register in MCP Service ---
+
+/*
+// In mcp.service.ts:
+import { staticResources, resourceTemplates, ResourceHandler } from './resources/resource-handler';
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: await this.resourceHandler.listResources(),
+}));
+
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+  resourceTemplates,
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => ({
+  contents: [await this.resourceHandler.readResource(request.params.uri)],
+}));
+*/
+
+// --- Error Types ---
+
+class ResourceNotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ResourceNotFoundError';
+  }
+}
+
+// Placeholder interfaces for dependency injection
+interface RulesService {
+  listRuleNames(): Promise<string[]>;
+  getRule(name: string): Promise<string | null>;
+  getSkill(name: string): Promise<string | null>;
+  readFile(path: string): Promise<string>;
+}
+
+interface AgentsService {
+  getAgent(name: string): Promise<Record<string, unknown> | null>;
+}
+
+interface ConfigService {
+  getProjectConfig(): Promise<Record<string, unknown>>;
+}