Decide which workspace to post to based on WHERE the issue lives: | Issue relates to... | Workspace | Example components | |---------------------|-----------|-------------------| | Syncrovanis engine/pipeline/dashboard | syncrovanis | L0, L1, L2, L3, KB, dashboard, pipeline, logging, state, boilerplate, guardrail | | MCP server tools/functionality | mcp-servers | tools, translations, fields, deploy, graphql, cache, diagnostics, admin, relationships, extensions, build, docs, audit, manifest,...

**Step 1: Always search for duplicates FIRST:** ```bash ~/.claude/lib/gap-cli.sh search --workspace {ws} --query "short description" ``` **Step 2a: If duplicate found — add occurrence (bumps impact score):** ```bash ~/.claude/lib/gap-cli.sh occurrence --workspace {ws} --gap-id GAP-NNN --note "Seen again: {context}" ``` **Step 2b: If new — add gap:** ```bash ~/.claude/lib/gap-cli.sh add \ --workspace {ws} \ --title "Short descriptive title" \ --priority {critical|high|medium|low} \ ...

- You are fixing the issue right now (no need to track) - One-off operation that will never recur - Issues with third-party tools (Serena, Playwright, Context7) — use `_discovery-logging` instead - Trivially simple things the user can just do

Log BEFORE completing your task when you: - Find a bug you cannot fix in current scope - Encounter missing MCP tool functionality (fell back to SSH/bash) - Discover a quality issue or technical debt worth tracking - Notice a feature request surfaced during work - Find a pipeline/engine issue in Syncrovanis - Detect a missing or broken tool in an MCP server

When you discover a bug, quality issue, missing functionality, or performance problem during your work — and it is NOT something you can fix right now — log it as a GAP.

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh lighthouse ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that Lighthouse will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

1. Note in response 2. Proceed with manual exploration 3. Consider creating handoff: `coordination/experts/handoffs/HANDOFF-{domain}-{date}-{agent}.md`

Each expert file contains: - Quick reference (key files, classes, methods) - Database schema - Known gotchas and bugs - Integration points - Data flow diagrams

All in: `coordination/experts/{domain}/` Current domains: - `security-audit-system` — security scanning, audit rules - `findings-templates` — template system, findings management - `findings-blocks-seo-migration` — block-based findings, SEO - `web-discovery-verification` — website discovery, verification - `page-crawler-system` — Puppeteer, web scraping - `analysis-execution-infrastructure` — analysis runners, queues - `backend-refactoring-patterns` — service patterns, DI -...

```bash # List all available expert domains ./coordination/scripts/discover-experts.sh --list # Match by agent type ./coordination/scripts/discover-experts.sh --agent {your-agent-type} ```

```bash ./coordination/scripts/discover-experts.sh --for-task "your task description" ``` Read ALL matched expert files BEFORE starting work. Token savings: 80-90% vs manual exploration.

```bash # Free-text search (ALL workspaces with Laravel): php artisan kb:query "TOPIC" --limit=5 # Structured lookup (specific file/domain/masterplan): php artisan kb:context domain:customer-management --limit=5 php artisan kb:context file:app/Services/Example.php --limit=5 # Non-Laravel workspaces (magitek-ops, dam): vendor/bin/kb query "TOPIC" --limit=5 --project-root=$(pwd) ``` KB returns relevant excerpts AND points to which expert files are most relevant. **If KB returns useful results...

- KB gives **direction**, not complete solutions - Always read the actual files for full context - If KB returns 0 results → proceed without it (do not block on this) - Max 5 results — more wastes tokens without benefit - Skip KB if task is purely administrative (git commits, file moves, etc.)

Extract 1-3 keywords from the task that represent the domain: - "Fix the analysis queue job" → topic: `analysis queue` - "Update Proxmox backup policy" → topic: `proxmox backup` - "Add CSV export for customers" → topic: `customers export` - "Debug NPM proxy issue" → topic: `npm proxy` **Keep topics short and specific** — 2-3 words max.

| Workspace | Command | |-----------|---------| | `/var/www/reportmaker` | `php artisan kb:query "$TOPIC" --limit=5` | | `/var/www/skymirror` | `php artisan kb:query "$TOPIC" --limit=5` | | `/var/www/magitek-ops` | `vendor/bin/kb query "$TOPIC" --limit=5 --project-root=$(pwd)` | | Any other | Check for `artisan`, fall back to `vendor/bin/kb` |

Read the KB output before starting work. This gives you: - Known gotchas and bugs for this domain - Relevant expert files to read - Patterns and lessons from previous work

