```bash # Quick check if [ -f artisan ]; then basename "$(pwd)" # reportmaker, skymirror, etc. else echo "ops-workspace" fi ```

**Detect workspace from current working directory:** ``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): → Read and follow ALL instructions from .claude/agents/expert-training-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): → Read and follow ALL instructions from .claude/agents/expert-training-reportmaker.md (SkyMirror uses same expert structure as ReportMaker) ELSE IF cwd = /var/www/suitecrm-dev (or...

This agent detects your workspace and delegates to the correct specialized variant.

- Expert files are symlinked to `~/.claude/experts/syncrovanis/` - Changes here are visible to Syncrovanis knowledge queries - Never reference internal file paths that may change — use function names and concepts - Cross-reference with syncrovanis-specialist agent file for consistency

```bash # 1. Verify only latest EXPERT + competitive in root ls coordination/experts/EXPERT-*.md # Must return ONLY: EXPERT-syncrovanis-competitive-*.md + EXPERT-syncrovanis-v{LATEST}.md # 2. Verify all symlinks are valid for f in coordination/experts/CURRENT*.md; do [ -L "$f" ] && target=$(readlink "$f") && [ -f "coordination/experts/$target" ] \ && echo "OK: $f -> $target" || echo "BROKEN: $f" done # 3. Verify CURRENT files are symlinks, not regular files for f in...

Read `coordination/experts/domain-config.json` before updating. Defaults: - Main expert (overview + architecture): 600 lines soft target - Domain sub-files (engine, dashboard, etc.): 400 lines soft target - Competitive: no limit When main expert exceeds 700 lines → trigger domain split (see structure above).

When UPDATE optimizes an existing file, these sections MUST be preserved or explicitly migrated to sub-files: | Section | Why critical | |---------|-------------| | Engine Core Function Reference | Function signatures for classify.sh, kb-query.sh, state.sh, l3-gate.sh — agents use this daily | | Dashboard Template Map | Route→template→datasource mapping + hosting chain — needed for dashboard work | | Install System Details | Symlink table + known missing symlinks (SYN-32) | | L3 Provider Chain...

**After every UPDATE:** ```bash # 1. Move old version to _archive mv coordination/experts/EXPERT-syncrovanis-v{OLD}.md coordination/experts/_archive/ # 2. Update symlink cd coordination/experts/ ln -sf EXPERT-syncrovanis-v{NEW}.md CURRENT.md ln -sf EXPERT-syncrovanis-v{NEW}.md CURRENT-syncrovanis.md # 3. Verify only correct files remain in root ls coordination/experts/*.md # Should only show: competitive + latest version ``` **FORBIDDEN root state:** - More than 2 EXPERT-*.md files in root...

1. **Minor version** (v1.1 → v1.2): New gotchas, updated file paths, added sections 2. **Major version** (v1.x → v2.0): Architecture changed, new components, significant rewrites 3. **Always update CURRENT.md symlink** after creating new version 4. **Never delete old versions** — move to `_archive/` immediately after creating new version 5. **Only CURRENT symlinks + latest EXPERT version** should remain in root (or domain folder)

- Related expert: [filename] - Source code: [file:line] ```

[Numbered SYN-XX gotchas with root cause and workaround]

[System structure with file paths and line references]

[What this covers and why it matters]

```markdown --- version: X.Y date: YYYY-MM-DD scope: syncrovanis --- # EXPERT: Syncrovanis [Topic] vX.Y

When building expert knowledge, gather from: ```bash # Engine code (primary source of truth) cat engine/hooks/user-prompt-context-engine.sh cat engine/lib/*.sh # Dashboard code cat dashboard/app.py cat dashboard/data/*.py # Existing expert files cat experts/CURRENT.md # JSONL log (runtime behavior evidence) tail -50 ~/.claude/logs/syncrovanis.jsonl # Quality test results ./engine/test/quality-test.sh --workspace reportmaker # Workspace configs (cross-workspace differences) for ws in...

Expert files for Syncrovanis should document: 1. **Pipeline architecture** — Hook flow, classification layers, KB query, context delivery 2. **Classification system** — L1 keywords, L2 FTS, L3 LLM, provider constraints 3. **KB integration** — `kb_query_rich()`, JSON format, artisan footer workaround, dedup 4. **State management** — Session state, delta detection, onboarding vs continuation 5. **Cross-workspace behavior** — How configs differ, testing strategies 6. **Dashboard architecture** —...

Dynamic context delivery engine for Claude Code. Two codebases: **Engine (Bash):** - Hook pipeline: `engine/hooks/user-prompt-context-engine.sh` - Classification: `engine/lib/classify.sh` (L1 keyword, L2 FTS, L3 LLM) - KB query: `engine/lib/kb-query.sh` (`kb_query_rich()` returns JSON) - State: `engine/lib/state.sh` (session state, delta detection) - Workspace detection: `engine/lib/workspace-detect.sh` - Quality test: `engine/test/quality-test.sh` **Dashboard (Python/Flask):** - Flask app:...

``` 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!)