When the user says these things, run the corresponding command WITHOUT asking: | User says | Agent runs | |---|---| | "kjør kvalitetstest" / "test quality" | `cd /var/www/syncrovanis && ./engine/test/quality-test.sh` | | "test reportmaker" / "test [workspace]" | `cd /var/www/syncrovanis && ./engine/test/quality-test.sh --workspace [workspace]` | | "test denne prompten: X" | `cd /var/www/syncrovanis && ./engine/test/quality-test.sh --prompt "X" --workspace [ask]` | | "lagre baseline" | `cd...

**THIS IS PRODUCTION.** Changes affect ALL Claude Code sessions on this server. Before ANY code change: 1. `bash -n engine/hooks/user-prompt-context-engine.sh` — syntax check 2. `bash -n engine/lib/*.sh` — syntax check all libs 3. Test with quality harness: `engine/test/quality-test.sh --workspace magitek-ops` 4. If engine crashes, Claude Code sessions still work — context just won't be injected

``` /var/www/syncrovanis/ ├── engine/ │ ├── hooks/ — UserPromptSubmit + SessionStart hooks │ ├── lib/ — classify, kb-query, llm-classify, state, workspace-detect │ └── test/ — quality-test.sh (cross-workspace quality harness) ├── experts/ — Syncrovanis expert files (CURRENT.md → latest version) ├── coordination/ — MP-0008 masterplan + tasks ├── install.sh — Symlink installer └── CLAUDE.md ``` Engine files are symlinked from...

Dynamic context delivery engine for Claude Code. Runs as a global hook on every user prompt across all workspaces. Pipeline: 1. **Detect workspace** (`engine/lib/workspace-detect.sh`) 2. **Classify prompt** (`engine/lib/classify.sh`) — L1 keyword → L2 FTS → L3 LLM (Gemini) 3. **Query KB** (`engine/lib/kb-query.sh`) — `kb_query_rich()` returns JSON with deduplicated excerpts 4. **Track state** (`engine/lib/state.sh`) — session state, delta detection 5. **Deliver context**...

**First action:** Run `pwd` and verify. - Expected: `/var/www/syncrovanis` (or subdir) - If wrong workspace: STOP and tell the user to switch.

When working on agent improvements, check the maintenance backlog for MCP-usage items: ```bash # Check for outstanding MCP-usage items in current workspace grep -c '\[ \] M-' coordination/maintenance/BACKLOG.md 2>/dev/null || echo "0" ``` If outstanding items exist: 1. **Group by pattern** — many items describe the same underlying issue (e.g., 5 items all say "use Serena instead of grep") 2. **Implement grouped** — one agent-file edit per pattern group, not per item 3. **Mark completed** —...

1. Run unused analysis (90 days) 2. Verify not referenced by orchestrator 3. Present to user with data 4. Archive on approval (never delete)

1. Check executable permissions 2. Check registered in settings.json 3. Check matcher pattern 4. Test manually: `echo '{"tool_name":"..."}' | ~/.claude/hooks/{name}.sh`

1. Check file locks (2hr expiry) 2. Check work registry 3. Check stale worktrees (`git worktree list`) 4. Clear stale locks

1. Check YAML frontmatter 2. Fix if missing/malformed 3. Fix permissions (`chmod 644`) 4. User reloads VS Code window

1. Sjekk at pakken eksisterer: `ls /var/www/mcp-servers/packages/{name}/` 2. Les `server.py` og `helpers.py` for faktiske env-var-navn — ikke README (kan ligge etter) 3. Installer deps: `cd packages/{name} && uv venv --python 3.12 && uv pip install -e .` 4. Legg til i `.mcp.json` med korrekte env-vars og venv-python som command 5. Oppdater doks: `session-state.md`, `CLAUDE.md` (tellerrad), `mcp-tools-reference.md` 6. Verifiser: `python3 -c "from server import mcp; print('OK')"` med timeout

- Agent naming: `{domain}-{function}` or `{function}-{workspace}` - Expert file rules: CURRENT = symlinks, domain prefix, cross-refs

- Fix stuck file locks (`coordination/file_locks.json` — 2hr expiry) - Clean stale work registries (`coordination/active_work_registry.json`) - Maintain masterplan archival

- Create skills (`~/.claude/skills/{name}/SKILL.md`) - Create hooks (`~/.claude/hooks/{name}.sh` + register in settings) - Debug broken hooks (permissions, matchers, exit codes) - Maintain background skills budget (total `_*` descriptions < 4000 chars)

- Create, modify, archive agents (global or local) - Create workspace variants (e.g., `architect-{workspace}.md`) - Fix visibility issues (YAML frontmatter, permissions)

```bash python3 ~/.claude/scripts/usage-stats.py summary --days=30 python3 ~/.claude/scripts/usage-stats.py unused --days=60 ls ~/.claude/agents/*.md | wc -l ls ~/.claude/hooks/*.sh 2>/dev/null ```

Some agent files are auto-generated from `~/.claude/agents/parts/`. A hook blocks direct edits. Currently generated: `orchestrator.md`. To modify: edit parts, then `~/.claude/agents/build-agent.sh orchestrator [profile]`. See `orchestrator-ops.md` for full details.

Read: `~/.claude/agents/agent-meta/context-{WORKSPACE}.md` If it doesn't exist, discover the workspace: ```bash ls .claude/agents/*.md 2>/dev/null # Local agents ls .claude/commands/*.md 2>/dev/null # Local commands cat .mcp.json 2>/dev/null | python3 -c "import json,sys; print(list(json.load(sys.stdin).get('mcpServers',{}).keys()))" 2>/dev/null ls coordination/experts/ 2>/dev/null # Expert structure cat CLAUDE.md 2>/dev/null | head -30 # Workspace...

You are **agent-meta** in a workspace that doesn't have a specialized variant yet. Read the context file for data, then apply these generic procedures. **Shared principles are in the router:** `~/.claude/agents/agent-meta.md` — you inherit all of them.

All gaps visible at: https://syncrovanis.magitek.no/gaps

Tell the user: > **GAP logged:** {GAP-NNN} [{priority}] {title} -> {workspace}

**syncrovanis types:** bug, feature, quality, docs, performance **mcp-servers types:** gap, error, perf, ux, bug, feature, quality, docs, performance **Priority:** critical, high, medium, low To see all current enums: `~/.claude/lib/gap-cli.sh enums`

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