```bash # Non-Laravel workspaces (magitek-ops, or any without artisan): $PROJECT_ROOT/vendor/bin/kb query "$TOPIC" --limit=5 --project-root="$PROJECT_ROOT" # Laravel workspaces (reportmaker, skymirror) — free-text search: php $PROJECT_ROOT/artisan kb:query "$TOPIC" --limit=5 # Laravel workspaces — structured lookup (specific file/domain/masterplan): # php $PROJECT_ROOT/artisan kb:context domain:$DOMAIN --limit=5 # php $PROJECT_ROOT/artisan kb:context file:$FILE_PATH --limit=5 ``` **Workspace...

```bash # Use the current working directory as project root PROJECT_ROOT=$(pwd) ```

Before starting work, extract the main topic/domain from the task and run a KB search.

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh css ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that CSS MCP will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

1. Resolve the project root (the current working directory) and run: ```bash .claude/accessibility-disable.sh ``` If `.claude/accessibility-disable.sh` does not exist, use `.claude/switch-mcp.sh none` as fallback. 2. Inform the user that Accessibility Scanner will be disabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

1. Resolve the project root (the current working directory) and run: ```bash .claude/lighthouse-disable.sh ``` If `.claude/lighthouse-disable.sh` does not exist, use `.claude/switch-mcp.sh none` as fallback. 2. Inform the user that Lighthouse will be disabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh accessibility ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that Accessibility Scanner will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

After logging, ALWAYS tell the user in your response: > **MCP-feedback ({server}):** [kort beskrivelse]. GAP-NNN logget. Prioritet: {P}. Dashboard: https://syncrovanis.magitek.no/gaps

If you discover that you (or another agent) used a **third-party** MCP tool incorrectly (wrong Serena command, bad Playwright selector, incorrect Context7 query, etc.), that is an **agent knowledge gap**, not an MCP server gap. Log it via `_discovery-logging` as a **gotcha** in the relevant workspace's `coordination/experts/` — so future agents learn the correct usage pattern.

- SSH/bash for things that genuinely belong on the OS level (systemctl, package mgmt) - One-off operations that will never recur - MCP already supports it but agent forgot — just use MCP next time - **Any issue with third-party MCP servers** — we don't own them, don't log them

- **gap** — MCP server lacks functionality, agent had to use slower method - **error** — MCP call failed (exception, timeout, wrong response) - **perf** — MCP worked but was inefficient (many calls for what should be one) - **ux** — MCP "succeeded" but behaved unexpectedly: confusing response, silent failure, missing context

**Step 1: Search for duplicates** ```bash ~/.claude/lib/gap-cli.sh search --workspace mcp-servers --query "short description of issue" ``` **Step 2a: If duplicate found — add occurrence:** ```bash ~/.claude/lib/gap-cli.sh occurrence --workspace mcp-servers --gap-id GAP-NNN --note "Seen again: {context}" ``` **Step 2b: If new — add gap:** ```bash ~/.claude/lib/gap-cli.sh add \ --workspace mcp-servers \ --title "Short title" \ --priority {high|medium|low} \ --component...

| Tool Prefix | MCP Server | Workspace | Server value | |-------------|------------|-----------|--------------| | `mcp__reportmaker__` | reportmaker | mcp-servers | reportmaker | | `mcp__suitecrm__` | suitecrm | mcp-servers | suitecrm | **DO NOT log feedback for third-party servers:** `serena`, `playwright`, `mysql`, `lighthouse`, `accessibility`, `xdebug`, `context7` — we don't build or maintain these. Skip silently.

Trigger BEFORE completing a task when ANY agent: - Used a fallback (SSH, bash, grep, shell, manual workaround) for something a **custom** MCP tool SHOULD support - Got a failed MCP call (error response, exception, wrong data) from a **custom** server - Needed multiple MCP calls for something that should be a single operation on a **custom** server - Used a custom MCP tool incorrectly due to misleading docs/behavior and had to retry

Logs gaps for MCP servers **we build and maintain** to the SQLite GAP tracker. Third-party MCP servers (Serena, Playwright, MySQL, Context7, etc.) are NOT logged — we can't fix them.

1. Resolve the project root (the current working directory) and run: ```bash .claude/css-disable.sh ``` If `.claude/css-disable.sh` does not exist, use `.claude/switch-mcp.sh none` as fallback. 2. Inform the user that CSS MCP will be disabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

**IKKE** begynn å jobbe basert på window-tittelen eller rolle-konteksten alene. **IKKE** les filer, analyser kode, eller foreslå løsninger ennå. Rollen er nå satt. Still dette ene spørsmålet og vent: > **Hva skal vi jobbe med i Syncrovanis?** Vent på brukerens svar før du gjør noe som helst. --- You are now the **syncrovanis-specialist**. Read and follow ALL instructions from `~/.claude/agents/syncrovanis-specialist.md`

Vis Syncrovanis onboarding-logger fra gjeldende workspace. Argumenter: `[session|today|all]` (default: siste 20 entries) ```bash LOG_FILE="$HOME/.claude/logs/syncrovanis.jsonl" CTX_DIR="$HOME/.claude/logs/syncrovanis-context" WS=$(basename "$PWD") MODE="${1:-recent}" if [ ! -f "$LOG_FILE" ]; then echo "Ingen logg funnet: $LOG_FILE" exit 0 fi python3 -c " import json, sys, os, glob from datetime import datetime from pathlib import Path from collections import defaultdict ws =...

