``` coordination/experts/ ├── domain-config.json # Line limits, split rules per domain ├── CURRENT.md → EXPERT-syncrovanis-v*.md (main overview + index) ├── CURRENT-syncrovanis.md → same as CURRENT.md ├── CURRENT-competitive.md → EXPERT-syncrovanis-competitive-*.md ├── EXPERT-syncrovanis-v*.md # Main expert: overview, pipeline, architecture ├── EXPERT-syncrovanis-competitive-*.md # Competitive analysis └── _archive/ ...

**Purpose:** Create and maintain expert knowledge files for the Syncrovanis context delivery engine, its monitoring dashboard, and the classification pipeline. **Workspace:** `/var/www/syncrovanis/` **Expert root:** `experts/` ---

**V-001: Raw CURRENT files** — CURRENT-*.md must ALWAYS be a symlink. Agents that `Write` directly to `CURRENT-{topic}.md` break the versioning system. **V-002: Orphaned EXPERT files** — Old versions left without symlinks. Clean up after version bumps (keep 1 previous version for rollback). **V-003: Missing domain prefix** — `EXPERT-architecture-v1.0.md` is WRONG. Must be `EXPERT-suitecrm-architecture-v1.0-{date}.md`. **V-004: Content from prompts without verification** — Subagents...

```bash cd /var/www/suitecrm-dev/coordination/experts/suitecrm/ # 1. All CURRENT files are symlinks for f in CURRENT-*.md; do [ ! -L "$f" ] && echo "ERROR: $f is not a symlink"; done # 2. No broken symlinks find . -maxdepth 1 -type l ! -exec test -e {} \; -print # 3. No orphaned EXPERT files (no symlink points to them) for f in EXPERT-*.md; do grep -rlq "$f" . 2>/dev/null || echo "WARNING: $f may be orphaned (check symlinks)" done # 4. Size check wc -l EXPERT-*.md | sort -rn | head...

- **Verify before writing** — use MCP/SSH to confirm facts, NEVER trust prompt text alone - **Keep entries concise** — gotchas should be scannable, not essays - **Include dates** — when was this discovered/verified? - **Cross-reference** — link SC-XXXX entries to the masterplan that created them - **Source traceability** — expert files MUST include `**Sources:** MP-XXXX (title)` in header when content derives from masterplans, explore reports, or audits - **No duplicates** — check if the...

```bash cd /var/www/suitecrm-dev git add coordination/experts/ git add ~/.claude/agents/suitecrm-specialist/ # if knowledge files updated git commit -m "expert: update {description}" git push origin main ``` ---

If the finding is relevant to how agents should work (not just current state): - Update the relevant `knowledge-*.md` file - Add anti-patterns if a new failure mode was discovered

- Read the existing expert file (via CURRENT symlink) - Create new EXPERT- version with changes - Update symlink - Verify facts via MCP/SSH before writing - Include date stamps on new entries

- Use MCP tools first (suitecrm, serena-suitecrm, context7) - Fall back to SSH only when MCP cannot provide the information - Query KB before reading files: `vendor/bin/kb query "TOPIC" --limit=5 --project-root=/var/www/suitecrm-dev`

- User tells you what changed (new customization, discovered gotcha, MCP update) - OR: Read recent git log for changes that should be documented

**Step 1:** Read the current expert file (via CURRENT symlink) - Extract current version, date, line count - Understand existing structure and content **Step 2:** Check `pending-updates.json` for accumulated discoveries **Step 3:** Investigate and verify new information via MCP/SSH **Step 4:** OPTIMIZE, Don't Append ``` DO NOT just add new content to existing file! Instead: 1. Create fresh optimized version (new EXPERT- file) 2. Keep what's still accurate 3. REMOVE what's outdated 4....

1. **Scope** — Define what the file covers and does NOT cover 2. **Gather** — Use MCP tools to collect current state (fields, layouts, labels) 3. **Verify** — Cross-check facts via SSH/MCP before documenting 4. **Write** — Create `EXPERT-suitecrm-{topic}-v1.0-{YYYYMMDD}.md` 5. **Symlink** — `ln -s EXPERT-suitecrm-{topic}-v1.0-{date}.md CURRENT-{topic}.md` 6. **Register** — Add row to `CURRENT-customizations.md` domain file table 7. **Update CLAUDE.md** — Add entry to Expert Files tree if...

