ima-claude 2.16.0 → 2.18.0

package/README.md

@@ -255,7 +255,7 @@ Named subagents with hard constraints — model, tools, and permissions enforced
 | `ima-claude:implementer` | sonnet | full access | `functional-programmer` | Feature dev, bug fixes, refactoring, tests |
 | `ima-claude:reviewer` | sonnet | read-only | `functional-programmer` | Code review, security audit, FP compliance |
 | `ima-claude:tester` | sonnet | full access | `unit-testing`, `functional-programmer` | Test creation, TDD, test running, debugging failures |
-| `ima-claude:wp-developer` | sonnet | full access | `php-fp`, `php-fp-wordpress`, `wp-local`, `ima-forms-expert`, `ima-bootstrap`, `jquery` | WordPress plugins, themes, WP-CLI, forms |
+| `ima-claude:wp-developer` | sonnet | full access | `php-fp`, `php-fp-wordpress`, `wp-ddev`, `wp-local`, `ima-forms-expert`, `ima-bootstrap`, `jquery` | WordPress plugins, themes, WP-CLI, forms |
 | `ima-claude:memory` | sonnet | full access | `mcp-vestige`, `mcp-qdrant`, `mcp-serena` | Memory search, storage, consolidation across Vestige/Qdrant/Serena |
 
 Agents are auto-discovered from `plugins/ima-claude/agents/`. No manifest changes needed to add new ones.
@@ -286,6 +286,13 @@ Agents are auto-discovered from `plugins/ima-claude/agents/`. No manifest change
 | `py-fp` | Python FP core - comprehensions, generators, frozen dataclasses |
 | `quasar-fp` | Quasar Framework with utility-first CSS |
 
+### CRM Skills
+
+| Skill | Description |
+|-------|-------------|
+| `espocrm` | EspoCRM skill family router (intent detection, Salesforce mapping, child skill routing) |
+| `espocrm-api` | EspoCRM v9.x REST API (auth, CRUD, WHERE filtering, relationships, webhooks, mass ops) |
+
 ### Domain Expert Skills
 
 | Skill | Description |
@@ -295,6 +302,7 @@ Agents are auto-discovered from `plugins/ima-claude/agents/`. No manifest change
 | `ima-bootstrap` | Bootstrap 5.3 + IMA brand (utility-first CSS, SCSS) |
 | `playwright` | E2E testing with Playwright + TypeScript |
 | `docs-organize` | Three-tier documentation organization |
+| `wp-ddev` | WP-CLI commands for DDEV WordPress environments |
 | `wp-local` | WP-CLI commands for Flywheel Local WP |
 | `jira-checkpoint` | Jira awareness checkpoints for team visibility |
 | `phpunit-wp` | PHPUnit testing for WordPress plugins with FP principles |

package/dist/cli.js

@@ -11,7 +11,7 @@ var HOOKS_DIR = join(CLAUDE_DIR, "hooks");
 var COMMANDS_DIR = join(CLAUDE_DIR, "commands");
 var RULES_DIR = join(CLAUDE_DIR, "rules");
 var SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
