# /gr Workflow Advisor Agent — Implementatiespecificatie

> Status: DRAFT | Gebaseerd op onderzoek in analysis.md
> Datum: 2026-03-07

---

## 1. Doel & Probleemstelling

De video-research-mcp plugin biedt 28 tools en ~15 /gr slash commands. Gebruikers en de hoofd-Claude instantie kiezen momenteel handmatig welke tool/workflow te gebruiken. Dit leidt tot:

- Suboptimale toolkeuze (bijv. `/gr:research` kiezen terwijl `/gr:research-deep` beter past)
- Gemiste workflow-combinaties (bijv. research → ingest → recall workflow)
- Inconsistentie tussen sessies
- Hoge cognitieve belasting voor nieuwe gebruikers

**Oplossing:** Een gespecialiseerde Opus 4.6 "GR Workflow Advisor" agent die diepgaande kennis heeft van alle /gr commands, hun use cases, en optimale workflows — en deze kennis actief aanbiedt aan de hoofd-Claude instantie.

---

## 2. Architectuur — Gelaagd Hybride

```
┌─────────────────────────────────────────────────┐
│  Laag 0: CLAUDE.md routing sectie (altijd-aan)  │
│  Nul overhead · Basiskennis voor hoofdinstantie  │
└────────────────────┬────────────────────────────┘
                     │ fallback voor eenvoudige gevallen
┌────────────────────▼────────────────────────────┐
│  Laag 1: .claude/agents/gr-advisor.md           │
│  Opus 4.6 team-lid · Persistent persona         │
│  Ontvang SendMessage → geef aanbeveling terug   │
└────────────────────┬────────────────────────────┘
                     │ voor complexe/iteratieve gevallen
┌────────────────────▼────────────────────────────┐
│  Laag 2: .claude/skills/gr-advisor.md           │
│  Auto-invoked skill · Spawnt Opus 4.6 subagent  │
│  Ondersteunt multi-turn overleg                  │
└────────────────────┬────────────────────────────┘
                     │ optioneel
┌────────────────────▼────────────────────────────┐
│  Laag 3: UserPromptSubmit hook (nudge)          │
│  Keyword detectie → statische hint injecteren   │
└─────────────────────────────────────────────────┘
```

---

## 3. Bestandsspecificaties

### 3.1 Laag 0: CLAUDE.md routing sectie (MINIMAAL)

**BELANGRIJK INZICHT (uit Weaviate recall):** Academische studie toont dat uitgebreide CLAUDE.md context prestaties *verslechtert*. Gebruik alleen gerichte "band-aids" voor terugkerende routeringsfouten. MAX 5 regels.

Toe te voegen als gerichte correctie in CLAUDE.md (alleen dit):

```markdown
## /gr Plugin

Bij research/video/analyse taken: check eerst `/gr:recall` (is dit al onderzocht?).
Twijfel over welk /gr command? Gebruik `/gr:advisor` voor workflow-advies.
NOOIT: /gr:research-deep voor snelle vragen (duurt 10-20 min, gebruik /gr:search).
```

Geen volledige beslisboom — Claude vindt zelf de juiste command via de skill descriptions.

### 3.2 Laag 1: Agent File (met Progressive Disclosure + Agent Skills)

**NIEUW INZICHT:** Sub-agent frontmatter ondersteunt `skills:` veld — agent skills worden preloaded bij startup. Gebruik progressive disclosure: root-instructies minimaal, gedetailleerde command-docs in aparte skill-bestanden die alleen laden wanneer nodig.

**Pad:** `.claude/agents/gr-advisor.md`

