ima-claude 2.16.0 → 2.20.0

package/plugins/ima-claude/skills/design-to-code/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: design-to-code
+description: "Convert design screenshots into working WordPress code through a two-phase workflow. Phase A: analyze screenshots + Jira context → detailed implementation prompt. Phase B: execute prompt → PHP/SCSS code via agent delegation. Use when: user provides design screenshots, says 'implement this design,' 'design to code,' 'convert this mockup,' or has screenshots to turn into WordPress code. Also use when user has an existing implementation prompt to execute. Requires opus for orchestration. Delegates to wp-developer for code generation. Always load ima-brand alongside."
+---
+
+# Design to Code
+
+Orchestrate the transformation of design screenshots into working WordPress code. Two phases, one skill — produce the implementation prompt (Phase A), then execute it (Phase B).
+
+You are the orchestrator. You analyze designs, compose prompts, delegate implementation, and verify results. You do NOT implement directly — you delegate to `ima-claude:wp-developer` agents.
+
+---
+
+## Mode Selection
+
+Determine the mode from the user's input:
+
+```
+What did the user provide?
+├── Screenshots/mockups (no existing prompt)
+│   → Phase A: Design → Prompt
+│   → Read references/phase-a-design-to-prompt.md
+│
+├── An existing implementation prompt
+│   → Phase B: Prompt → Code
+│   → Read references/phase-b-prompt-to-code.md
+│
+└── Screenshots + "implement this" / "full pipeline"
+    → Phase A then Phase B in sequence
+    → Phase A produces prompt → user reviews → Phase B executes
+```
+
+---
+
+## Required Skills
+
+Always load alongside this skill:
+- **`ima-brand`** — color palette, typography, mixins (needed for both phases)
+- **`ima-bootstrap`** — utility classes, grid system, components
+
+Phase B additionally needs:
+- **`php-fp-wordpress`** — WordPress development patterns, security, shortcodes
+
+---
+
+## Phase A: Design → Prompt
+
+Transform design screenshots into a detailed, section-by-section implementation prompt. Output: a ~200-300 line prompt file matching the team's established template structure.
+
+Before starting, search Qdrant for `design-to-prompt` to recall prior lessons.
+
+### Steps (read `references/phase-a-design-to-prompt.md` for detailed procedures)
+
+1. **GATHER** — Fetch Jira context + receive screenshots + explore codebase (parallel)
+2. **ANALYZE** — Load brand palette from `ima-brand` (**must complete before COMPOSE**)
+3. **CROP** — Full view → section detection → detail crops (iterative PIL cropping)
+4. **EXTRACT** — Per crop: exact text, icons, colors, layout, spacing
+5. **MAP** — Visual elements → brand variables, components → existing shortcodes
+6. **COMPOSE** — Write prompt using `references/prompt-template.md` structure
+7. **VALIDATE** — Re-check each section against its crop for accuracy
+
+**Output**: Save prompt to `docs/designs/{ticket}/PROMPT.md` and Serena memory as `{feature-name}-plan`.
+
+After Phase A, present the prompt to the user. Stop here unless running full pipeline.
+
+---
+
+## Phase B: Prompt → Code
+
+Execute an implementation prompt to produce working WordPress code. Input: a structured prompt (from Phase A or user-provided).
+
+Before starting, search Qdrant for `design-to-code` to recall prior lessons.
+
+### Steps (read `references/phase-b-prompt-to-code.md` for detailed procedures)
+
+1. **RESEARCH** — Brand SCSS files + current code + component libraries (parallel explorers)
+2. **ARCHITECTURE** — New file vs modify, function reuse, component migration decision
+3. **DECOMPOSE** — Stories by page section; Story 1 = foundation, Stories 2-N = parallel fills, final = polish
+4. **IMPLEMENT** — Delegate to `ima-claude:wp-developer` per story with precise prompts
+5. **REVIEW** — Verify copy, colors, element order, asset paths (orchestrator review before visual test)
+6. **VISUAL-QA** — Compile SASS → screenshot desktop + mobile → compare to design → iterate
+
+---
+
+## Critical Guardrails
+
+Read `references/guardrails.md` for the complete set. The top 5 (each learned from a real failure):
+
+1. **Never hardcode colors** — always brand SCSS variables or Bootstrap utilities
+2. **Always verify asset paths exist** — Glob/grep before referencing; check existing usage patterns
+3. **Always provide exact copy text** — never let agents paraphrase; include verbatim text in quotes
+4. **Load brand palette BEFORE composition** — informs every color reference on first pass
+5. **Check site header/footer first** — don't build custom components that duplicate existing site elements
+
+---
+
+## Agent Delegation Model
+
+| Role | Agent | When |
+|---|---|---|
+| Orchestrator | opus (you) | All phases — research, planning, decomposition, delegation, review, surgical fixes |
+| Codebase explorer | `ima-claude:explorer` (haiku) | GATHER/RESEARCH: find existing shortcodes, templates, SCSS files |
+| Implementer | `ima-claude:wp-developer` (sonnet) | IMPLEMENT: write PHP/SCSS with skills: ima-brand, ima-bootstrap, php-fp-wordpress |
+| Reviewer | `ima-claude:reviewer` (sonnet, read-only) | REVIEW: brand compliance + accessibility audit (for larger implementations) |
+
+Orchestrator does surgical fixes (<5 lines) directly via Edit tool. Anything larger → delegate to wp-developer.
+
+---
+
+## Qdrant Integration
+
+Before each phase, search Qdrant for prior lessons:
+- Phase A: `qdrant_find("design-to-prompt workflow")` — retrieves methodology, cropping techniques, composition decisions
+- Phase B: `qdrant_find("design-to-code implementation")` — retrieves decomposition patterns, delegation templates, QA patterns
+
+---
+
+## Related Skills
+
+| Skill | Relationship |
+|---|---|
+| `ima-brand` | Required — color palette, typography, mixins |
+| `ima-bootstrap` | Required — utility classes, grid, components |
+| `php-fp-wordpress` | Required for Phase B — WordPress dev patterns |
+| `task-master` | Optional — for complex multi-page designs needing Epic > Story > Task decomposition |
+| `prompt-starter` | Pattern borrowed — Phase A follows its "builder not executor" philosophy |