-var VERSION = "2.16.0";
+var VERSION = "2.18.0";
 var colors = {
   reset: "\x1B[0m",
   bright: "\x1B[1m",
@@ -90,10 +90,14 @@ var SKILLS_TO_INSTALL = [
   "jquery",
   // Payment & API skills
   "php-authnet",
+  // CRM skills
+  "espocrm",
+  "espocrm-api",
   // Domain expert skills
   "architect",
   "docs-organize",
   "wp-local",
+  "wp-ddev",
   "rg",
   "ima-forms-expert",
   "ima-brand",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima-claude",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "description": "IMA's AI coding agent skills - FP patterns, architecture guidance, and team standards. Supports Claude Code, Junie CLI, Gemini CLI, and GitHub Copilot.",
   "type": "module",
   "scripts": {

package/plugins/ima-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ima-claude",
-  "version": "2.16.0",
-  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 57 skills, 24 hooks, default persona, 3-tier memory system.",
+  "version": "2.18.0",
+  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 60 skills, 24 hooks, default persona, 3-tier memory system.",
   "author": {
     "name": "IMA",
     "url": "https://github.com/Soabirw/ima-claude"

package/plugins/ima-claude/agents/wp-developer.md

@@ -5,6 +5,7 @@ model: sonnet
 skills:
   - php-fp
   - php-fp-wordpress
+  - wp-ddev
   - wp-local
   - ima-forms-expert
   - ima-bootstrap
@@ -23,7 +24,7 @@ You are a WordPress development specialist with deep knowledge of the WordPress
 ## Capabilities
 
 - Plugin and theme development with WordPress coding standards
-- WP-CLI operations via Local WP environments
+- WP-CLI operations via DDEV environments (preferred) or Local WP
 - IMA Forms component library (ima_forms_* functions)
 - Bootstrap 5.3 integration with IMA brand system
 - jQuery patterns for WordPress DOM manipulation

package/plugins/ima-claude/hooks/prompt_coach_digest.md

@@ -13,7 +13,7 @@
 | WordPress plugin, nonce, sanitization, capability | `php-fp-wordpress` |
 | Architecture, new project, scaling, microservices | `architect` |
 | Documentation structure, organize docs | `docs-organize` |
-| WP-CLI, Local WP, wp plugin, wp db query | `wp-local` |
+| WP-CLI, DDEV, ddev wp, wp plugin, wp db query | `wp-ddev` (DDEV) or `wp-local` (Flywheel) |
 | Find in files, search code, grep | `rg` |
 | Latest, current, 2025/2026, recent updates, research | `mcp-tavily` |
 | Library docs, React API, how to use [library] | `mcp-context7` |

package/plugins/ima-claude/skills/espocrm/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: "espocrm"
+description: >-
+  EspoCRM skill family router. Detects intent (API calls, extension development,
+  UI customization) and routes to the appropriate child skill. Provides shared
+  context: v9.x target, entity-based REST architecture, Salesforce mental model
+  mapping. Use when: any EspoCRM work, CRM integration, CRM API, EspoCRM
+  customization. Triggers on: EspoCRM, Espo, CRM API, CRM integration, CRM
+  entity, CRM webhook, CRM hook.
+---
+
+# EspoCRM - Skill Family Router
+
+Routes EspoCRM work to the right child skill based on intent.
+
+**Target version**: v9.x (9.0+)
+**Architecture**: Entity-based REST API, PHP backend, Backbone.js frontend
+
+## Decision Tree
+
+```
+What are you doing with EspoCRM?
+├── REST API calls (external integration)?
+│   → espocrm-api (primary) + php-fp or js-fp-api
+│   → Auth, CRUD, filtering, webhooks, mass ops
+│
+├── PHP extension development (hooks, services, custom entities)?
+│   → espocrm-extensions (Phase 2) + php-fp
+│   → ORM, hooks, services, DI, custom controllers, modules
+│
+├── Frontend/UI customization (views, fields, layouts)?
+│   → espocrm-ui (Phase 3)
+│   → Backbone views, Espo.Ajax, Handlebars templates
+│
+└── Not sure / mixed?
+    → Start with espocrm-api for data access
+    → Route to extension/UI skill once scope is clear
+```
+
+## Shared Context
+
+### Entity-Based Model
+EspoCRM organizes data as **Entity Types** (Account, Contact, Lead, Opportunity, custom types). Every entity type gets automatic REST endpoints. Custom entities created via Entity Manager are immediately API-accessible.
+
+### Salesforce Mental Model
+For developers familiar with Salesforce, this mapping accelerates onboarding:
+
+| Salesforce | EspoCRM |
+|---|---|
+| sObject | Entity Type |
+| Connected App + OAuth | API User + API Key |
+| SOQL | WHERE JSON filters + select/orderBy params |
+| SOSL | Text filter on list endpoint |
+| Apex Trigger | PHP Hook (beforeSave, afterSave) |
+| Apex REST endpoint | Custom API Action (Controller + routes.json) |
+| LWC / Visualforce | Custom Views (JS, extending base views) |
+| Platform Events / CDC | Webhooks ({Entity}.create, .update, .delete) |
+| Bulk API 2.0 | No equivalent (loop individual calls or use Import) |
+| Governor Limits | None (self-hosted, you manage resources) |
+| AppExchange | EspoCRM Extensions marketplace |
+
+### Key Differences from Salesforce
+- **No SOQL** — queries use structured JSON WHERE filters (verbose but explicit)
+- **No Bulk API** — mass operations exist (massUpdate, massDelete) but no batch create
+- **No Composite API** — one request per operation
+- **No governor limits** — self-hosted, manage at server/proxy level
+- **Simpler auth** — API Key in one header vs. multi-step OAuth
+- **Metadata is JSON files** — no deployment steps, changes take effect on cache clear
+
+### Documentation Lookup
+Use Context7 for live EspoCRM docs: `resolve-library-id("espocrm")` resolves to `/espocrm/documentation`.
+
+## Child Skill Status
+
+| Skill | Status | Covers |
+|---|---|---|
+| `espocrm-api` | Active | REST API, auth, CRUD, filtering, webhooks, mass ops |
+| `espocrm-extensions` | Planned | PHP hooks, services, ORM, custom entities, modules |
+| `espocrm-ui` | Planned | JS views, fields, Espo.Ajax, Backbone, Handlebars |

package/plugins/ima-claude/skills/espocrm-api/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: "espocrm-api"
+description: >-
+  EspoCRM v9.x REST API patterns — authentication (API Key, HMAC), CRUD operations,
+  JSON WHERE filtering, relationship management, webhooks, mass operations, error
+  handling, and performance. Official PHP client and Node.js patterns. Use when:
+  calling EspoCRM API, building CRM integrations, querying CRM data, managing
+  webhooks, bulk CRM operations. Triggers on: EspoCRM API, CRM endpoint, CRM
+  query, CRM webhook, CRM filter, espo api, api/v1, X-Api-Key, HMAC auth,
+  entity CRUD.
+---
+
+# EspoCRM REST API (v9.x)
+
+Patterns for the EspoCRM REST API. External integrations, data pipelines, and automation.
+
+**Base URL**: `https://{your-site}/api/v1/`
+**Content-Type**: `application/json` (all requests)
+**Parent skill**: `espocrm` (router — Salesforce mapping, shared context)
+**Companion skills**: `php-fp` (PHP integrations), `js-fp-api` (Node integrations)
+**Live docs**: Context7 `/espocrm/documentation`
+
+---
+
+## Authentication
+
+Three methods, in order of recommendation:
+
+### 1. API Key (Simple, Recommended for Dev/Internal)
+
+Create an API User at Administration > API Users. Authentication method: "API Key". Assign a Role for scope.
+
+```
+X-Api-Key: {key_from_api_user_detail_view}
+```
+
+One header. Done. Use when transport is already secured (HTTPS, internal network).
+
+### 2. HMAC (Production, Most Secure)
+
+Create an API User with "HMAC" auth. Both API Key and Secret Key are generated. Secret never leaves your server.
+
+```
+X-Hmac-Authorization: base64(apiKey + ':' + hmacSha256(METHOD + ' /' + uri, secretKey))
+```
+
+Where `METHOD` is uppercase (GET, POST, PUT, DELETE) and `uri` is the path after `/api/v1/`.
+
+```php
+// PHP
+$string = $method . ' /' . $uri;
+$hash = hash_hmac('sha256', $string, $secretKey);
+$header = base64_encode($apiKey . ':' . $hash);
+// X-Hmac-Authorization: $header
+```
+
+```javascript
+// Node.js
+import { createHmac } from 'node:crypto';
+const hash = createHmac('sha256', secretKey).update(`${method} /${uri}`).digest('hex');
+const header = Buffer.from(`${apiKey}:${hash}`).toString('base64');
+// X-Hmac-Authorization: header
+```
+
+### 3. Basic / Token Auth (Session-Based Only)
+
+```
+Espo-Authorization: base64(username + ':' + token)
+```
+
+Obtain token via `GET App/user` with initial credentials. Only for session flows (SPA, frontend). Never for server-to-server.
+
+### Auth Decision
+
+| Context | Method |
+|---|---|
+| Dev/testing, internal scripts | API Key |
+| Production integrations | HMAC |
+| Frontend SPA, session flows | Token auth |
+| Never | Basic auth with plaintext password |
+
+---
+
+## CRUD Operations
+
+All entity types share the same endpoint pattern. Replace `{Entity}` with the type name (Account, Contact, Lead, CMyCustomEntity, etc.).
+
+### List Records
+```
+GET {Entity}
+```
+Returns `{"list": [...], "total": N}`. Total is `-1` if more records exist (pagination needed), `-2` if count disabled.
+
+### Read One Record
+```
+GET {Entity}/{id}
+```
+
+### Create
+```
+POST {Entity}
+{"name": "Acme Corp", "assignedUserId": "someUserId"}
+```
+Returns the created record with generated `id`. Use `X-Skip-Duplicate-Check: true` to bypass duplicate detection.
+
+### Update (Partial)
+```
+PUT {Entity}/{id}
+{"status": "Closed Won"}
+```
+Only send changed fields. Returns full updated record.
+
+### Delete
+```
+DELETE {Entity}/{id}
+```
+Returns `true`.
+
+### Endpoint Summary
+
+| Operation | Method | Path |
+|---|---|---|
+| List | GET | `{Entity}` |
+| Read | GET | `{Entity}/{id}` |
+| Create | POST | `{Entity}` |
+| Update | PUT | `{Entity}/{id}` |
+| Delete | DELETE | `{Entity}/{id}` |
+| List related | GET | `{Entity}/{id}/{link}` |
+| Link | POST | `{Entity}/{id}/{link}` |
+| Unlink | DELETE | `{Entity}/{id}/{link}` |
+| Mass update | POST | `{Entity}/action/massUpdate` |
+| Mass delete | POST | `{Entity}/action/massDelete` |
+| Stream/notes | GET | `{Entity}/{id}/stream` |
+| Webhook CRUD | POST/DELETE | `Webhook` / `Webhook/{id}` |
+| Auth token | GET | `App/user` |
+| Attachment up | POST | `Attachment` |
+| Attachment down | GET | `Attachment/file/{id}` |
+| OpenAPI spec | GET | `OpenApi` |
+
+---
+
+## Filtering & Search
+
+Parameters go as query params or as a single JSON-encoded `searchParams` param.
+
+### Core Parameters
+
+| Param | Type | Purpose |
+|---|---|---|
+| `select` | string | Comma-separated fields: `id,name,status` |
+| `maxSize` | int | Records per page (max 200, default varies) |
+| `offset` | int | Pagination offset |
+| `orderBy` | string | Sort field |
+| `order` | string | `asc` or `desc` |
+| `where` | array | Filter conditions (see below) |
+| `primaryFilter` | string | Named server-side filter (`open`, `onlyMy`, etc.) |
+| `boolFilterList` | array | Boolean toggles: `["onlyMy", "followed"]` |
+
+v9.0+ aliases (WAF-safe): `attributeSelect` for `select`, `whereGroup` for `where`.
+
+### WHERE Operators
+
+Each filter is `{"type": "...", "attribute": "...", "value": "..."}`. Multiple items in the `where` array are implicitly ANDed. Use `{"type": "or", "value": [...]}` for OR logic.
+
+**Operator categories**: equality (`equals`, `notEquals`), comparison (`greaterThan`, `lessThan`, `greaterThanOrEquals`, `lessThanOrEquals`), null (`isNull`, `isNotNull`), boolean (`isTrue`, `isFalse`), string (`contains`, `notContains`, `startsWith`, `endsWith`, `like`, `notLike`), set (`in`, `notIn`), relationship (`linkedWith`, `notLinkedWith`, `isLinked`, `isNotLinked`), date helpers (`today`, `past`, `future`, `lastSevenDays`, `currentMonth`, `lastMonth`, `currentYear`, `between`, `lastXDays`, `nextXDays`), logical (`or`, `and`).
+
+Full operator reference with examples: `references/where-operators.md`
+
+---
+
+## Relationships
+
+Link names are visible at Administration > Entity Manager > {Entity} > Relationships (4th column).
+
+### List Related Records
+```
+GET Account/{id}/contacts?select=id,name,emailAddress&maxSize=50
+```
+Same search params as list endpoint.
+
+### Link Records
+```
+POST Account/{id}/contacts
+{"id": "contactId"}
+```
+
+Multiple at once:
+```json
+{"ids": ["id1", "id2", "id3"]}
+```
+
+Mass relate by filter:
+```json
+{"massRelate": true, "where": [{"type": "equals", "attribute": "status", "value": "Active"}]}
+```
+
+### Unlink Records
+```
+DELETE Account/{id}/contacts
+{"id": "contactId"}
+```
+
+Multiple: `{"ids": ["id1", "id2"]}`.
+
+---
+
+## Webhooks
+
+### Register
+```
+POST Webhook
+{"event": "Contact.create", "url": "https://your-server.com/hook"}
+```
+Returns `{"id": "webhookId", "secretKey": "generatedKey"}`. Save both for signature verification.
+
+### Event Types
+- `{Entity}.create` — record created (all attributes in payload)
+- `{Entity}.update` — record updated (only changed attributes)
+- `{Entity}.delete` — record removed (ID only)
+- `{Entity}.fieldUpdate.{field}` — specific field changed
+
+### Payload Format
+Always an array (even for single events):
+```json
+[{"id": "abc123", "name": "Updated Name", "status": "Active"}]
+```
+
+### Signature Verification
+The `Signature` header contains: `base64(webhookId + ':' + hmacSha256(rawBody, secretKey))`.
+
+```php
+$expected = base64_encode($webhookId . ':' . hash_hmac('sha256', $rawBody, $secretKey));
+$valid = hash_equals($expected, $_SERVER['HTTP_SIGNATURE']);
+```
+
+### Lifecycle
+- Processed by scheduled job "Process Webhook Queue" (default: every 5 min)
+- Failed deliveries are retried automatically
+- Persistent failures deactivate the webhook
+- Config: `webhookAllowedAddressList` in `data/config.php` for internal URLs
+
+### Delete
+```
+DELETE Webhook/{id}
+```
+
+---
+
+## Mass Operations
+
+### Mass Update
+```
+POST Lead/action/massUpdate
+```
+
+By IDs:
+```json
+{"ids": ["id1", "id2"], "data": {"assignedUserId": "userId", "status": "In Process"}}
+```
+
+By filter:
+```json
+{"where": [{"type": "equals", "attribute": "status", "value": "New"}], "data": {"status": "Assigned"}}
+```
+
+### Mass Delete
+```
+POST Lead/action/massDelete
+```
+Same payload patterns — `ids` array or `where` filter.
+
+### No Bulk Create
+There is no native batch create endpoint. For bulk ingestion:
+1. Loop individual POST requests with reasonable pacing
+2. Use the built-in Import feature (Administration > Import) for CSV
+3. Write a custom API action for batch processing if volume demands it
+
+### Important
+API Before-Save Scripts (Formula) are **not executed** during mass update operations.
+
+---
+
+## Error Handling
+
+### Status Codes
+
+| Code | Meaning | Action |
+|---|---|---|
+| 200 | Success | — |
+| 400 | Bad Request | Check required fields, validation |
+| 401 | Unauthorized | Check auth headers/credentials |
+| 403 | Forbidden | Check API User role/ACL |
+| 404 | Not Found | Record doesn't exist or no read access |
+| 409 | Conflict | Duplicate detected or record locked |
+| 500 | Server Error | Check `data/log` on server |
+
+### Error Details
+Error reason is in the `X-Status-Reason` response header (not always in the body).
+
+### Duplicate Detection (409)
+```json
+{"reason": "Duplicate", "data": {"idList": ["existingId1"]}}
+```
+Bypass with `X-Skip-Duplicate-Check: true` header.
+
+---
+
+## Performance Best Practices
+
+1. **Select only needed fields** — `?select=id,name,status` avoids loading all attributes
+2. **Skip total count** — `X-No-Total: true` header skips the COUNT query on list requests
+3. **Paginate** — use `offset` + `maxSize` (keep maxSize at 50-100)
+4. **Use primary filters** — server-optimized named filters are faster than complex WHERE
+5. **Minimal API User roles** — dedicated API users with only required scopes
+6. **No native rate limiter** — implement at reverse proxy level (nginx, Apache) if needed
+7. **OpenAPI spec** — `GET OpenApi` returns full schema for your instance including custom entities (v9.3+, admin only)
+
+---
+
+## Client Libraries
+
+### PHP (Official — Preferred)
+
+`composer require espocrm/php-espo-api-client`
+
+Class: `Espo\ApiClient\Client`. Constructor takes base URL. Auth via `setApiKey()` or `setApiKey()` + `setSecretKey()` for HMAC. All requests through `$client->request(METHOD, path, params, payload)`.
+
+### Node.js
+
+No official npm package. Build a thin client around `fetch` with:
+- Base URL + `/api/v1/` prefix
+- `X-Api-Key` header (or compute HMAC per-request)
+- `Content-Type: application/json`
+- Search params as JSON-encoded `searchParams` query param
+- Error extraction from `X-Status-Reason` header on non-2xx responses
+
+---
+
+## Field Types & API Representation
+
+| Field Type | JSON Type | Example |
+|---|---|---|
+| varchar | string | `"name": "Test"` |
+| text | string | `"description": "Long text"` |
+| int | number | `"quantity": 5` |
+| float | number | `"rate": 4.5` |
+| boolean | boolean | `"isActive": true` |
+| enum | string | `"status": "New"` |
+| multiEnum | string[] | `"tags": ["A", "B"]` |
+| date | string | `"closeDate": "2025-06-15"` |
+| datetime | string (UTC) | `"createdAt": "2025-06-15 14:30:00"` |
+| currency | number + string | `"amount": 1000, "amountCurrency": "USD"` |
+| link | string (ID) | `"accountId": "someId"` |
+| linkMultiple | string[] + object | `"teamsIds": ["id1"], "teamsNames": {"id1": "Sales"}` |
+| email | string | `"emailAddress": "test@example.com"` |
+| phone | string | `"phoneNumber": "+1234567890"` |
+| address | multiple fields | `"billingAddressStreet": "123 Main", "billingAddressCity": "NYC"` |
+| file | string (ID) | `"fileId": "attachmentId"` |
+
+All datetime values are UTC. Date format: `YYYY-MM-DD`. Datetime: `YYYY-MM-DD HH:mm:ss`.

package/plugins/ima-claude/skills/espocrm-api/references/where-operators.md

@@ -0,0 +1,84 @@
+# EspoCRM WHERE Filter Operators
+
+Complete reference for the `where` array filter objects used in list/search requests.
+
+Each filter: `{"type": "...", "attribute": "...", "value": "..."}`
+
+## Equality & Comparison
+
+| Type | Value | Example |
+|---|---|---|
+| `equals` | any | `{"type": "equals", "attribute": "status", "value": "New"}` |
+| `notEquals` | any | `{"type": "notEquals", "attribute": "status", "value": "Canceled"}` |
+| `greaterThan` | number/date | `{"type": "greaterThan", "attribute": "amount", "value": 1000}` |
+| `lessThan` | number/date | `{"type": "lessThan", "attribute": "amount", "value": 5000}` |
+| `greaterThanOrEquals` | number/date | `{"type": "greaterThanOrEquals", "attribute": "probability", "value": 50}` |
+| `lessThanOrEquals` | number/date | `{"type": "lessThanOrEquals", "attribute": "probability", "value": 100}` |
+
+## Null & Boolean
+
+| Type | Notes |
+|---|---|
+| `isNull` | No `value` needed |
+| `isNotNull` | No `value` needed |
+| `isTrue` | Boolean field check |
+| `isFalse` | Boolean field check |
+
+## String Matching
+
+| Type | Value | Behavior |
+|---|---|---|
+| `contains` | string | `%value%` |
+| `notContains` | string | NOT `%value%` |
+| `startsWith` | string | `value%` |
+| `endsWith` | string | `%value` |
+| `like` | string | Raw LIKE pattern (use `%` wildcards) |
+| `notLike` | string | Raw NOT LIKE pattern |
+
+## Set Membership
+
+| Type | Value |
+|---|---|
+| `in` | array of strings/numbers: `["New", "Assigned"]` |
+| `notIn` | array of strings/numbers: `["Canceled", "Recycled"]` |
+
+## Relationship Filters
+
+| Type | Value | Notes |
+|---|---|---|
+| `linkedWith` | array of IDs | Records linked to ANY of the given IDs |
+| `notLinkedWith` | array of IDs | Records NOT linked to any of the given IDs |
+| `isLinked` | — | Has at least one linked record |
+| `isNotLinked` | — | Has no linked records |
+
+## Date/Time Helpers
+
+No `value` needed unless noted:
+
+| Type | Notes |
+|---|---|
+| `today` | |
+| `past` | |
+| `future` | |
+| `lastSevenDays` | |
+| `currentMonth` | |
+| `lastMonth` | |
+| `currentQuarter` | |
+| `currentYear` | |
+| `lastXDays` | `value`: number of days |
+| `nextXDays` | `value`: number of days |
+| `between` | `value`: `["YYYY-MM-DD", "YYYY-MM-DD"]` |
+
+## Logical Combinators
+
+Multiple items in the `where` array are implicitly **ANDed**.
+
+For OR logic, wrap in a combinator:
+```json
+{"type": "or", "value": [
+  {"type": "equals", "attribute": "status", "value": "New"},
+  {"type": "equals", "attribute": "status", "value": "Assigned"}
+]}
+```
+
+Combinators nest: `and` and `or` can contain other combinators.

package/plugins/ima-claude/skills/functional-programmer/SKILL.md

@@ -158,6 +158,21 @@ Every abstraction has a cost:
 
 **The question to ask:** Does this abstraction pay for itself? Will I use it enough to justify the cost? Would a junior developer understand it?
 
+### File Size as a Smell
+
+Keep files under 500 lines. This isn't an arbitrary limit — it's a smell detector. A file approaching 500 lines almost certainly has multiple responsibilities that should be separated.
+
+**When a file grows too large:**
+- Split by responsibility, not by arbitrary line count
+- A 300-line file with two unrelated concerns is worse than a 480-line file with one
+- The goal is cohesion: each file should have a single, clear reason to exist
+
+**Why this matters:**
+- Readability: Developers can hold one file's purpose in their head
+- Testability: Smaller, focused files are easier to test in isolation
+- Navigation: Finding what you need is faster in a well-structured codebase
+- Review: Code review quality drops sharply beyond 500 lines
+
 ### Context-Appropriate Complexity
 
 A CLI script has different needs than a production API.