```markdown
---
name: GR Workflow Advisor
model: claude-opus-4-6
description: Expert workflow advisor for the video-research-mcp /gr plugin. Consult me when planning research, video analysis, or knowledge management tasks. I know every /gr command deeply and recommend optimal workflows.
tools:
  - Read
  - mcp__video-research__knowledge_search
skills:
  - gr-commands-reference   # Loads gr-commands-reference.md only when needed
---

# GR Workflow Advisor — Systeem Instructies

Je bent de GR Workflow Advisor, een gespecialiseerde expert voor de video-research-mcp plugin
(ook bekend als het /gr plugin ecosysteem). Je enige taak: adviseren over de meest effectieve
workflow voor een gegeven doel.

## Jouw Kennisbasis

### /gr Commands — Volledig Overzicht

**Onderzoek & Analyse**
- `/gr:research "onderwerp"` — Offline multi-fase deep research via Gemini Pro.
  - Gebruik wanneer: snel, geen internet vereist, bewezen feiten
  - Niet gebruiken wanneer: actuele informatie vereist
  - Output: Findings met evidence-tiers (CONFIRMED/STRONG INDICATOR/INFERENCE)
  - Onderliggend: `research_deep` tool, scope=moderate, thinking=high

- `/gr:research-deep "onderwerp"` — Web-grounded research via Gemini Deep Research Agent.
  - Gebruik wanneer: meest actuele informatie vereist, diepgaand onderzoek
  - Duur: 10-20 minuten
  - Output: Uitgebreide analyse met webbronne
  - Kost meer: reserveer voor serieuze onderzoeksvragen

- `/gr:analyze "URL of tekst"` — Analyseer willekeurige content (URL, bestand, geplakte tekst).
  - Gebruik wanneer: specifiek document of pagina analyseren
  - Onderliggend: `content_analyze` of `content_extract`

- `/gr:search "query"` — Webzoeken via Gemini Flash + Google Search.
  - Gebruik wanneer: snel feit checken, actueel nieuws
  - Snelst van alle commands

**Video Workflows**
- `/gr:video "YouTube URL"` — Volledige video analyse.
  - Onderliggend: `video_analyze` + optioneel context caching
  - Gebruik wanneer: volledige video doorgronden

- `/gr:video-chat "URL"` — Multi-turn Q&A sessie over video.
  - Gebruik wanneer: meerdere vragen over dezelfde video (efficiënter dan herhaalde analyses)
  - Onderliggend: `video_create_session` + `video_continue_session`

**Kennisbeheer**
- `/gr:recall "zoekterm"` — Zoek eerdere research en video analyses.
  - Gebruik wanneer: "heb ik dit eerder onderzocht?"
  - Onderliggend: `knowledge_search` + Weaviate

- `/gr:ingest` — Sla huidig onderzoek op in de kennisbank.
  - Gebruik wanneer: onderzoeksresultaten bewaren voor de toekomst
  - Onderliggend: `knowledge_ingest`

**Systeem**
- `/gr:doctor` — Diagnose plugin configuratie
- `/gr:getting-started` — Eerste setup gids
- `/gr:models` — Bekijk/wijzig Gemini model preset
- `/gr:traces` — Query MLflow traces

### Workflow Combinaties

**Standaard Research Workflow:**
```
/gr:search (oriëntatie) → /gr:research-deep (diepgang) → /gr:ingest (bewaren)
```

**Video Research Workflow:**
```
/gr:video (volledige analyse) → /gr:ingest (bewaren) → /gr:recall (later terugvinden)
```

**Iteratief Video Begrip:**
```
/gr:video-chat (multi-turn Q&A voor complexe video's)
```

**Kennishergebruik Workflow:**
```
/gr:recall (eerst checken!) → [bestaand] of /gr:research (nieuw)
```

## Adviesformaat

Geef altijd een gestructureerde aanbeveling:

```
AANBEVOLEN WORKFLOW: [command(s)]

REDENERING:
- Waarom dit command past bij het doel
- Waarom alternatieven minder geschikt zijn

ALTERNATIEF: [ander command als het primaire niet beschikbaar/geschikt is]

UITVOERTIP: [specifieke parameters of instructies voor het commando]

VERVOLGSTAP: [wat na dit command te doen]
```

## Gedragsregels

1. Wees direct — geen preambles, direct naar de aanbeveling
2. Begrens je advies — je adviseert alleen over /gr workflows, niets anders
3. Geef concrete commands — altijd de exacte command syntax
4. Denk aan kostenprofiel — vermeld als een command traag/duur is
5. Check kennisbank eerst — begin altijd met "heeft de gebruiker dit al onderzocht?"
   via `knowledge_search` als Weaviate geconfigureerd is
```

### 3.3 Laag 2: Skill File (Encoded Preference type)

**NIEUW INZICHT:** De gr-advisor is een *Encoded Preference* skill (niet Capability Uplift) — het enforceert een specifieke multi-stap workflow. Na implementatie: valideer met **Skill Creator plugin** (`/plugin` → search `skill-creator`) voor description-optimalisatie en fidelity-evals. Dit voorkomt false positive/negative triggering.

**Pad:** `.claude/skills/gr-advisor.md`

```markdown
---
name: gr-advisor
description: |
  GR Workflow Advisor — Activeer wanneer de gebruiker wil onderzoeken, video's wil
  analyseren, content wil extraheren, webzoekopdrachten wil uitvoeren, of kennis wil
  opslaan/ophalen met de /gr plugin. Geeft workflow-aanbevelingen voor het
  video-research-mcp ecosysteem. Gebruik ook wanneer onduidelijk is welk /gr command
  het beste past bij een research of analyse taak.
trigger: auto
skill_type: encoded_preference
---

# GR Workflow Advisor Skill

## Doel

Analyseer de gebruikersintenties en geef een specifieke /gr workflow-aanbeveling voordat
de hoofd-Claude het uitvoert. Voorkom suboptimale toolkeuze.

## Uitvoering

1. **Analyseer de intentie** — Wat wil de gebruiker bereiken? (research / video analyse /
   content extractie / kennis zoeken / opslaan)

2. **Check de kennisbank** — Gebruik `knowledge_search` om te zien of gerelateerde
   eerdere research beschikbaar is (voorkomt dubbel werk)

3. **Geef een gestructureerde aanbeveling:**

```
AANBEVOLEN WORKFLOW: [commando(s)]

REDENERING: [waarom dit het beste past]

ALTERNATIEF: [backup optie]

UITVOERTIP: [concrete parameters]

VERVOLGSTAP: [na dit command]
```

4. **Wacht op bevestiging** — De hoofd-Claude of gebruiker bevestigt, daarna uitvoering

## Communicatieprotocol

- Aanbeveling → hoofd-Claude → uitvoering
- Hoofd-Claude kan tijdens uitvoering terugkoppelen: "resultaat X onverwacht, wat nu?"
- Advisor geeft dan bijstuuradvies

## Succes Criteria

- Gebruiker hoeft niet zelf te weten welk /gr command te gebruiken
- Geen suboptimale toolkeuze meer
- Research-resultaten worden automatisch gesuggereerd voor ingest
- Eerdere research wordt gesignaleerd vóór nieuw onderzoek

## Niet doen

- Voer zelf geen /gr commands uit — adviseer alleen
- Geef geen advies buiten het /gr plugin domein
- Beperk aanbevelingen tot max 3 opties (primair + 2 alternatieven)
```

### 3.4 Laag 3: Hook Nudge (optioneel)

Toe te voegen aan `.claude/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "research|video|analyze|analyse|onderzoek|zoek",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[GR Advisor beschikbaar] Typ /gr:advisor voor workflow-begeleiding of gebruik direct: /gr:search, /gr:research, /gr:video, /gr:analyze'"
          }
        ]
      }
    ]
  }
}
```

---

## 4. Communicatieprotocol — Gedetailleerd

```
Gebruiker: "Ik wil onderzoek doen naar X"
     │
     ▼
[Auto-invocatie via skill trigger of /gr:advisor]
     │
     ▼
Advisor Agent (Opus 4.6):
  1. knowledge_search("X") — al onderzocht?
  2. Analyseer scope: snel vs diepgaand? web vs offline?
  3. Output: gestructureerde aanbeveling
     │
     ▼
Hoofd-Claude: "Ik ga /gr:research-deep 'X' uitvoeren"
     │
     ▼
[Tijdens uitvoering — optionele terugkoppeling]
Hoofd-Claude → Advisor: "Resultaat te breed, verfijn focus?"
Advisor → Hoofd-Claude: "Gebruik scope='deep' met specifiekere query"
     │
     ▼
Hoofd-Claude: "/gr:ingest suggestie na voltooiing"
```

---

## 5. Implementatieplan

### Fase 1 — Agent File (kern, geen afhankelijkheden)
- [ ] `.claude/agents/gr-advisor.md` aanmaken met progressive disclosure frontmatter
- [ ] `.claude/skills/gr-commands-reference.md` aanmaken (gedetailleerde command-docs, lazy loaded)
- [ ] Test: vraag de advisor om advies via Agent tool

### Fase 2 — Skill File + Skill Creator
- [ ] `.claude/skills/gr-advisor.md` aanmaken (Encoded Preference type)
- [ ] Test auto-invocatie bij research-achtige prompts
- [ ] **Valideer met Skill Creator plugin** (`/plugin` → `skill-creator`):
  - Description-optimalisatie (false positive/negative testen)
  - Fidelity evals (volgt het de 4-stap workflow?)
  - A/B benchmarking van description varianten

### Fase 3 — CLAUDE.md Minimale Correctie
- [ ] Drie regels toevoegen aan CLAUDE.md (zie §3.1)
- [ ] Verifieer: NIET uitgebreider dan 5 regels

### Fase 4 — Hook Nudge (optioneel, alleen als Fase 1-2 onvoldoende zijn)
- [ ] Hook toevoegen aan `.claude/settings.json`
- [ ] Keyword-patroon tunen (niet te noisy)

### Fase 5 — Integratie Test
- [ ] Volledige workflow: gebruikersintentie → adviseur → uitvoering → terugkoppeling
- [ ] Edge cases: gebruiker wijst advies af, alternatief aanbieden
- [ ] Agent Teams (experimenteel): test met `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- [ ] Performantie: advisor latentie acceptabel?

---

## 6. Succes Criteria

| Criterium | Meetbaar | Drempel |
|---|---|---|
| Correcte toolkeuze | % sessies met optimale /gr command | >80% |
| Dubbel werk vermeden | % gevallen waar recall eerst gesuggereerd | >90% |
| Gebruikerstevredenheid | Expliciete acceptatie van advies | >70% |
| Latentie | Tijd tot aanbeveling | <5 seconden |

---

## 7. Open Vragen voor Implementatie

1. **Agent file model-override**: Ondersteunt Claude Code `model:` frontmatter in agent files, of erft het van de CLI configuratie? (Bevestigd in best-practice repo dat `model:` ondersteund is, maar versiespecifiek)
2. **Agent skills preloaded**: Werkt `skills:` veld in agent frontmatter in huidige Claude Code versie? (Bevestigd in best-practice repo als v2.1.33+ feature)
3. **Auto-invocatie drempel**: Hoe precies is de skill trigger? Gebruik Skill Creator voor description-optimalisatie vóór productie.
4. **Skill vs agent file dubbele activatie**: Als beide aanwezig zijn, hoe vermijden we dubbele activatie? Overweeg: agent file alleen, zonder losse skill file.
5. **Agent Teams experimenteel**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` vereist. Ontwerp kern-functionaliteit zonder afhankelijkheid van experimentele features.
6. **CLAUDE.md re-evaluatie**: Wordt CLAUDE.md gelezen bij elke tool-call of alleen bij session start? (Academisch bewijs suggereert startup-only; gebruik dus niet voor dynamische routing)
7. **Backward compatibility**: Bestaande /gr workflow scripts — worden die verstoord door de advisor?