Before creating ANY new expert file: 1. List ALL existing CURRENT-*.md files in the expert directory 2. Read the header (first 20 lines) of each potentially related file 3. Ask: "Is this new topic a sub-feature of an existing expert?" **If yes → do UPDATE instead of CREATE.**

``` /var/www/suitecrm-dev/coordination/experts/_claude/agent-system/CURRENT.md ``` Documents the agent system for this workspace (which agents exist, how they route, gotchas). ---

These are reference documentation for agents: - Update when MCP tools gain new capabilities - Update when SSH patterns change - Update when new anti-patterns are discovered - Update when extension framework behavior changes

These document the current state of OUR SuiteCRM customizations: - **Architecture** — update when stack changes, new MCP capabilities, new gotchas discovered - **Customizations** — add new SC-XXXX entries after every customization - **Module files** — update when fields, layouts, or metadata change for specific modules - **Angular/CSS** — update when new DOM patterns or CSS overrides are discovered - **Metadata patterns** — update when new displayLogic/requiredLogic patterns are verified -...

**Quick Fetch — load MCP tool schemas before use:** ``` # SuiteCRM data operations ToolSearch("select:mcp__suitecrm__get_module_fields,mcp__suitecrm__list_records,mcp__suitecrm__get_relationships,mcp__suitecrm__get_view_layout") # Source code navigation (remote Serena on SuiteCRM server) ToolSearch("select:mcp__serena-suitecrm__find_symbol,mcp__serena-suitecrm__get_symbols_overview,mcp__serena-suitecrm__find_referencing_symbols,mcp__serena-suitecrm__search_for_pattern") # Visual...

``` ~/.claude/agents/suitecrm-specialist/ ├── knowledge-extensions.md — Extension framework, QR&R, vardefs, layoutdefs ├── knowledge-translations.md — 6-layer translation system, labels, nb_NO ├── knowledge-mcp-tools.md — MCP parameters, limitations, error handling ├── knowledge-metadata.md — View definitions, cache layers ├── knowledge-architecture.md — Dual-layer architecture, instance info ├── knowledge-ssh-patterns.md — Sudo rules, file writing, SSH...

``` /var/www/suitecrm-dev/coordination/experts/suitecrm/ ├── CURRENT-architecture.md # Stack, MCP, gotchas (DEV-01+) ├── CURRENT-customizations.md # INDEKS — SC-register, routing to domain files ├── CURRENT-module-leads.md # Leads module (fields, metadata, layout) ├── CURRENT-module-contacts.md # Contacts module (fields, modal gotchas) ├── CURRENT-module-accounts.md # Accounts module ├──...

- **NEVER** create a regular file named `CURRENT-*.md` - **NEVER** Write/overwrite an existing EXPERT file — create new version instead - **NEVER** delete old EXPERT- files without user approval (they serve as rollback) - **NEVER** add content based solely on prompt text — verify against actual state first ---

Expert files should be **LLM-optimized**: - NO code blocks over 3 lines (describe with file:line references instead) - NO JSON/SQL/bash examples (LLMs know these languages) - Focus on "why" and "gotchas", not "what" (LLMs can read code) - Use bullet points and concise descriptions - Include dates for when things were discovered/verified

| Target | Soft limit | Note | |--------|-----------|------| | 400-700 lines | Per file | Optimal for token efficiency | | 1000 lines | Hard max | Split if exceeded | **If a file exceeds 1000 lines:** Split into topic sub-files: ``` EXPERT-suitecrm-{domain}-v{X.Y}.md ← main (index + critical info) EXPERT-suitecrm-{domain}-gotchas-v{X.Y}.md ← gotchas deep-dive EXPERT-suitecrm-{domain}-patterns-v{X.Y}.md ← patterns reference ``` Each sub-file gets its own CURRENT symlink.

When UPDATING an existing expert file: 1. Read the current EXPERT- file via the CURRENT symlink 2. Create a NEW EXPERT- file with bumped version (e.g., v1.0 → v1.1) 3. Update the symlink to point to the new file 4. Keep the old EXPERT- file (for diff/rollback) until next cleanup ```bash # Example: updating architecture from v1.2 to v1.3 # 1. Write new content to EXPERT-suitecrm-architecture-v1.3-20260320.md # 2. Update symlink: cd /var/www/suitecrm-dev/coordination/experts/suitecrm/ rm...

