---
source: web research
topic: "Specialized workflow advisor agent for the /gr plugin (video-research-mcp) in Claude Code — design patterns, competing hypotheses, implementation options"
analyzed: 2026-03-07T12:00:00Z
updated: 2026-03-07T13:05:00Z
scope: moderate
findings_count: 14
evidence_tiers:
  confirmed: 5
  strong_indicator: 4
  inference: 3
  speculation: 1
  unknown: 1
---

# /gr Workflow Advisor Agent — Research Analysis

> Researched on 2026-03-07 12:00
> Scope: moderate | Multiple parallel searches + Gemini Pro deep research

## Executive Summary  <!-- 2026-03-07 12:00 -->

A specialized workflow advisor agent for the `/gr` plugin ecosystem is architecturally feasible within Claude Code's confirmed primitives (skills, agent files, the Agent tool, agent teams). The strongest design is a **layered hybrid**: an always-on `.claude/agents/gr-advisor.md` agent file providing baseline routing awareness, combined with an on-demand `/gr:advisor` skill that spawns an Opus 4.6 subagent for rich back-and-forth consultation. Hook-based routing (Hypothesis 2) is confirmed to be deterministic shell execution only — unsuitable for semantic LLM routing without an external model call. A pure MCP meta-orchestrator (Hypothesis 4) is feasible but risks context degradation. The key architectural insight: skills already have native "auto-invocation" when Claude deems them relevant — leveraging this is the lowest-friction path.

---

## Findings  <!-- 2026-03-07 12:00 -->

### CONFIRMED

1. **Claude Code Skills support auto-invocation** — `.claude/skills/SKILL.md` files are discovered and auto-invoked by Claude when the skill's description matches the user's intent. This is not user-triggered; Claude itself decides when to invoke a skill based on LLM reasoning over the skill descriptions. A `/gr:advisor` skill with a well-crafted trigger description could be auto-invoked when research tasks are detected. (Source: lobehub.com/skills + Claude Code official docs on skills)

2. **Agent Teams are a confirmed Claude Code primitive** — Anthropic's native "Swarm" mode provides a Team Lead + multiple Teammates pattern with mailbox-style `SendMessage` for inter-agent communication, a shared task list, and parallel execution across separate context windows. A workflow advisor could operate as a permanent Teammate that receives messages from the main (Team Lead) instance. (Source: docs.anthropic.com/claude/docs/agent-teams)

3. **Hooks are deterministic shell commands, NOT LLM calls** — `PreToolUse`, `PostToolUse`, `SessionStart`, and `UserPromptSubmit` hooks run shell scripts. They cannot perform semantic routing or LLM reasoning by themselves without making an external API call. This fundamentally constrains hook-based routing (Hypothesis 2): hooks are best for hard rules (block/allow/inject static context), not soft workflow guidance. (Source: docs.anthropic.com/claude/docs/hooks)

4. **Agent files in `.claude/agents/` define specialized personas** — Subagents can be pre-defined with custom system prompts, tool access, and model selection. An `gr-advisor.md` agent file would be auto-loaded as a team member and carry deep `/gr` knowledge without requiring a separate skill file. (Source: multiple community sources, dometrain.com/blog, freek.dev/2025)

5. **Workflow Advisor as a pattern already exists in the ecosystem** — lobehub.com/skills/workflow-advisor and mcpmarket.com/skill/claude-workflow-builder both implement advisor agents that map "architectural pain points" to concrete configurations. The pattern is established. Community frameworks (claude-flow, ruflo) extend this to multi-agent swarms with 60+ specialized agents.

### STRONG INDICATOR

6. **Skill auto-invocation + subagent spawn is the richest combination** — A `/gr:advisor` skill file that (a) provides a descriptive trigger so Claude auto-invokes it, and (b) spawns an Opus 4.6 subagent with full `/gr` knowledge, combines the low-friction auto-invocation with full LLM reasoning. The subagent communicates back via the task result. Multiple community sources implement this pattern (Codex Workflow Advisor, AB Method). (Source: mcpmarket.com/skill/codex-workflow-advisor, github.com/AyoubBensalah/ab-method)

7. **Back-and-forth communication requires Agent Teams or multi-turn subagent** — For iterative consultation (advisor ↔ main Claude), the Agent Teams pattern (SendMessage) or a multi-turn subagent session is required. Simple subagent calls (one-shot Agent tool) return a result but don't support back-and-forth. The `video_continue_session` pattern in this codebase is a direct analogue: persistent session state enabling multi-turn interaction. (Source: Claude Agent SDK docs, project codebase patterns)

