codingbuddy-rules 4.4.0 → 5.0.0

package/.ai-rules/skills/api-design/examples/openapi-template.yaml

@@ -0,0 +1,393 @@
+# OpenAPI 3.1 Template
+# Copy and adapt this template when creating new API specifications.
+# Replace all placeholder values (marked with <angle-brackets>).
+
+openapi: 3.1.0
+info:
+  title: <Service Name> API
+  version: 1.0.0
+  description: |
+    <Brief description of what this API does and who it serves.>
+  contact:
+    name: <Team Name>
+    email: <team@example.com>
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://api-staging.example.com/v1
+    description: Staging
+
+# ──────────────────────────────────────────
+# Paths
+# ──────────────────────────────────────────
+
+paths:
+  /items:
+    get:
+      summary: List items
+      operationId: listItems
+      tags: [Items]
+      parameters:
+        - $ref: '#/components/parameters/PageParam'
+        - $ref: '#/components/parameters/PageSizeParam'
+        - name: status
+          in: query
+          description: Filter by item status
+          schema:
+            type: string
+            enum: [active, archived, draft]
+        - name: search
+          in: query
+          description: Full-text search across name and description
+          schema:
+            type: string
+            maxLength: 200
+      responses:
+        '200':
+          description: Paginated list of items
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    post:
+      summary: Create an item
+      operationId: createItem
+      tags: [Items]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateItemRequest'
+      responses:
+        '201':
+          description: Item created
+          headers:
+            Location:
+              description: URL of the newly created item
+              schema:
+                type: string
+                format: uri
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /items/{itemId}:
+    parameters:
+      - name: itemId
+        in: path
+        required: true
+        description: Unique item identifier
+        schema:
+          type: string
+          format: uuid
+
+    get:
+      summary: Get an item by ID
+      operationId: getItem
+      tags: [Items]
+      responses:
+        '200':
+          description: Item details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    patch:
+      summary: Update an item
+      operationId: updateItem
+      tags: [Items]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateItemRequest'
+      responses:
+        '200':
+          description: Item updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ItemResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+    delete:
+      summary: Delete an item
+      operationId: deleteItem
+      tags: [Items]
+      responses:
+        '204':
+          description: Item deleted
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+# ──────────────────────────────────────────
+# Components
+# ──────────────────────────────────────────
+
+components:
+  # --- Schemas ---
+
+  schemas:
+    Item:
+      type: object
+      required: [id, name, status, createdAt, updatedAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier
+          examples: ['550e8400-e29b-41d4-a716-446655440000']
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: Display name
+        description:
+          type: string
+          maxLength: 2000
+          description: Detailed description
+        status:
+          type: string
+          enum: [active, archived, draft]
+          description: Current item status
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    CreateItemRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        description:
+          type: string
+          maxLength: 2000
+        status:
+          type: string
+          enum: [active, draft]
+          default: draft
+
+    UpdateItemRequest:
+      type: object
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        description:
+          type: string
+          maxLength: 2000
+        status:
+          type: string
+          enum: [active, archived, draft]
+
+    ItemResponse:
+      type: object
+      required: [data, meta]
+      properties:
+        data:
+          $ref: '#/components/schemas/Item'
+        meta:
+          $ref: '#/components/schemas/ResponseMeta'
+
+    ItemListResponse:
+      type: object
+      required: [data, meta]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Item'
+        meta:
+          allOf:
+            - $ref: '#/components/schemas/ResponseMeta'
+            - $ref: '#/components/schemas/PaginationMeta'
+
+    # --- Shared Schemas ---
+
+    ResponseMeta:
+      type: object
+      required: [requestId, timestamp]
+      properties:
+        requestId:
+          type: string
+          format: uuid
+          description: Unique request trace ID
+        timestamp:
+          type: string
+          format: date-time
+
+    PaginationMeta:
+      type: object
+      required: [total, page, pageSize, hasNext]
+      properties:
+        total:
+          type: integer
+          minimum: 0
+        page:
+          type: integer
+          minimum: 1
+        pageSize:
+          type: integer
+          minimum: 1
+          maximum: 100
+        hasNext:
+          type: boolean
+
+    ErrorResponse:
+      type: object
+      required: [error, meta]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+              description: Machine-readable error code
+              examples: ['VALIDATION_ERROR']
+            message:
+              type: string
+              description: Human-readable error message
+            details:
+              type: array
+              items:
+                type: object
+                required: [message]
+                properties:
+                  field:
+                    type: string
+                  message:
+                    type: string
+                  code:
+                    type: string
+        meta:
+          $ref: '#/components/schemas/ResponseMeta'
+
+  # --- Parameters ---
+
+  parameters:
+    PageParam:
+      name: page
+      in: query
+      description: Page number (1-indexed)
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+
+    PageSizeParam:
+      name: pageSize
+      in: query
+      description: Items per page
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 20
+
+  # --- Responses ---
+
+  responses:
+    ValidationError:
+      description: Input validation failed
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: VALIDATION_ERROR
+              message: Invalid input data
+              details:
+                - field: name
+                  message: Name is required
+                  code: REQUIRED
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: NOT_FOUND
+              message: The requested resource was not found
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: UNAUTHORIZED
+              message: Authentication is required
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+    Conflict:
+      description: State conflict (duplicate or version mismatch)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error:
+              code: CONFLICT
+              message: An item with this name already exists
+            meta:
+              requestId: '550e8400-e29b-41d4-a716-446655440000'
+              timestamp: '2024-01-15T10:30:00Z'
+
+  # --- Security ---
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []
+
+tags:
+  - name: Items
+    description: Item management endpoints

package/.ai-rules/skills/build-fix/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: build-fix
+description: Use when build fails, TypeScript errors appear, or compilation breaks. Minimal diff fixes only — no refactoring, no architecture changes.
+user-invocable: true
+allowed-tools: Read, Edit, Grep, Glob, Bash
+---
+
+# Build Fix
+
+## Overview
+
+Build errors block everything. Fix them fast, fix them small, fix nothing else.
+
+**Core principle:** Fix ONLY what is broken. A build fix is not an opportunity to refactor, add features, or improve architecture. Touch the minimum lines required to restore a passing build.
+
+**Violating the letter of this process is violating the spirit of build fixing.**
+
+## The Iron Law
+
+```
+MINIMAL DIFF, NO ARCHITECTURE CHANGES — FIX WHAT'S BROKEN, NOTHING MORE
+```
+
+If your diff touches lines unrelated to the error, you are not build-fixing. You are refactoring. Stop.
+
+**No exceptions:**
+- "While I'm here, I'll clean up..." → No. Separate PR.
+- "This would be better as..." → No. Separate issue.
+- "The real problem is the architecture..." → No. File an issue, fix the build now.
+
+## When to Use
+
+Use for ANY build/compilation failure:
+- TypeScript compiler errors (`tsc --noEmit` failures)
+- Import/export resolution errors
+- Dependency version mismatches or missing packages
+- Configuration errors (tsconfig, webpack, vite, etc.)
+- CI/CD build pipeline failures
+- Module not found errors
+
+**Use this ESPECIALLY when:**
+- Build is red and blocking the team
+- CI pipeline is failing on compilation
+- Dependency update broke the build
+- Merge conflict left broken imports
+
+**Do NOT use when:**
+- Tests fail but build succeeds → use `systematic-debugging`
+- You want to improve code quality → use `refactoring`
+- You want to add features → use `brainstorming` + TDD
+- Runtime errors, not compile-time → use `error-analysis`
+
+## Error Classification
+
+First, classify the build error:
+
+| Class | Symptoms | Typical Minimal Fix |
+|-------|----------|-------------------|
+| **TypeScript Error** | `TS2345`, `TS2339`, `TS7006`, `TS2532` | Add type annotation, null check, or correct type |
+| **Import Error** | `Cannot find module`, `has no exported member` | Fix path, add missing export, correct import name |
+| **Dependency Error** | Version mismatch, missing peer dep, lockfile conflict | Align version, install missing package |
+| **Config Error** | `tsconfig.json` invalid, env var missing, wrong target | Fix config value, add missing variable |
+| **Syntax Error** | Unexpected token, missing bracket | Fix syntax at reported location |
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Read the Error
+
+**BEFORE attempting ANY fix:**
+
+1. **Read the FULL error output**
+   - Don't skim — read every line
+   - Note the error code (e.g., `TS2345`)
+   - Note the exact file and line number
+   - Note what the compiler expected vs. what it got
+
+2. **Classify the error** (see table above)
+   - What class does this error belong to?
+   - Is it a single error or a cascade?
+   - Cascading errors: fix the FIRST error only, then re-run
+
+3. **Count the errors**
+   - One error? Fix it directly.
+   - Many errors, same root cause? Fix the root, not each symptom.
+   - Many unrelated errors? Fix one at a time, verify after each.
+
+### Phase 2: Identify Root Cause
+
+**Find the MINIMUM change needed:**
+
+1. **Check recent changes**
+   ```bash
+   git diff HEAD~1        # What changed?
+   git log --oneline -5   # Recent commits
+   ```
+
+2. **Trace the error to its source**
+   - TypeScript error at line 42? Read line 42.
+   - Import error? Check if the export exists at the source.
+   - Dependency error? Check `package.json` versions.
+
+3. **Identify the scope**
+   - How many files need to change?
+   - If more than 3 files → question whether this is truly a build fix
+   - If it requires new files → this is not a build fix, it's a feature
+
+### Phase 3: Minimal Fix
+
+**Apply the SMALLEST possible change:**
+
+1. **One fix at a time**
+   - Change one thing
+   - Don't bundle fixes
+   - Don't "improve" surrounding code
+
+2. **Common minimal fixes**
+
+   ```typescript
+   // TypeScript: TS2345 - Type mismatch
+   // BAD: Rewrite the function with new types
+   // GOOD: Add the correct type annotation or assertion
+   const value = data as ExpectedType;
+
+   // TypeScript: TS2532 - Possibly undefined
+   // BAD: Refactor to eliminate the possibility
+   // GOOD: Add null check or optional chaining
+   const name = user?.name ?? 'default';
+
+   // Import: Cannot find module
+   // BAD: Restructure the module system
+   // GOOD: Fix the import path
+   import { Thing } from './correct/path';
+
+   // Dependency: Missing peer dependency
+   // BAD: Upgrade the entire dependency tree
+   // GOOD: Install the specific missing package
+   // $ yarn add missing-package@^required.version
+   ```
+
+3. **What NOT to do**
+   - Do NOT rename variables for "clarity"
+   - Do NOT extract functions for "reusability"
+   - Do NOT add error handling beyond what's needed
+   - Do NOT update unrelated dependencies
+   - Do NOT change code formatting
+
+### Phase 4: Verify
+
+**Confirm the build passes:**
+
+1. **Run the build command**
+   ```bash
+   # Run the same command that failed
+   yarn build          # or npm run build
+   tsc --noEmit        # TypeScript check
+   ```
+
+2. **Run tests to ensure no regressions**
+   ```bash
+   yarn test           # or npm test
+   ```
+
+3. **Check the diff**
+   ```bash
+   git diff
+   ```
+   - Is every changed line directly related to the error?
+   - Did you touch anything unrelated? Revert it.
+   - Is the diff as small as possible?
+
+4. **If build still fails**
+   - Read the NEW error message
+   - Is it the same error? → Your fix was wrong. Revert.
+   - Is it a different error? → Return to Phase 1 for the new error.
+   - Do NOT stack fixes without verifying between each one.
+
+## Red Flags — STOP and Return to Phase 1
+
+If you catch yourself thinking:
+
+| Thought | Reality |
+|---------|---------|
+| "While I'm fixing this, I'll also..." | Build fix. Nothing else. |
+| "This function should really be..." | File an issue. Fix the build. |
+| "The types are all wrong, let me redesign..." | Fix the ONE type error. Not all types. |
+| "I need to add a new abstraction..." | No new abstractions in a build fix. |
+| "Let me upgrade this dependency to latest..." | Only change the version if it fixes the error. |
+| "This code is messy, let me clean up..." | Messy code that compiles > clean code in a broken build. |
+| "The architecture caused this, so I should..." | Architecture changes are not build fixes. |
+
+**ALL of these mean: STOP. You are no longer build-fixing.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "The refactor prevents future build errors" | Future prevention is a separate task. Fix now. |
+| "It's just a small improvement" | Small improvements compound into large diffs. |
+| "The code is already open in my editor" | Being convenient doesn't make it a build fix. |
+| "No one will review a 1-line PR" | 1-line PRs are the BEST PRs. Ship it. |
+| "I need to understand the whole module" | You need to understand the error. Not the module. |
+| "The dependency is outdated anyway" | Outdated but compiling > updated and broken. |
+
+## Scope Guard
+
+Before committing, verify your changes pass the scope guard:
+
+```
+For EACH changed line, ask:
+  "Would the build fail without this specific change?"
+
+  YES → Keep it
+  NO  → Revert it
+```
+
+If any changed line fails the scope guard, you have scope creep. Remove it.
+
+## Quick Reference
+
+| Phase | Key Activity | Success Criteria |
+|-------|-------------|------------------|
+| **1. Read** | Read full error, classify, count | Know WHAT is broken |
+| **2. Identify** | Check changes, trace source | Know WHERE and WHY |
+| **3. Fix** | Smallest possible change | Minimal diff applied |
+| **4. Verify** | Build passes, tests pass, diff is clean | Build green, no extras |
+
+## Related Skills
+
+- **`error-analysis`** — For classifying and understanding error messages (Phase 1)
+- **`systematic-debugging`** — For runtime bugs, not compile-time errors
+- **`verification-before-completion`** — For confirming the fix before claiming success
+- **`refactoring`** — For when you actually WANT to improve structure (not during build fix)

package/.ai-rules/skills/code-explanation/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: code-explanation
 description: Use when explaining complex code to new team members, conducting code reviews, onboarding, or understanding unfamiliar codebases. Provides structured analysis from high-level overview to implementation details.
+context: fork
+agent: Explore
+allowed-tools: Read, Grep, Glob
+argument-hint: [file-or-symbol]
 ---
 
 # Code Explanation

package/.ai-rules/skills/context-management/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: context-management
 description: Use when working on long tasks that span multiple sessions, when context compaction is a concern, or when decisions from PLAN mode need to persist through ACT and EVAL modes.
+user-invocable: false
 ---
 
 # Context Management