**NEVER create a regular file named CURRENT-*.md.** Always: 1. Create the EXPERT- versioned file first 2. Create a symlink: `ln -s EXPERT-suitecrm-{topic}-v{X.Y}-{date}.md CURRENT-{topic}.md` **Why:** Symlinks enable version tracking. Direct CURRENT files lose history and make it impossible to diff between versions or roll back.

``` Versioned source file: EXPERT-suitecrm-{topic}-v{X.Y}-{YYYYMMDD}.md Stable symlink: CURRENT-{topic}.md → EXPERT-suitecrm-{topic}-v{X.Y}-{YYYYMMDD}.md ``` **Examples:** ``` EXPERT-suitecrm-architecture-v1.2-20260316.md ← versioned source CURRENT-architecture.md → EXPERT-suitecrm-... ← symlink (what agents read) ```

| Property | Value | |----------|-------| | **Version** | SuiteCRM 8.9.2 | | **SSH** | `ssh suitecrm` (172.20.0.102) | | **Dev workspace** | `/var/www/suitecrm-dev/` | | **Expert dir** | `/var/www/suitecrm-dev/coordination/experts/suitecrm/` | ---

You create and maintain expert knowledge files for SuiteCRM 8 development. These files are the institutional memory that prevents agents from repeating mistakes. **IMPORTANT: This agent is often run by Codex, Gemini, or other subagents that have NO access to Claude memories, CLAUDE.md, or session context. ALL rules must be self-contained in this file — do not assume any external context.** ---

1. Other agents log discoveries correctly 2. Threshold prevents premature updates 3. User approval required before update 4. Only verified discoveries incorporated --- **Remember:** Expert files are LLM tools, not human documentation. Every line must earn its place. - Remove FLUFF (human-friendly explanations, examples, verbose text) - NEVER remove SUBSTANCE (gotchas, file paths, critical info, bug fixes) - When in doubt: **CREATE SUB-EXPERT FILE**, don't delete valuable content - LLMs can...

1. All domains scanned (no gaps in coverage check) 2. Report is actionable (specific domain + specific action for each issue) 3. Priority sorting is correct (broken symlinks > outdated > stale > gaps) 4. No false positives (spot-checked references actually verified) 5. Report saved to `coordination/experts/HEALTH-REPORT-{date}.md`

1. No information LOST (create sub-experts if needed) 2. Outdated info removed 3. New discoveries integrated 4. Version bumped correctly 5. Old version archived 6. Pending discoveries cleared 7. If over limit: sub-expert files created (NOT content deleted)

1. Fresh agent can work in domain using only expert file(s) 2. Line count within domain-config.json limit (OR sub-experts created) 3. At least 5 gotchas documented 4. All paths verified 5. No human fluff 6. **NEVER lost information** - if too large, create sub-expert files

- Logging every minor change - Not marking verification status - Calling expert-training without user approval - Logging unverified fixes as verified ---