8. **Tool Search Tool enables dynamic tool discovery** — Anthropic's Tool Search Tool allows Claude to discover thousands of tools on-demand without loading all schemas into context. Applied to the `/gr` advisor pattern: the advisor could expose a `recommend_gr_workflow` MCP tool that returns the right `/gr` command sequence, then the main Claude acts on it — avoiding full schema injection. (Source: anthropic.com/news/advanced-tool-use)

9. **CLAUDE.md + agent file hybrid gives zero-cost baseline routing** — For projects using the `/gr` plugin, a section in `CLAUDE.md` containing a `/gr` decision tree (when to use which command) provides baseline routing without any overhead. Community sources confirm this is the highest-leverage low-cost approach (humanlayer.dev: "CLAUDE.md is the highest-leverage point for an agent"). Combined with an agent file for richer cases, this is the recommended baseline.

### INFERENCE

10. **A UserPromptSubmit hook can inject lightweight awareness** — While hooks can't do LLM routing, a `UserPromptSubmit` hook could detect keywords ("research", "video", "analyze") via grep and inject a system note: "Note: /gr:advisor available for workflow guidance." This adds near-zero cost but nudges both Claude and the user toward the advisor without being intrusive. Already demonstrated in this project's SessionStart hook.

11. **MCP meta-orchestrator (Hypothesis 4) risks context degradation** — Adding a meta-orchestrator MCP tool shifts the tool-selection burden without eliminating it. If the tool's output is large or the main agent misinterprets it, context degrades. The pattern is most effective when the orchestrator returns a structured, minimal recommendation (e.g., `{"command": "/gr:research", "reason": "..."}`) rather than a full analysis.

12. **Opus 4.6 as the advisor model is optimal for reasoning quality** — Per project conventions (CLAUDE.md: "Opus 4.6 — default for all agents and subagents"), the advisor should use Opus 4.6. The advisor's job (interpreting user intent, mapping to workflows, anticipating edge cases) is a reasoning-heavy task that benefits from the highest-capability model. Sonnet 4.6 is acceptable for cost-sensitive deployments.

### SPECULATION

13. **Future Anthropic native orchestration may render custom advisors obsolete** — Multiple sources hint at Anthropic's internal roadmap including native middleware interception and multi-agent orchestration features. If Claude Code natively gains "workflow routing" capabilities, custom advisor agents may be superseded. Building on confirmed primitives (skills, agent files) rather than exotic workarounds protects against this.

### UNKNOWN

14. **Exact limits of CLAUDE.md dynamic state updating during sessions** — It is undocumented how frequently Claude re-evaluates CLAUDE.md during an active session. If it's only read at startup, embedded decision trees cannot react to mid-session state changes. This affects the viability of Hypothesis 5 as a standalone solution.

---

## Competing Hypotheses — Verdict Table  <!-- 2026-03-07 12:00 -->

| Hypothesis | Feasibility | Cost | Interactivity | Recommended? |
|---|---|---|---|---|
| H1: `/gr:advisor` skill file (slash command) | HIGH | Low | One-shot | Yes — as entry point |
| H2: Hook-based auto-router | MEDIUM | Near-zero | None (static inject) | Partial — keyword nudge only |
| H3: Opus 4.6 subagent team member | HIGH | Medium | Full back-and-forth | Yes — for complex cases |
| H4: MCP meta-orchestrator tool | MEDIUM | Low-medium | One-shot structured | Optional — lightweight variant |
| H5: CLAUDE.md decision tree | HIGH | Zero | None | Yes — as baseline layer |

**Winner: Layered hybrid of H1 + H3 + H5**, with H2 as optional lightweight nudge.

---

## Recommended Architecture  <!-- 2026-03-07 12:00 -->

### Layer 0 — Baseline (Zero cost, always-on)
**File:** `CLAUDE.md` section or `.claude/rules/gr-routing.md`
- Decision tree: when to use `/gr:research` vs `/gr:video` vs `/gr:analyze` vs `/gr:research-deep`
- Shapes the main Claude instance's baseline `/gr` knowledge
- Cost: 0 tokens extra at inference time (baked into session context)