package/plugins/ima-claude/skills/design-to-code/references/guardrails.md

@@ -0,0 +1,46 @@
+# Guardrails — Lessons from Real Failures
+
+Every rule here was learned from a specific failure during the FNR-2785 implementation. Prevention strategies are included so the same mistakes don't recur.
+
+---
+
+## Color
+
+- **Never hardcode hex values** in SCSS or inline styles. Every color must come from `$ima-brand-*` SCSS variables or Bootstrap `.text-*` / `.bg-*` utility classes.
+- **Load the brand palette BEFORE composing the prompt or writing code.** Doing this after means an expensive editing pass to replace color descriptions with variable names.
+- **Decorative category colors are the exception** — colors that serve UI categorization (not brand identity) can use explicit hex values. Example: pink for "Family Medicine" chip icons.
+- **Final check**: `rg '#[0-9a-fA-F]{3,6}' --type php --type scss` should return zero matches in new code.
+
+## Copy
+
+- **Always provide exact text in quotes.** "Search our directory of ethics-committed physicians dedicated to honest, patient-first care." — not a paraphrase like "Search our curated network of independent practitioners."
+- **Agents WILL paraphrase** descriptive text unless given the exact copy. This is the most common failure mode.
+- **If text is unclear in the screenshot**, flag it with `[VERIFY: exact text unclear from screenshot]` rather than guessing.
+- **Include ALL text** — headings, subheadings, body copy, button labels, placeholder text, tooltip text. If it's visible in the design, it goes in the prompt.
+
+## Assets
+
+- **Verify every asset path exists** before referencing it in code. Use `Glob` or `rg` to find existing usage.
+- **Never assume local file paths.** Logos may be served from CDN, uploads directory, or rendered via a filter. Grep for existing usage patterns (e.g., `ima_ui_footer_logo_url`).
+- **Check the existing icon system** before introducing new icon dependencies. If the site uses Font Awesome, use Font Awesome — don't mix Bootstrap Icons into FA sites.
+
+## Architecture
+
+- **Check if site header/footer already provides the element.** Design screenshots show the final composite — the nav bar in the design may BE the standard site header via `get_header()`, not a custom inline nav. Building a custom one creates a duplicate.
+- **Preserve existing backend logic.** Design changes are presentation-layer only. Search logic, API endpoints, pure functions, sorting, pagination — these do NOT change unless explicitly stated.
+- **Bootstrap utility first, custom SCSS only when Bootstrap cannot express the style.** Check the hierarchy: Bootstrap utility → IMA brand mixin → Bootstrap variable override → then custom CSS.
+- **Evaluate component libraries before implementing.** Check ima-forms, ima-ui-components for existing patterns. Decide based on feature support, not preference. Document the decision.
+
+## Spatial Relationships
+
+- **Be explicit about element order** in prompts. "Left to right: social icons → logo" — agents don't reliably interpret spatial relationships from screenshots.
+- **Specify flex direction and alignment** when order matters: `d-flex flex-row` vs `flex-row-reverse`.
+- **For stacked layouts**, specify top-to-bottom order explicitly.
+
+## Verification
+
+- **Run `php -l` after every PHP change.** Syntax errors caught early prevent cascading debugging.
+- **Recompile SASS before ANY visual testing.** New SCSS imports don't auto-apply. Run `ddev wp ima-scss compile` and verify new classes appear in `bundle.css`.
+- **Screenshot at both desktop and mobile widths.** Desktop (1920px) and mobile (375px) catch different categories of issues.
+- **Grep for hardcoded hex values** as a final check. New code should reference only brand variables.
+- **Verify existing functionality** still works after changes — search, filters, pagination, form submissions.

