codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/nx-workspace-patterns/SKILL.md

@@ -0,0 +1,467 @@
+---
+name: nx-workspace-patterns
+description: "Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Nx Workspace Patterns
+
+Production patterns for Nx monorepo management.
+
+## Do not use this skill when
+
+- The task is unrelated to nx workspace patterns
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Setting up new Nx workspaces
+- Configuring project boundaries
+- Optimizing CI with affected commands
+- Implementing remote caching
+- Managing dependencies between projects
+- Migrating to Nx
+
+## Core Concepts
+
+### 1. Nx Architecture
+
+```
+workspace/
+├── apps/              # Deployable applications
+│   ├── web/
+│   └── api/
+├── libs/              # Shared libraries
+│   ├── shared/
+│   │   ├── ui/
+│   │   └── utils/
+│   └── feature/
+│       ├── auth/
+│       └── dashboard/
+├── tools/             # Custom executors/generators
+├── nx.json            # Nx configuration
+└── workspace.json     # Project configuration
+```
+
+### 2. Library Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **feature** | Smart components, business logic | `feature-auth` |
+| **ui** | Presentational components | `ui-buttons` |
+| **data-access** | API calls, state management | `data-access-users` |
+| **util** | Pure functions, helpers | `util-formatting` |
+| **shell** | App bootstrapping | `shell-web` |
+
+## Templates
+
+### Template 1: nx.json Configuration
+
+```json
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "npmScope": "myorg",
+  "affected": {
+    "defaultBase": "main"
+  },
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "nx/tasks-runners/default",
+      "options": {
+        "cacheableOperations": [
+          "build",
+          "lint",
+          "test",
+          "e2e",
+          "build-storybook"
+        ],
+        "parallel": 3
+      }
+    }
+  },
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["production", "^production"],
+      "cache": true
+    },
+    "test": {
+      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
+      "cache": true
+    },
+    "lint": {
+      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
+      "cache": true
+    },
+    "e2e": {
+      "inputs": ["default", "^production"],
+      "cache": true
+    }
+  },
+  "namedInputs": {
+    "default": ["{projectRoot}/**/*", "sharedGlobals"],
+    "production": [
+      "default",
+      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
+      "!{projectRoot}/tsconfig.spec.json",
+      "!{projectRoot}/jest.config.[jt]s",
+      "!{projectRoot}/.eslintrc.json"
+    ],
+    "sharedGlobals": [
+      "{workspaceRoot}/babel.config.json",
+      "{workspaceRoot}/tsconfig.base.json"
+    ]
+  },
+  "generators": {
+    "@nx/react": {
+      "application": {
+        "style": "css",
+        "linter": "eslint",
+        "bundler": "webpack"
+      },
+      "library": {
+        "style": "css",
+        "linter": "eslint"
+      },
+      "component": {
+        "style": "css"
+      }
+    }
+  }
+}
+```
+
+### Template 2: Project Configuration
+
+```json
+// apps/web/project.json
+{
+  "name": "web",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/web/src",
+  "projectType": "application",
+  "tags": ["type:app", "scope:web"],
+  "targets": {
+    "build": {
+      "executor": "@nx/webpack:webpack",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "compiler": "babel",
+        "outputPath": "dist/apps/web",
+        "index": "apps/web/src/index.html",
+        "main": "apps/web/src/main.tsx",
+        "tsConfig": "apps/web/tsconfig.app.json",
+        "assets": ["apps/web/src/assets"],
+        "styles": ["apps/web/src/styles.css"]
+      },
+      "configurations": {
+        "development": {
+          "extractLicenses": false,
+          "optimization": false,
+          "sourceMap": true
+        },
+        "production": {
+          "optimization": true,
+          "outputHashing": "all",
+          "sourceMap": false,
+          "extractLicenses": true
+        }
+      }
+    },
+    "serve": {
+      "executor": "@nx/webpack:dev-server",
+      "defaultConfiguration": "development",
+      "options": {
+        "buildTarget": "web:build"
+      },
+      "configurations": {
+        "development": {
+          "buildTarget": "web:build:development"
+        },
+        "production": {
+          "buildTarget": "web:build:production"
+        }
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "apps/web/jest.config.ts",
+        "passWithNoTests": true
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["apps/web/**/*.{ts,tsx,js,jsx}"]
+      }
+    }
+  }
+}
+```
+
+### Template 3: Module Boundary Rules
+
+```json
+// .eslintrc.json
+{
+  "root": true,
+  "ignorePatterns": ["**/*"],
+  "plugins": ["@nx"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {
+        "@nx/enforce-module-boundaries": [
+          "error",
+          {
+            "enforceBuildableLibDependency": true,
+            "allow": [],
+            "depConstraints": [
+              {
+                "sourceTag": "type:app",
+                "onlyDependOnLibsWithTags": [
+                  "type:feature",
+                  "type:ui",
+                  "type:data-access",
+                  "type:util"
+                ]
+              },
+              {
+                "sourceTag": "type:feature",
+                "onlyDependOnLibsWithTags": [
+                  "type:ui",
+                  "type:data-access",
+                  "type:util"
+                ]
+              },
+              {
+                "sourceTag": "type:ui",
+                "onlyDependOnLibsWithTags": ["type:ui", "type:util"]
+              },
+              {
+                "sourceTag": "type:data-access",
+                "onlyDependOnLibsWithTags": ["type:data-access", "type:util"]
+              },
+              {
+                "sourceTag": "type:util",
+                "onlyDependOnLibsWithTags": ["type:util"]
+              },
+              {
+                "sourceTag": "scope:web",
+                "onlyDependOnLibsWithTags": ["scope:web", "scope:shared"]
+              },
+              {
+                "sourceTag": "scope:api",
+                "onlyDependOnLibsWithTags": ["scope:api", "scope:shared"]
+              },
+              {
+                "sourceTag": "scope:shared",
+                "onlyDependOnLibsWithTags": ["scope:shared"]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Template 4: Custom Generator
+
+```typescript
+// tools/generators/feature-lib/index.ts
+import {
+  Tree,
+  formatFiles,
+  generateFiles,
+  joinPathFragments,
+  names,
+  readProjectConfiguration,
+} from '@nx/devkit';
+import { libraryGenerator } from '@nx/react';
+
+interface FeatureLibraryGeneratorSchema {
+  name: string;
+  scope: string;
+  directory?: string;
+}
+
+export default async function featureLibraryGenerator(
+  tree: Tree,
+  options: FeatureLibraryGeneratorSchema
+) {
+  const { name, scope, directory } = options;
+  const projectDirectory = directory
+    ? `${directory}/${name}`
+    : `libs/${scope}/feature-${name}`;
+
+  // Generate base library
+  await libraryGenerator(tree, {
+    name: `feature-${name}`,
+    directory: projectDirectory,
+    tags: `type:feature,scope:${scope}`,
+    style: 'css',
+    skipTsConfig: false,
+    skipFormat: true,
+    unitTestRunner: 'jest',
+    linter: 'eslint',
+  });
+
+  // Add custom files
+  const projectConfig = readProjectConfiguration(tree, `${scope}-feature-${name}`);
+  const projectNames = names(name);
+
+  generateFiles(
+    tree,
+    joinPathFragments(__dirname, 'files'),
+    projectConfig.sourceRoot,
+    {
+      ...projectNames,
+      scope,
+      tmpl: '',
+    }
+  );
+
+  await formatFiles(tree);
+}
+```
+
+### Template 5: CI Configuration with Affected
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Derive SHAs for affected commands
+        uses: nrwl/nx-set-shas@v4
+
+      - name: Run affected lint
+        run: npx nx affected -t lint --parallel=3
+
+      - name: Run affected test
+        run: npx nx affected -t test --parallel=3 --configuration=ci
+
+      - name: Run affected build
+        run: npx nx affected -t build --parallel=3
+
+      - name: Run affected e2e
+        run: npx nx affected -t e2e --parallel=1
+```
+
+### Template 6: Remote Caching Setup
+
+```typescript
+// nx.json with Nx Cloud
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "nx-cloud",
+      "options": {
+        "cacheableOperations": ["build", "lint", "test", "e2e"],
+        "accessToken": "your-nx-cloud-token",
+        "parallel": 3,
+        "cacheDirectory": ".nx/cache"
+      }
+    }
+  },
+  "nxCloudAccessToken": "your-nx-cloud-token"
+}
+
+// Self-hosted cache with S3
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "@nx-aws-cache/nx-aws-cache",
+      "options": {
+        "cacheableOperations": ["build", "lint", "test"],
+        "awsRegion": "us-east-1",
+        "awsBucket": "my-nx-cache-bucket",
+        "awsProfile": "default"
+      }
+    }
+  }
+}
+```
+
+## Common Commands
+
+```bash
+# Generate new library
+nx g @nx/react:lib feature-auth --directory=libs/web --tags=type:feature,scope:web
+
+# Run affected tests
+nx affected -t test --base=main
+
+# View dependency graph
+nx graph
+
+# Run specific project
+nx build web --configuration=production
+
+# Reset cache
+nx reset
+
+# Run migrations
+nx migrate latest
+nx migrate --run-migrations
+```
+
+## Best Practices
+
+### Do's
+- **Use tags consistently** - Enforce with module boundaries
+- **Enable caching early** - Significant CI savings
+- **Keep libs focused** - Single responsibility
+- **Use generators** - Ensure consistency
+- **Document boundaries** - Help new developers
+
+### Don'ts
+- **Don't create circular deps** - Graph should be acyclic
+- **Don't skip affected** - Test only what changed
+- **Don't ignore boundaries** - Tech debt accumulates
+- **Don't over-granularize** - Balance lib count
+
+## Resources
+
+- [Nx Documentation](https://nx.dev/getting-started/intro)
+- [Module Boundaries](https://nx.dev/core-features/enforce-module-boundaries)
+- [Nx Cloud](https://nx.app/)

package/templates/.agent/skills/odoo-docker-deployment/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: odoo-docker-deployment
+description: "Production-ready Docker and docker-compose setup for Odoo with PostgreSQL, persistent volumes, environment-based configuration, and Nginx reverse proxy."
+risk: safe
+source: "self"
+---
+
+# Odoo Docker Deployment
+
+## Overview
+
+This skill provides a complete, production-ready Docker setup for Odoo, including PostgreSQL, persistent file storage, environment variable configuration, and an optional Nginx reverse proxy with SSL. It covers both development and production configurations.
+
+## When to Use This Skill
+
+- Spinning up a local Odoo development environment with Docker.
+- Deploying Odoo to a VPS or cloud server (AWS, DigitalOcean, etc.).
+- Troubleshooting Odoo container startup failures or database connection errors.
+- Adding a reverse proxy with SSL to an existing Odoo Docker setup.
+
+## How It Works
+
+1. **Activate**: Mention `@odoo-docker-deployment` and describe your deployment scenario.
+2. **Generate**: Receive a complete `docker-compose.yml` and `odoo.conf` ready to run.
+3. **Debug**: Describe your container error and get a diagnosis with a fix.
+
+## Examples
+
+### Example 1: Production docker-compose.yml
+
+```yaml
+# Note: The top-level 'version' key is deprecated in Docker Compose v2+
+# and can be safely omitted. Remove it to avoid warnings.
+
+services:
+  db:
+    image: postgres:15
+    restart: always
+    environment:
+      POSTGRES_DB: odoo
+      POSTGRES_USER: odoo
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    networks:
+      - odoo-net
+
+  odoo:
+    image: odoo:17.0
+    restart: always
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "8069:8069"
+      - "8072:8072"   # Longpolling for live chat / bus
+    environment:
+      HOST: db
+      USER: odoo
+      PASSWORD: ${POSTGRES_PASSWORD}
+    volumes:
+      - odoo-web-data:/var/lib/odoo
+      - ./addons:/mnt/extra-addons   # Custom modules
+      - ./odoo.conf:/etc/odoo/odoo.conf
+    networks:
+      - odoo-net
+
+volumes:
+  postgres-data:
+  odoo-web-data:
+
+networks:
+  odoo-net:
+```
+
+### Example 2: odoo.conf
+
+```ini
+[options]
+admin_passwd = ${ODOO_MASTER_PASSWORD}    ; set via env or .env file
+db_host = db
+db_port = 5432
+db_user = odoo
+db_password = ${POSTGRES_PASSWORD}        ; set via env or .env file
+
+; addons_path inside the official Odoo Docker image (Debian-based)
+addons_path = /mnt/extra-addons,/usr/lib/python3/dist-packages/odoo/addons
+
+logfile = /var/log/odoo/odoo.log
+log_level = warn
+
+; Worker tuning for a 4-core / 8GB server:
+workers = 9                ; (CPU cores × 2) + 1
+max_cron_threads = 2
+limit_memory_soft = 1610612736   ; 1.5 GB — soft kill threshold
+limit_memory_hard = 2147483648   ; 2.0 GB — hard kill threshold
+limit_time_cpu = 600
+limit_time_real = 1200
+limit_request = 8192
+```
+
+### Example 3: Common Commands
+
+```bash
+# Start all services in background
+docker compose up -d
+
+# Stream Odoo logs in real time
+docker compose logs -f odoo
+
+# Restart Odoo only (not DB — avoids data risk)
+docker compose restart odoo
+
+# Stop all services
+docker compose down
+
+# Backup the database to a local SQL dump
+docker compose exec db pg_dump -U odoo odoo > backup_$(date +%Y%m%d).sql
+
+# Update a custom module without restarting the server
+docker compose exec odoo odoo -d odoo --update my_module --stop-after-init
+```
+
+## Best Practices
+
+- ✅ **Do:** Store all secrets in a `.env` file and reference them with `${VAR}` — never hardcode passwords in `docker-compose.yml`.
+- ✅ **Do:** Use `depends_on: condition: service_healthy` with a PostgreSQL healthcheck to prevent Odoo starting before the DB is ready.
+- ✅ **Do:** Put Nginx in front of Odoo for SSL termination (Let's Encrypt / Certbot) — never expose Odoo directly on port 80/443.
+- ✅ **Do:** Set `workers = (CPU cores × 2) + 1` in `odoo.conf` — `workers = 0` uses single-threaded mode and blocks all users.
+- ❌ **Don't:** Expose port 5432 (PostgreSQL) to the public internet — keep it on the internal Docker network only.
+- ❌ **Don't:** Use the `latest` or `17` Docker image tags in production — always pin to a specific patch-level tag (e.g., `odoo:17.0`).
+- ❌ **Don't:** Mount `odoo.conf` and rely on it for secrets in CI/CD — use Docker secrets or environment variables instead.
+
+## Limitations
+
+- This skill covers **self-hosted Docker deployments** — Odoo.sh (cloud-managed hosting) has a completely different deployment model.
+- **Horizontal scaling** (multiple Odoo containers behind a load balancer) requires shared filestore (NFS or S3-compatible storage) not covered here.
+- Does not include an Nginx configuration template — consult the [official Odoo Nginx docs](https://www.odoo.com/documentation/17.0/administration/install/deploy.html) for the full reverse proxy config.
+- The `addons_path` inside the Docker image may change with new base image versions — always verify after upgrading the Odoo image.

package/templates/.agent/skills/odoo-performance-tuner/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: odoo-performance-tuner
+description: "Expert guide for diagnosing and fixing Odoo performance issues: slow queries, worker configuration, memory limits, PostgreSQL tuning, and profiling tools."
+risk: safe
+source: "self"
+---
+
+# Odoo Performance Tuner
+
+## Overview
+
+This skill helps diagnose and resolve Odoo performance problems — from slow page loads and database bottlenecks to worker misconfiguration and memory bloat. It covers PostgreSQL query tuning, Odoo worker settings, and built-in profiling tools.
+
+## When to Use This Skill
+
+- Odoo is slow in production (slow page loads, timeouts).
+- Getting `MemoryError` or `Worker timeout` errors in logs.
+- Diagnosing a slow database query using Odoo's profiler.
+- Tuning `odoo.conf` for a specific server spec.
+
+## How It Works
+
+1. **Activate**: Mention `@odoo-performance-tuner` and describe your performance issue.
+2. **Diagnose**: Share relevant log lines or config and receive a root cause analysis.
+3. **Fix**: Get exact configuration changes with explanations.
+
+## Examples
+
+### Example 1: Recommended Worker Configuration
+
+```ini
+# odoo.conf — tuned for a 4-core, 8GB RAM server
+
+workers = 9                   # (CPU_cores × 2) + 1 — never set to 0 in production
+max_cron_threads = 2          # background cron jobs; keep ≤ 2 to preserve user-facing capacity
+limit_memory_soft = 1610612736  # 1.5 GB — worker is recycled gracefully after this
+limit_memory_hard = 2147483648  # 2.0 GB — worker is killed immediately; prevents OOM crashes
+limit_time_cpu = 600          # max CPU seconds per request
+limit_time_real = 1200        # max wall-clock seconds per request
+limit_request = 8192          # max requests before worker recycles (prevents memory leaks)
+```
+
+### Example 2: Find Slow Queries with PostgreSQL
+
+```sql
+-- Step 1: Enable pg_stat_statements extension (run once as postgres superuser)
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Step 2: Also add to postgresql.conf and reload:
+-- shared_preload_libraries = 'pg_stat_statements'
+-- log_min_duration_statement = 1000   -- log queries taking > 1 second
+
+-- Step 3: Find the top 10 slowest average queries
+SELECT
+    LEFT(query, 100) AS query_snippet,
+    round(mean_exec_time::numeric, 2) AS avg_ms,
+    calls,
+    round(total_exec_time::numeric, 2) AS total_ms
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 10;
+
+-- Step 4: Check for missing indexes causing full table scans
+SELECT schemaname, tablename, attname, n_distinct, correlation
+FROM pg_stats
+WHERE tablename = 'sale_order_line'
+  AND correlation < 0.5   -- low correlation = poor index efficiency
+ORDER BY n_distinct DESC;
+```
+
+### Example 3: Use Odoo's Built-In Profiler
+
+```text
+Prerequisites: Run Odoo with ?debug=1 in the URL to enable debug mode.
+
+Menu: Settings → Technical → Profiling
+
+Steps:
+  1. Click "Enable Profiling" — set a duration (e.g., 60 seconds)
+  2. Navigate to and reproduce the slow action
+  3. Return to Settings → Technical → Profiling → View Results
+
+What to look for:
+  - Total SQL queries > 100 on a single page  → N+1 query problem
+  - Single queries taking > 100ms             → missing DB index
+  - Same query repeated many times            → missing cache, use @ormcache
+  - Python time high but SQL low             → compute field inefficiency
+```
+
+## Best Practices
+
+- ✅ **Do:** Use `mapped()`, `filtered()`, and `sorted()` on in-memory recordsets — they don't trigger additional SQL.
+- ✅ **Do:** Add PostgreSQL B-tree indexes on columns frequently used in domain filters (`partner_id`, `state`, `date_order`).
+- ✅ **Do:** Enable Odoo's HTTP caching for static assets and put a CDN (Cloudflare, AWS CloudFront) in front of the website.
+- ✅ **Do:** Use `@tools.ormcache` decorator on methods pulled repeatedly with the same arguments.
+- ❌ **Don't:** Set `workers = 0` in production — single-threaded mode serializes all requests and blocks all users on any slow operation.
+- ❌ **Don't:** Ignore `limit_memory_soft` — workers exceeding it are recycled between requests; without the limit they grow unbounded and crash.
+- ❌ **Don't:** Directly manipulate `prefetch_ids` on recordsets — rely on Odoo's automatic batch prefetching, which activates by default.
+
+## Limitations
+
+- PostgreSQL tuning (`shared_buffers`, `work_mem`, `effective_cache_size`) is highly server-specific and not covered in depth here — use [PGTune](https://pgtune.leopard.in.ua/) as a starting baseline.
+- The built-in Odoo profiler only captures **Python + SQL** traces; JavaScript rendering performance requires browser DevTools.
+- **Odoo.sh** managed hosting restricts direct PostgreSQL and `odoo.conf` access — some tuning options are unavailable.
+- Does not cover **Redis-based session store** or **Celery task queue** optimizations, which are advanced patterns for very high-traffic instances.