### Layer 1 — Agent File (Low cost, persistent persona)
**File:** `.claude/agents/gr-advisor.md`
- Defines an Opus 4.6 "GR Workflow Advisor" teammate
- Deep knowledge of all 28 video-research-mcp tools, all /gr commands, their use cases, gotchas
- Auto-available as a team member when agent teams are active
- Receives `SendMessage` from main Claude: "User wants to X, what workflow?"

### Layer 2 — Skill (On-demand, explicit or auto-invoked)
**File:** `.claude/skills/gr-advisor.md`
- Trigger: auto-invoked when research/video/analysis intent detected
- Action: spawns Opus 4.6 subagent with full /gr knowledge
- Returns: structured workflow recommendation + rationale
- Supports back-and-forth via multi-turn Agent call pattern

### Layer 3 — Hook nudge (Optional, keyword-based)
**File:** `.claude/settings.json` hooks section
- `UserPromptSubmit` hook: grep for research/video keywords → inject "Tip: /gr:advisor can help plan this workflow"
- Deterministic, zero-LLM-cost
- Purely informational, not routing

---

## Sources  <!-- 2026-03-07 12:00 -->

- docs.anthropic.com/claude/docs/agent-teams — Official agent teams documentation
- docs.anthropic.com/claude/docs/skills — Official skills documentation
- docs.anthropic.com/claude/docs/hooks — Official hooks documentation
- anthropic.com/news/advanced-tool-use — Tool Search Tool announcement
- lobehub.com/skills/workflow-advisor — Workflow Advisor skill pattern
- mcpmarket.com/skill/codex-workflow-advisor — Codex Workflow Advisor implementation
- mcpmarket.com/skill/agent-architect — Agent architect patterns
- github.com/AyoubBensalah/ab-method — AB Method research→plan→execute pattern
- github.com/ruvnet/claude-flow — Claude Flow multi-agent orchestration
- humanlayer.dev/blog/writing-good-claude-md — CLAUDE.md as highest-leverage point
- dometrain.com/blog/perfect-claude-md-for-claude-code — Agent personas via .claude/agents/
- github.com/ThibautMelen/agentic-workflow-patterns — Anthropic-validated patterns

---

## Open Questions  <!-- 2026-03-07 12:00 -->

1. Does CLAUDE.md get re-evaluated mid-session, or only at startup? This affects H5 viability.
2. What is the exact communication protocol for multi-turn Agent teams back-and-forth in this project's setup?
3. Can a `UserPromptSubmit` hook output be structured (JSON) to selectively inject different hints based on detected intent?
4. What is the latency overhead of spawning an Opus 4.6 subagent for simple routing decisions? Is there a threshold below which H4 (MCP tool) is preferable?
5. Should the advisor also have access to the user's past `/gr` research sessions (via `knowledge_search`) to provide continuity-aware recommendations?

---

## Methodology Critique  <!-- 2026-03-07 12:00 -->

Research relied on web-grounded Gemini Flash searches + Gemini Pro deep analysis. Gemini Pro incorrectly flagged Opus 4.6 as non-existent (it lacks knowledge of the current model lineup per our project context). All Gemini Pro findings were cross-checked against web search results and project CLAUDE.md. No functional prototypes were built — all feasibility assessments are theoretical. Hook behavior and CLAUDE.md re-evaluation frequency require empirical testing.

---

## Weaviate Recall — Aanvullende Bevindingen  <!-- 2026-03-07 12:45 -->

Vier parallelle searches op 2.359 objecten (12 collecties). Kritieke correcties en aanvullingen:

### CONFIRMED (nieuw via recall)

**F15: Skills hebben TWEE patterns** — (1) Standalone skills (triggered door description matching), (2) **Agent skills preloaded at startup** — gedefinieerd in sub-agent frontmatter via `skills:` veld. Agent skills worden automatisch geladen wanneer de agent start. Dit is architecturaal cruciaal: de gr-advisor agent file kan zijn eigen skills bundelen zonder aparte invocatie.
> Bron: ConceptKnowledge `claude-code-best-practice` (shanraisshan, 2026-03, github.com/shanraisshan/claude-code-best-practice)

**F16: Sub-agent frontmatter ondersteunt volledige configuratie** — Velden: `name/description/tools/model/memory/skills/hooks/isolation`. Een agent kan zijn eigen model, tools, skills én hooks hebben. Dit bevestigt dat `.claude/agents/gr-advisor.md` volledig zelfstandig geconfigureerd kan worden.
> Bron: Zelfde bron

