@karedo-hq/agents 0.1.1 → 0.1.3

package/commands/publish-to-agents.md

@@ -0,0 +1,66 @@
+# Publish to Agents
+
+Publishes the `@karedo/agents` package after adding new rules or commands.
+
+## Instructions
+
+Follow these steps in order:
+
+### 1. Verify Changes
+
+Check what files have been added or modified in `packages/agents/`:
+
+```bash
+git status packages/agents/
+```
+
+Confirm the changes include new rules (`.mdc` files in `rules/`) or commands (`.md` files in `commands/`).
+
+### 2. Bump Version
+
+Update the version in `packages/agents/package.json`:
+
+```json
+"version": "X.X.X"
+```
+
+Use semantic versioning:
+
+- **Patch (X.X.1)**: Minor rule updates, typo fixes
+- **Minor (X.1.0)**: New rules or commands
+- **Major (1.0.0)**: Breaking changes to rule structure
+
+### 3. Commit and Push
+
+```bash
+git add packages/agents/ && git commit -m "chore(agents): bump to vX.X.X
+
+- Brief description of changes" && git push
+```
+
+### 4. Publish to npm
+
+From the `packages/agents` directory:
+
+```bash
+pnpm publish --access public
+```
+
+**Note**: You must be logged in to npm with publish access to `@karedo` scope.
+
+### 5. Verify Publication
+
+```bash
+npm view @karedo/agents version
+```
+
+Confirm the version matches what you just published.
+
+## Example Output
+
+```
+✅ Changes verified in packages/agents/
+✅ Version bumped to X.X.X
+✅ Committed and pushed to remote
+✅ Published @karedo/agents@X.X.X to npm
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karedo-hq/agents",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Centralized agent skills, rules, and commands for our engineering team",
   "type": "module",
   "bin": {

package/rules/api/nestjs.mdc

@@ -2,6 +2,7 @@
 description: General NestJS guidelines for our backend development.
 alwaysApply: false
 ---
+
 # NestJS Guidelines
 
 ## Module Organization
@@ -34,3 +35,19 @@ alwaysApply: false
 - Throw NestJS built-in exceptions (`NotFoundException`, `BadRequestException`, etc.)
 - Create custom exceptions extending `HttpException` when needed
 - Use exception filters for consistent error responses
+
+## Logging
+
+- Use `new Logger(ClassName.name)` for service-scoped loggers
+- **Always pass stack trace** as second argument to `logger.error()`:
+  ```ts
+  this.logger.error(`Failed to process: ${error.message}`, error.stack);
+  ```
+- **Include metadata in the message** via `JSON.stringify` (ConsoleLogger ignores object params):
+  ```ts
+  this.logger.error(
+    `Operation failed: ${error.message} ${JSON.stringify({ userId, context })}`,
+    error.stack
+  );
+  ```
+- Never log sensitive data (passwords, tokens, secrets)

package/rules/typescript.mdc

@@ -7,6 +7,7 @@ alwaysApply: true
 ## TypeScript Guidelines
 
 ### Types
+
 - Declare types for all variables, function params, and return values
 - Don't cast to `any` to get around type issues. Use `unknown` with type guards
 - Prefer `type` over `interface`.
@@ -14,19 +15,22 @@ alwaysApply: true
 - Use `readonly` and `as const` for immutable data
 
 ### Exports & Imports
+
 - One primary named export per file. Avoid `export default`
 - Use `export type { ... }` and `import type { ... }` for types
 
 ### Naming
+
 - **PascalCase:** Classes, types, components
 - **camelCase:** Variables, functions, methods
 - **kebab-case:** Files and directories
 - **UPPERCASE:** Environment variables, constants
 - Functions: verb prefix (`findUser`, `isValid`, `handleClick`)
 - Booleans: `is`, `has`, `can` prefix
-- Use complete, descriptive names for variables. Avoid things like (c => c._id). Exceptions: err, ctx, req, res, next
+- Use complete, descriptive names for variables. Avoid things like (c => c.\_id). Exceptions: err, ctx, req, res, next
 
 ### Functions
+
 - Single purpose, short functions
 - Early returns to avoid nesting
 - Use `function` to define them. Arrow functions only for functions inside functions.
@@ -35,26 +39,55 @@ alwaysApply: true
 - Maintain single level of abstraction
 
 ### Async
+
 - `async/await` over `.then()`
 - `Promise.all`/`Promise.allSettled` for concurrent operations
 - Move `await` into branches where actually needed
 
 ### Caching
+
 - Build `Map`/`Set` for repeated O(1) lookups
 - Cache object properties in loops (`const len = arr.length`)
 - Cache function results at module level for expensive computations
 - Check array length before expensive comparisons
 
 ### Errors
+
 - Use exceptions for unexpected errors
 - Catch only to: fix, add context, or re-throw
 
 ### Testing
+
 - Arrange-Act-Assert pattern
 - Clear naming: `inputX`, `mockX`, `actualX`, `expectedX`
 - Mock external dependencies
 
 ### Comments
+
 - DO NOT ADD VERBOSE STEP-BY-STEP COMMENTS
 - Only comment genuinely non-obvious logic when strictly necessary
-- Comments should explain *why*, not *what*
+- Comments should explain _why_, not _what_
+
+### Framework-Specific Rules
+
+**IMPORTANT:** Before implementing, read the applicable rules from the table below. Only read rules that match your task.
+
+**Backend tasks (`apps/api/`)** — Read from `/rules/api/`:
+| Rule | When to read |
+|------|--------------|
+| `nestjs.mdc` | Always for any backend work |
+| `controllers.mdc` | Creating/modifying API endpoints |
+| `services.mdc` | Creating/modifying services |
+| `dtos.mdc` | Creating/modifying request/response DTOs |
+| `mongodb-schemas.mdc` | Creating/modifying database schemas |
+| `tiptap-templates.mdc` | Working with Tiptap document templates |
+| `mail-from-template.mdc` | Implementing email sending |
+
+**Frontend tasks (`apps/web/`)** — Read from `/rules/web/`:
+| Rule | When to read |
+|------|--------------|
+| `nextjs.mdc` | Always for any frontend work |
+| `pages.mdc` | Creating new pages |
+| `tables.mdc` | Implementing data tables |
+| `data-fetching-and-server-actions.mdc` | Data fetching or server actions |
+| `responsive-dialog-drawer.mdc` | Dialog/drawer components |

package/rules/web/{api-layer.mdc → data-fetching-and-server-actions.mdc}

@@ -1,7 +1,8 @@
 ---
-description: How to create data-fetching functions and server actions on the frontend.
+description: How to handle frontend data-fetching and actions.
 alwaysApply: false
 ---
+
 # API Layer Patterns
 
 ## File Organization
@@ -56,11 +57,42 @@ headers: {
 
 ---
 
-## Client-Side Fetching
+## Data Fetching Strategy
+
+**Rule:** Server-first for page-level data; React Query hooks for nested interactive data.
+
+### Server-Side (Default)
+
+- Pages, tables, list views → fetch in RSC with URL-based pagination
+- Keeps payloads explicit and server rendering deterministic
+- Use `preparePaginationParams(dto)` for query string construction
+
+### Client-Side (Nested Interactive Components)
+
+- Comboboxes, dialogs, embedded forms/pickers → don't prop-drill giant lists
+- Create `useX` / `useInfiniteX` hooks in feature's `lib/hooks/`
+- Wrap `useQuery` / `useInfiniteQuery` from `@tanstack/react-query`
+- Handle pagination client-side (infinite scroll, search-as-you-type)
+- Use debounced search for text input filtering
+- Never use `useEffect(() => fetch().then(), [])` pattern
+
+### Anti-Pattern: MAX_QUERY_LIMIT
+
+Do NOT use `limit: MAX_QUERY_LIMIT` to feed dropdowns/comboboxes with "all" data.
+
+**Problems:**
+
+- Huge payloads for data the UI only partially needs
+- More memory + CPU on both backend and browser
+- Slower server renders / bigger RSC waterfalls
+- Worse UX for forms/dialogs that block on heavy lists
+
+**Signal to refactor:** If you see `MAX_QUERY_LIMIT` in a query feeding a nested UI selector, convert it to a React Query hook with pagination.
+
+**Examples:**
 
-- Use react-query for automatic request deduplication on client components.
-- Never use `useEffect(() => fetch().then(), [])` pattern.
-- Create query hooks when server props are impractical for nested client components.
+- `app/dashboard/contacts/lib/hooks/use-organization-contacts.ts` — hook pattern with `useInfiniteQuery`
+- `app/dashboard/clients/components/update-client-health-insurance-form.tsx` — combobox consuming the hook with infinite scroll
 
 ---