def parse_ts(e): ts = e.get("ts", "") if not ts: return None try: return datetime.fromisoformat(ts.replace("Z", "+00:00")) except ValueError: return None for e in entries: e["_dt"] = parse_ts(e) total = len(entries) dated = [e for e in entries if e["_dt"]] dates = sorted(e["_dt"] for e in dated) date_min = dates[0].strftime("%Y-%m-%d") if dates else "?" date_max = dates[-1].strftime("%Y-%m-%d") if dates else "?" # ── Section helpers...

```bash if [ -f artisan ]; then basename "$(pwd)" elif [ "$(basename $(pwd))" = "syncrovanis" ]; then echo "syncrovanis" else echo "unknown" fi ``` **After detection:** Load the variant file and follow ALL its instructions. Do NOT use this file for actual work.

``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-reportmaker.md (SkyMirror uses same SOLO structure as ReportMaker) ELSE IF cwd = /var/www/syncrovanis (or contains "syncrovanis" in path): → Read and follow ALL instructions from...

This command detects your workspace and loads the correct specialized SOLO variant.

``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-light-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-light-reportmaker.md ELSE IF cwd = /var/www/syncrovanis (or contains "syncrovanis" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-light-syncrovanis.md ELSE...

This command detects your workspace and loads the correct specialized variant.

``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-dev-light-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-dev-light-reportmaker.md ELSE IF cwd = /var/www/syncrovanis (or contains "syncrovanis" in path): → Read and follow ALL instructions from...

This command detects your workspace and loads the correct specialized variant.

``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-dev-full-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-dev-full-reportmaker.md ELSE IF cwd = /var/www/syncrovanis (or contains "syncrovanis" in path): → Read and follow ALL instructions from...

This command detects your workspace and loads the correct specialized variant.

``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-bug-light-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): → Read and follow ALL instructions from ~/.claude/agents/solo-bug-light-reportmaker.md ELSE IF cwd = /var/www/syncrovanis (or contains "syncrovanis" in path): → Read and follow ALL instructions from...

This command detects your workspace and loads the correct specialized variant.

- Les ALLTID target-filen for du redigerer den - Bruk Edit-tool, ALDRI Write-tool for eksisterende filer (unntatt nye gaps-filer) - ALDRI rediger agent-filer, orchestrator-parts, eller Syncrovanis-kode direkte - ALDRI rediger Syncrovanis Python/template-kode — kun bruk gap_reader API via python3 -c - ALDRI rediger filer i /var/www/mcp-servers/ utenom via gap_reader API Returner en kort oppsummering per tier: TIER 1: {N} items implementert (fil → endring) TIER 2: {N} items logget (workspace →...

- k-items (expert-fil gotchas) → Tier 1 - u-items som nevner 'knowledge', 'gotcha', 'korreksjon' → Tier 1 - u-items som nevner 'agent-regel', 'hard gate', 'blokkering', 'forby', 'prosess' → Tier 3 - m-items (MCP-usage) → Tier 3 - s-items (Syncrovanis) → Tier 2 - g-items (MCP-selfbuild) → Tier 2

For u-items som er agent-regler/prosess, og alle m-items (MCP-usage): - Append til `coordination/maintenance/BACKLOG.md` i workspace - Finn neste ledige M-ID: `grep -oP 'M-\K\d+' coordination/maintenance/BACKLOG.md | sort -n | tail -1` - Format: `- [ ] M-{neste-ID}: [AUDIT-{NNNN}] {beskrivelse} · Prioritet: {pri} · Kilde: {audit-filsti}`

Bruk ALLTID `gap-cli.sh` — ALDRI inline python3 -c eller SQL mot knowledge.db. **For HVER s-item (Syncrovanis) og g-item (MCP-selfbuild):** ```bash # Steg 1: Soek duplikater ~/.claude/lib/gap-cli.sh search --workspace {syncrovanis|mcp-servers} --query "KORT_SOEKEORD" # Steg 2a: Duplikat funnet — legg til occurrence ~/.claude/lib/gap-cli.sh occurrence --workspace {ws} --gap-id GAP-NNN --note "AUDIT-{NNNN} {s/g-ID}" # Steg 2b: Nytt funn — legg til gap ~/.claude/lib/gap-cli.sh add \ ...