**F17: Canonical architectuurhiërarchie is Command → Agent → Skill** — Dit is de bevestigde patroon-volgorde in Claude Code. Een `/gr:advisor` command activeert een Agent, die zijn eigen Skills gebruikt voor specifieke taken (kennisbank check, command-selectie, etc.).

**F18: Skill Creator is een officieel Anthropic plugin** — Biedt evals, A/B benchmarking, en description-optimalisatie voor skills. Twee skill-types: (a) Capability Uplift (compenseert zwaktes) en (b) **Encoded Preference** (enforceert multi-stap workflows). De gr-advisor is een Encoded Preference skill — de evaluatiemethode verschilt van capability uplift.
> Bron: VideoAnalyses (Chase AI, "Claude Code Skills Just Got a MASSIVE Upgrade", youtube.com/watch?v=UxfeF4bSBYI)

**F19: Progressive disclosure is de juiste pattern voor kennislading** — In plaats van alle /gr command-kennis in één groot blok, laadt de skill root-instructies first en sub-bestanden (bijv. `research-commands.md`, `video-commands.md`) alleen wanneer relevant. Dit houdt het context-venster lean. Succesvol bewezen in de Remotion agent skill.
> Bron: SessionTranscripts (video-continue_session analyse over Remotion skill)

### STRONG INDICATOR (herzien via recall)

**F7-herzien: Agent Teams zijn EXPERIMENTEEL** — Vereist `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var. Peer-to-peer communicatie (zonder supervisor) is de nieuwe feature. Kosten: ~$7-8 per Agent Team taak. Het ontwerp mag hier niet volledig op steunen voor kern-functionaliteit.
> Bron: WebSearchResults (shipyard.build, alexop.dev, Agent Teams 2026 guide)

### CONFIRMED (kritieke correctie voor Laag 0)

**F20: Uitgebreide CLAUDE.md context VERSLECHTERT prestaties** — Academische studie: developer-geschreven context files verbeterden succes slechts +4%; LLM-gegenereerde context files verlaagden prestaties -3% en verhoogden kosten >20%. Modern LLMs zijn beter in zelf zoeken dan statische overzichten lezen. **Implicatie: Laag 0 moet minimaal zijn** — niet een volledige beslisboom, maar alleen specifieke "band-aids" voor terugkerende routeringsfouten (max 5-10 regels).
> Bron: VideoAnalyses (Theo analyse academische studie over AGENT.md/CLAUDE.md, bv. "CLAUDE.md files often WORSEN performance")

**F21: Description-optimalisatie is kritiek voor betrouwbare auto-invocatie** — Skill Creator optimaliseert de description om false positives (activeert wanneer het niet moet) en false negatives (activeert niet wanneer het wel moet) te voorkomen. De gr-advisor trigger-description moet getest worden met Skill Creator voordat productie.

## Evidence Network  <!-- 2026-03-07 12:30 -->

### Nodes

- **Finding 1** (CONFIRMED) — Skills auto-invoke via LLM intent matching
- **Finding 2** (CONFIRMED) — Agent Teams with SendMessage enable back-and-forth
- **Finding 3** (CONFIRMED) — Hooks are deterministic shell only, not LLM-capable
- **Finding 5** (CONFIRMED) — Workflow Advisor pattern is established in ecosystem
- **Finding 6** (STRONG INDICATOR) — Skill + subagent spawn is richest combination
- **Finding 9** (STRONG INDICATOR) — CLAUDE.md zero-cost baseline is highest leverage
- **Finding 11** (INFERENCE) — MCP meta-orchestrator risks context degradation
- **Open Question 1** — CLAUDE.md re-evaluation frequency unknown
- **Open Question 5** — Past session continuity for advisor

### Relationships

- Finding 1 → *enables* → Finding 6 (auto-invocation enables the skill+subagent pattern)
- Finding 2 → *enables* → Finding 6 (back-and-forth via Agent Teams)
- Finding 3 → *constrains* → Finding (H2 hook router limited to static injection)
- Finding 5 → *validates* → Finding 6 (ecosystem precedent)
- Finding 9 → *complements* → Finding 6 (zero-cost baseline + rich advisor)
- Finding 11 → *argues against* → H4 as standalone solution
- Open Question 1 → *challenges* → Finding 9 (if CLAUDE.md is startup-only)
- Open Question 5 → *extends* → Finding 6 (continuity-aware advisor is richer)

---

## Visualization  <!-- 2026-03-07 13:05 -->

![Evidence Network](evidence-network.png)
Interactive: [Open Evidence Network](evidence-network.html)
