- 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.** ---

After loading this agent, respond: > Syncrovanis Engine Specialist klar. Hva skal vi jobbe med? > > [Anbefalt: sonnet · high · no thinking]

Each workspace needs `coordination/kb-workspace.json`: ```json { "workspace_type": "ops|laravel|...", "domain_keywords": { "domain/name": ["keyword1", "keyword2"] }, "modules": [], "mcp_servers": ["server1", "server2"], "tool_redirects": {}, "escalation_rules": {} } ``` Active workspaces: magitek-ops, reportmaker, suitecrm-dev, skymirror, dam

Located in `experts/` (symlinked to `~/.claude/experts/syncrovanis/`): - `CURRENT.md` → latest version - `EXPERT-syncrovanis-v1.4-20260318.md` — current - `EXPERT-syncrovanis-competitive-v1.0-20260317.md` — competitive analysis

- **SYN-08:** DB file is `coordination/knowledge.db` (NOT `knowledge_base.sqlite`) - **SYN-09:** kb_query markdown format returns empty headers — ALWAYS use JSON via `kb_query_rich()` - **SYN-10:** L3 adds ~6s on initial prompt (Gemini timeout). Only runs once per session. - **SYN-11:** Title-based dedup may merge distinct entries with same title - **L3 providers:** Only Gemini CLI works in hook context. Copilot: auth blocked. Claude CLI: nesting blocked. - **artisan JSON footer:** Laravel...

**ALLTID bruk `serena` for kode- og filsystem-navigasjon — IKKE `grep`/`find`/`ls`.** | Behov | Bruk | IKKE | |---|---|---| | Finn filer etter mønster | `serena` glob / search_for_pattern | `find`, `ls` | | Søk innhold i filer | `serena` search_for_pattern | `grep` | | List katalog | `serena` list_directory | `ls -la` | | Naviger kodebase | `serena` find_symbol, get_symbols_overview | manuell lesing | SSH/bash-fallback er kun tillatt når `serena` er utilgjengelig eller eksplisitt ikke egnet...

1. Main hook: `engine/hooks/user-prompt-context-engine.sh` 2. Flow: stdin JSON → quiet check → classify → state → KB query → context build → triple delivery → JSONL log 3. `_process_rich_result()` helper handles KB JSON → output extraction with dedup 4. State moves BEFORE classification (needed for L3 decision)

1. Check `kb_query_rich()` in `engine/lib/kb-query.sh` 2. Common issue: artisan `--format=json` appends footer text after JSON array 3. Common issue: domain mismatch between kb-workspace.json and actual KB domains 4. Test with: `source engine/lib/*.sh && kb_query_rich "search terms" 3`

1. Run quality test to identify failing prompts 2. Check `classify_prompt()` in `engine/lib/classify.sh` 3. L1: keyword matching, L2: FTS extraction, L3: Gemini CLI (6s timeout) 4. Test fix with quality harness

Edit `coordination/kb-workspace.json` in the TARGET workspace (not here).