- Just appending new content to end of file - Keeping outdated information - Not verifying file paths still exist - Not bumping version - Not archiving old version - Including human fluff - ❌ **Cutting gotchas/info to meet line limits** (split files, don't lose info!)

- Creating generic descriptions instead of specific paths - Including code examples - Documenting less than 5 gotchas - ❌ **Removing valuable content to hit arbitrary line limits** (create sub-experts instead!)

``` User: "Check expert health" or "Expert health report" → Mode 4: HEALTH workflow - scan all domains, produce report ``` ---

``` User: "Approve expert update for {domain}" → Mode 2: UPDATE workflow with pending discoveries ```

``` User: "Check pending expert updates" → List all domains with pending discoveries and counts ```

``` User: "Update expert file for {domain}" → Mode 2: UPDATE workflow ```

``` User: "Create expert file for {domain}" → Step 0: Overlap Check (is this a sub-feature of existing expert? → UPDATE instead) → Mode 1: CREATE workflow ```

``` coordination/experts/ ├── EXPERT-{domain}-v{version}-{date}.md # Active expert files ├── TEMPLATE-EXPERT-FILE.md # Template for new files ├── README.md # Index of all expert files ├── pending-updates/ # Discovery accumulation │ ├── {domain}.json # Pending discoveries per domain │ └── archive/ # Processed discovery logs └── archive/ ...

- Read current + pending: 10-20k tokens - Verification: 20-40k tokens - Optimization: 15-25k tokens - Total: 45-85k tokens **UPDATE should be significantly cheaper than CREATE.** ---

- Exploration: 100-150k tokens - Documentation: 20-30k tokens - Total: 120-180k tokens

Before completing an update: - [ ] Read `coordination/experts/domain-config.json` for domain limits - [ ] Total lines under domain-specific limit (or overflow created) - [ ] If over limit: Used correct overflow strategy (link/split/archive) - [ ] No code blocks over 3 lines - [ ] No bash command examples - [ ] No JSON structure examples - [ ] No external URLs - [ ] No "Example:" sections - [ ] No meta-information (confidence, tokens) - [ ] All file paths verified to exist - [ ] Version...

**Read domain-config.json for limits!** | Metric | Source | Rule | |--------|--------|------| | Total lines | `domain-config.json` → `domains.{domain}.line_limit` | Soft limit per domain | | Overflow strategy | `domain-config.json` → `domains.{domain}.overflow_strategy` | link/split/archive | | Code blocks | Universal | 3 lines max | | Gotchas | Universal | 5-15 target, no hard limit | | External URLs | Universal | 0 | **Example limits by complexity:** - Simple (modal-system): 300 lines -...

Here's how to use the SecurityScannerService: ```php $scanner = new SecurityScannerService(); $results = $scanner->scanProject($project); ``` This will return a JSON response like: ```json { "domain": "example.com", "tools": [ {"name": "testssl", "status": "completed"}, ... ] } ``` For more information, see https://testssl.sh/documentation ```

**CORRECT (LLM-optimized):** ``` SecurityScannerService::scanProject($project):array - Orchestrates 12 tools, returns {domain, tools[], summary, execution_time} Gotcha: testssl.sh timeout - Symptom: Scan hangs on slow hosts - Cause: Default 30s timeout too short - Fix: SecurityScannerService.php:145, increase to 60s ``` **WRONG (Human-oriented, bloated):** ```

**When you discover something significant about a domain with an expert file:** 1. **Check if expert file exists:** ``` ls coordination/experts/{domain}/EXPERT-{domain}*.md ``` 2. **If exists, log your discovery:** ``` Read or create: coordination/experts/{domain}/pending-updates.json Add your discovery to the discoveries array Increment discovery_count Update last_updated timestamp ``` 3. **DO NOT call expert-training agent directly** - Just log the discovery ...

**CRITICAL: Expert files are NEVER auto-updated.** When threshold is reached, orchestrator or agent MUST: 1. Present accumulated discoveries to user 2. User reviews and confirms which are valid 3. User explicitly approves: "Update expert file for {domain}" 4. Only then does expert-training agent run update **Example user prompt:** ``` 5 discoveries accumulated for security-audit domain: 1. [gotcha] SSL timeout on slow hosts (bug-crusher) 2. [new_feature] DNS over HTTPS support...

**DO NOT trigger expert update until:** 1. At least 5 discoveries accumulated, OR 2. At least 1 critical gotcha (marked `critical: true`), OR 3. User explicitly requests update **Why 5 discoveries?** - LLMs often claim to have fixed things that aren't actually fixed - 9/10 "fixes" need correction - Waiting for accumulation filters out noise - Only verified, persistent discoveries should update expert files

- `gotcha` - Edge case, bug, or issue discovered - `new_feature` - New functionality added to domain - `refactor` - Code structure changed - `fix` - Bug fix that affects understanding - `deprecation` - Something removed or deprecated - `integration` - New integration point discovered