package/plugins/ima-claude/skills/design-to-code/references/phase-a-design-to-prompt.md

@@ -0,0 +1,141 @@
+# Phase A: Design → Prompt — Detailed Procedure
+
+Transform design screenshots into a structured implementation prompt. This phase requires opus-level judgment for visual analysis, brand mapping, and prompt composition.
+
+**Steps**: [1. GATHER](#step-1-gather-parallel) → [2. ANALYZE](#step-2-analyze-brand-palette-loading) → [3. CROP](#step-3-crop-iterative-image-analysis) → [4. EXTRACT](#step-4-extract-per-crop) → [5. MAP](#step-5-map-visual--technical) → [6. COMPOSE](#step-6-compose) → [7. VALIDATE](#step-7-validate)
+
+---
+
+## Step 1: GATHER (Parallel)
+
+Run three parallel streams:
+
+### Stream 1: Jira Context
+- Fetch issue via mcp-atlassian (`getJiraIssue`)
+- Extract: summary, description, acceptance criteria, linked issues
+- Read ALL comments — stakeholder requirements often hide in comment threads, not the description
+- Note attachment metadata (screenshot filenames, dimensions)
+
+### Stream 2: Screenshots
+- Receive screenshots from user or download from Jira attachments
+- Save to `docs/designs/{ticket}/` directory
+- Note image dimensions — tall images (>2000px) will need cropping
+
+### Stream 3: Codebase Exploration
+- Dispatch `ima-claude:explorer` agent to map:
+  - Current template file and shortcodes
+  - Existing helper/render functions (signatures and return types)
+  - SCSS file structure (partials, variables, existing page styles)
+  - Page template chain (`get_header()` → content → `get_footer()`)
+- Key question: What exists today that the redesign must preserve?
+
+---
+
+## Step 2: ANALYZE (Brand Palette Loading)
+
+**This step MUST complete before Step 6 (COMPOSE).** Loading the palette first means every section gets correct brand variable references on the first pass — avoiding an expensive editing pass afterward.
+
+- Load `ima-brand` skill for the complete palette
+- Create a working color mapping table:
+
+```
+| Visual Element | Brand Variable | Hex | Bootstrap Utility |
+|---|---|---|---|
+| Dark blue headers | $ima-brand-primary | #00066F | .text-primary |
+| Teal buttons/CTAs | $ima-brand-secondary | #00B8B8 | .text-secondary, .bg-secondary |
+| Gold accents | $ima-brand-gold | #FFCC00 | .text-ima-gold |
+| Light backgrounds | $ima-brand-gray-light | #F2F3F5 | .bg-light |
+```
+
+- Inventory available brand mixins: `@include ima-gradient-bg`, `@include ima-card-white`, `@include ima-button-primary`, etc.
+
+---
+
+## Step 3: CROP (Iterative Image Analysis)
+
+Full-image views lose critical detail — text becomes unreadable, subtle elements get missed. Use iterative cropping:
+
+### Pass 1: Full-image overview
+- View each screenshot at full size
+- Identify section boundaries (background changes, whitespace gaps, visual groupings)
+- Identify page states (e.g., landing vs results, empty vs populated)
+
+### Pass 2: Section crops (6-8 per image)
+- Use Python PIL to crop each section:
+```python
+from PIL import Image
+img = Image.open('screenshot.png')
+# Overlap sections by ~100px to avoid missing content at boundaries
+section = img.crop((0, start_y, width, end_y))
+section.save(f'section-{name}.png')
+```
+- Name crops descriptively: `hero-section.png`, `search-form.png`, `discover-cards.png`
+
+### Pass 3: Detail crops (targeted)
+- After viewing section crops, identify areas too small for text extraction
+- Crop individual components: single cards (~450x360px), form fields, badge legends
+- Crop text areas for exact copy extraction
+
+---
+
+## Step 4: EXTRACT (Per Crop)
+
+For each section/detail crop, extract:
+
+- **Text content** — exact wording in quotes. "Discover Providers Who Share Your Values" not "Find providers who share your values"
+- **Icons** — identify by library and class name (e.g., `fa-regular fa-stethoscope`). If uncertain, use "fa-regular fa-stethoscope or similar" pattern
+- **Colors** — note approximate hex values for mapping in Step 5
+- **Layout** — describe grid structure (e.g., "3-column on desktop, stacked on mobile")
+- **Interactive behavior** — specify URL params, form actions, click targets. Bridge design → engineering by documenting function, not just appearance
+
+---
+
+## Step 5: MAP (Visual → Technical)
+
+Translate visual elements to technical references:
+
+| Visual | Technical |
+|---|---|
+| Colors | Brand SCSS variables (`$ima-brand-primary`) |
+| Components | Existing shortcode names (`[ima_directory_filters]`) |
+| Icons | FontAwesome/Bootstrap Icons classes (`fa-regular fa-search`) |
+| Layout | Bootstrap grid classes (`col-lg-4 col-md-6`) |
+| Spacing | Bootstrap utilities (`py-5`, `mb-4`) or brand scale |
+
+For redesigns: explicitly document which existing functions to reuse vs rebuild.
+
+---
+
+## Step 6: COMPOSE
+
+Read `references/prompt-template.md` for the template structure. Write the prompt section-by-section:
+
+### Structure conventions
+- **Named sections** over numbered: "Header Section", "Search Form" not "Section 01"
+- **State annotations** on every section: `(Both States)`, `(Landing Only)`, `(Results Only)`
+- **Exact text in quotes** — never describe text, provide it verbatim
+- **Brand variables inline** — `$ima-brand-secondary` not "teal"
+- **Bootstrap classes inline** — `.text-primary`, `.bg-light`
+
+### For redesigns
+- Add a **"What Changes vs What Stays"** section at the top
+- Explicitly list what NOT to modify (backend logic, API, pure functions)
+- Frame component migration as a decision point with criteria, not a directive
+
+### For multi-state pages
+- Document each state separately with clear annotations
+- Shared elements get `(Both States)` annotation
+
+---
+
+## Step 7: VALIDATE
+
+Before presenting to the user:
+
+1. Re-read each prompt section
+2. Compare against the corresponding crop
+3. Verify: exact text match, correct brand variables, correct element order, no missing elements
+4. Check all referenced file paths exist in the codebase
+5. Ensure the "What Changes vs What Stays" section is accurate
+
+Save the completed prompt to `docs/designs/{ticket}/PROMPT.md` and Serena memory.

package/plugins/ima-claude/skills/design-to-code/references/phase-b-prompt-to-code.md

@@ -0,0 +1,155 @@
+# Phase B: Prompt → Code — Detailed Procedure
+
+Execute a structured implementation prompt to produce working WordPress code. This phase delegates to `ima-claude:wp-developer` agents and reviews their output.
+
+**Steps**: [1. RESEARCH](#step-1-research-parallel-explorers) → [2. ARCHITECTURE](#step-2-architecture-decisions-before-code) → [3. DECOMPOSE](#step-3-decompose-stories-by-section) → [4. IMPLEMENT](#step-4-implement-agent-delegation) → [5. REVIEW](#step-5-review-before-visual-test) → [6. VISUAL-QA](#step-6-visual-qa)
+
+---
+
+## Step 1: RESEARCH (Parallel Explorers)
+
+Dispatch `ima-claude:explorer` agents in parallel to gather:
+
+### Explorer 1: Brand System
+- Read `_variables.scss` — complete color palette, font stack, spacing scale
+- Read `_mixins.scss` — available brand mixins and their parameters
+- Read `_theme_variables.scss` — Bootstrap variable overrides
+- Summarize: what Bootstrap utilities map to brand colors
+
+### Explorer 2: Current Implementation
+- Read the template file being modified (or closest existing template)
+- Inventory existing shortcodes: names, parameters, what they return
+- Read existing helper/render functions — signatures, return types, reuse candidates
+- Check page template chain: what does `get_header()` provide? What does `get_footer()` provide?
+
+### Explorer 3: Component Libraries (if applicable)
+- Check ima-forms: does it support the form patterns needed? (icons in inputs, custom dropdowns)
+- Check ima-ui-components: any reusable components?
+- Evaluate migration: use existing library or raw HTML + Bootstrap?
+
+---
+
+## Step 2: ARCHITECTURE (Decisions Before Code)
+
+Document these decisions before proceeding:
+
+1. **New file vs modify existing?** — New shortcode file for redesigns avoids merge conflicts during development
+2. **Function reuse** — List exact functions to call (not duplicate). Include signatures:
+   ```
+   ima_directory_get_filter_options() → ['specialties' => [...], 'states' => [...]]
+   ima_directory_search($params) → WP_Query results
+   ```
+3. **Component migration** — Use existing library or raw HTML? Decide based on feature support, not preference
+4. **Page template changes** — Does the page template need modification, or just the shortcode?
+5. **State management** — What's shared between page states vs state-specific?
+
+---
+
+## Step 3: DECOMPOSE (Stories by Section)
+
+Break the prompt into implementation stories. Follow the foundation-first pattern:
+
+### Story 1: Foundation (no dependencies)
+- Create the file (PHP shortcode + SCSS partial)
+- Main orchestrator function with state detection
+- Placeholder calls for each section
+- SCSS import in `_custom.scss`
+- `require_once` in `functions.php`
+
+### Stories 2-N: Section Fills (parallelizable)
+- Group by page state when applicable:
+  - Landing state sections (one story)
+  - Results state sections (one story)
+  - Shared sections (one story)
+- Each story fills placeholder slots from Story 1
+- Stories touching independent insertion points run in parallel
+
+### Final Story: Polish
+- Animation and transitions (progressive enhancement — static first)
+- Responsive refinements
+- Accessibility review
+- Visual QA
+
+### Parallelization Rules
+- Stories with independent insertion points → run in parallel
+- Stories sharing the same function/placeholder → run sequentially
+- Story 1 must complete before all others (creates the file structure)
+- Polish story runs last (needs all sections in place)
+
+---
+
+## Step 4: IMPLEMENT (Agent Delegation)
+
+Delegate each story to `ima-claude:wp-developer`. Each agent prompt MUST include:
+
+### Required Prompt Elements
+1. **Task identity** — Story number, section name, where it fits in the page
+2. **File context** — Exact file paths, line numbers to modify, current state of the code
+3. **HTML structure** — Specific elements with Bootstrap classes, not "create a search form" but:
+   ```
+   Row 1: Full-width input with fa-magnifying-glass icon
+     - Placeholder: "Keyword search (e.g. name, specialty, or city...)"
+   Row 2: 3 equal-width dropdowns (col-12 col-md-4)
+   ```
+4. **Brand color mapping** — Exact variable names for every color used in this section
+5. **Existing functions to reuse** — Function names, signatures, return values
+6. **What NOT to do** — Guardrails specific to this story
+7. **Verification step** — `php -l` on the PHP file after changes
+
+### Anti-patterns
+- "Implement the discover section" → too vague, inconsistent results
+- "Make it look like the screenshot" → agent can't see screenshots
+- "Use appropriate colors" → must specify exact variable names
+- Omitting existing function signatures → agent will reinvent them
+
+---
+
+## Step 5: REVIEW (Before Visual Test)
+
+The orchestrator reviews each agent's output BEFORE visual testing. This catches most issues faster than visual → fix → retest cycles.
+
+### Review Checklist
+1. **Exact copy** — Diff generated text against prompt's quoted text. Agents paraphrase.
+2. **Element order** — Compare DOM order to prompt's section order. Spatial relationships get reversed.
+3. **URL paths** — Verify every href matches the prompt spec. Agents default to common paths (`/join/` instead of `/register/`)
+4. **Asset paths** — Glob to verify every referenced image/icon path exists. Grep for existing usage patterns.
+5. **Color compliance** — Grep for hardcoded hex values (should be zero — all brand variables)
+6. **Function reuse** — Verify agents called existing functions instead of reimplementing
+
+### Fixing Issues
+- <5 lines: Orchestrator fixes directly via Edit tool (faster than re-delegating)
+- Larger issues: Re-delegate to wp-developer with specific correction instructions
+
+---
+
+## Step 6: VISUAL-QA
+
+### Step 0: Compile SASS (before anything else)
+New SCSS won't appear until compiled. Verify new classes exist in `bundle.css` before testing.
+```
+ddev wp ima-scss compile
+```
+
+### Desktop Testing
+1. Navigate to page in chrome-devtools
+2. Full-page screenshot at 1920px width (landing state)
+3. Full-page screenshot (results state with search params)
+4. Viewport screenshots of specific sections as needed
+
+### Mobile Testing
+1. Emulate mobile device (390x844, 2x DPR, touch)
+2. Screenshot both page states
+3. Verify responsive stacking (single-column layout)
+
+### What to Check
+- Gradient rendering
+- Card floating/overlap effects
+- Color matches (brand colors, not approximations)
+- Text content matches design exactly
+- Icons correct (FA vs BI, regular vs solid weight)
+- Responsive stacking on mobile
+- Interactive elements visible and clickable
+- Sticky/fixed elements behave correctly
+
+### Iteration
+Compare screenshots against original design. Note discrepancies, fix via Edit or re-delegate, re-screenshot until acceptable. Usually 1-2 iteration rounds.

package/plugins/ima-claude/skills/design-to-code/references/prompt-template.md

@@ -0,0 +1,95 @@
+# Implementation Prompt Template
+
+This is the template structure for Phase A output. Fill in the bracketed placeholders with extracted design data. Delete sections that don't apply.
+
+---
+
+```markdown
+/task-master [One-line goal as a user story]
+Save this prompt and plan to Serena memory as `{feature-name}-plan`.
+
+## Context
+
+- **Page URL**: [current URL of the page being built/redesigned]
+- **Design files**: [paths to screenshots in docs/designs/{ticket}/]
+- **Related pages**: [URLs of pages with shared components or navigation]
+- **Branding reference**: Load `ima-brand` skill for color palette and typography
+- **Bootstrap reference**: Load `ima-bootstrap` skill for utility classes and grid
+- **Existing code**: [paths to current shortcode files, SCSS partials, page templates]
+
+## What Changes vs What Stays
+
+> Include this section for redesigns. Omit for greenfield pages.
+
+**Changes** (presentation layer only):
+- [List specific files/functions that will be modified]
+
+**Stays unchanged** (do not modify):
+- [List backend logic, APIs, pure functions, search/filter logic]
+- [List existing shortcodes that continue to work as-is]
+
+## Plan
+
+### [Section Name] ([State Annotation])
+
+> State annotations: (Both States), (Landing State Only), (Results State Only)
+> Repeat this block for each visual section of the page.
+
+**Layout**: [grid description — e.g., "full-width container, 3-column card grid on lg, stacked on mobile"]
+**Background**: [brand variable — e.g., "$ima-brand-primary" or "@include ima-gradient-bg"]
+
+**Text**:
+- Heading: "[exact heading text]" — `h2`, `.text-primary`, `fw-bold`
+- Subheading: "[exact subheading text]" — `p`, `.text-white`, `mx-auto`
+- Body: "[exact body copy]" — `p`, `.text-muted`
+
+**Elements** (left to right, top to bottom):
+- [element description] — [Bootstrap classes] — [icon: `fa-regular fa-icon-name`]
+- [element description] — [href: /path/to/page]
+- [element description] — [existing function: `ima_function_name()`]
+
+**SCSS needed**:
+- [Custom SCSS rules — only what Bootstrap utilities can't express]
+- [Reference brand mixins: `@include ima-card-white`]
+
+**Notes**: [animation as progressive enhancement, conditional display logic, accessibility considerations]
+
+## Implement
+
+1. Create/modify [file path] — [what to add: main shortcode, orchestrator function, state detection]
+2. Create/modify [SCSS file path] — [what to add: page-specific styles, import in _custom.scss]
+3. [Additional file changes in priority order]
+
+**Branch strategy**: `feature/{ticket}-{short-description}`
+**Approach**: Mobile-first, progressive enhancement. Static layout first, animation as enhancement.
+
+## Test
+
+- [ ] `php -l` on all modified PHP files
+- [ ] SCSS compiles without errors (`ddev wp ima-scss compile`)
+- [ ] Desktop screenshot matches design at 1920px (landing state)
+- [ ] Desktop screenshot matches design at 1920px (results state)
+- [ ] Mobile screenshot matches design at 375px (both states)
+- [ ] All links resolve to valid paths
+- [ ] No hardcoded color values (`rg '#[0-9a-fA-F]{3,6}' --type php --type scss`)
+- [ ] Existing functionality preserved (search, filters, pagination)
+
+## Review
+
+- `ima-claude:reviewer` for brand compliance + accessibility audit
+- Verify exact copy matches design screenshots
+- Verify element order matches design
+- Check responsive behavior at all breakpoints
+
+## Document
+
+- [ ] Update Jira ticket with implementation notes
+- [ ] Save session to Serena memory as `{feature-name}-implementation`
+- [ ] Update component inventory if new shortcodes were created
+
+## Agents
+
+- `ima-claude:explorer` (haiku) — parallel codebase research
+- `ima-claude:wp-developer` (sonnet) — PHP/SCSS implementation with skills: `ima-brand`, `ima-bootstrap`, `php-fp-wordpress`
+- `ima-claude:reviewer` (sonnet, read-only) — brand compliance after implementation
+```

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 |