From 6c4429a26f4ea727ef6e2a6316e0f24db20923b5 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:44:08 +0200 Subject: [PATCH 01/14] feat: add gemini-reviewer agent for generalist diff review --- agents/gemini-reviewer.md | 108 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 agents/gemini-reviewer.md diff --git a/agents/gemini-reviewer.md b/agents/gemini-reviewer.md new file mode 100644 index 0000000..d17ee14 --- /dev/null +++ b/agents/gemini-reviewer.md @@ -0,0 +1,108 @@ +--- +name: gemini-reviewer +description: | + Use proactively when finalizing a diff or PR for a generalist third-reviewer + pass that the other agents do not cover: security, threading correctness, + library/version drift, doc accuracy, dead code, and complexity. NOT for + research (use gemini-researcher), claim validation (use gemini-validator), + or devil's-advocate brainstorming (use gemini-challenger). Returns structured + JSON {verdict, strengths, issues, next_actions}. +tools: + - mcp__gemini__gemini_chat + - mcp__gemini__gemini_search_grounded + - Read + - Grep + - Glob + - Bash +model: sonnet +color: cyan +maxTurns: 10 +skills: + - gemini-when-to-use +--- + +You are gemini-reviewer, a generalist third-reviewer powered by Google Gemini. +Your role is to review a diff or PR for the cross-cutting concerns that the +other four Gemini agents do not own: security, threading/concurrency +correctness, library and API version drift, documentation accuracy, dead code, +and unnecessary complexity. + +## Workflow + +You have 10 turns. Budget them: + +1. **Turn 1-2: Establish scope.** If the brief names BASE_SHA and HEAD_SHA, run + `git diff $BASE_SHA $HEAD_SHA --stat` then targeted `git show` / + `git diff $BASE_SHA $HEAD_SHA -- ` on the changed files. If the brief + names files or a path instead, Read those directly. +2. **Turn 3-4: Read for context.** Use Read/Grep/Glob to pull in surrounding + code the diff depends on, so your review is grounded, not surface-level. +3. **Turn 5-7: Call Gemini once.** Call mcp__gemini__gemini_chat with the diff + content and ask for a review focused ONLY on: security, threading + correctness, library/version drift, doc accuracy, dead code, complexity. +4. **Turn 8 (optional): Verify a version fact.** If and only if a finding hinges + on a version-specific or post-cutoff fact, call + mcp__gemini__gemini_search_grounded ONCE to confirm it. +5. **Turn 9: Synthesize.** Draft the JSON verdict. +6. **Turn 10: Emit ONLY the JSON** (no other content in this turn). + +## What you are NOT + +- You are NOT gemini-validator. You do not validate a plan or a done-claim + against the original ask. If asked to do that, say so and defer. +- You are NOT gemini-researcher. You do not perform open-ended research. A + single grounded lookup to confirm one version fact is the only exception. +- You are NOT gemini-challenger. You do not argue alternatives or play devil's + advocate on architecture decisions. That is the challenger's job. +- You are NOT a yes-machine. If Gemini's findings contradict the dispatching + Claude's draft, surface BOTH positions with their evidence. Do not silently + defer to either side. + +## Disagreement protocol + +If Gemini's review contradicts a claim or choice in the diff or the dispatching +brief, record both positions in the verdict (one issue entry stating Gemini's +position with its citation, the strengths or next_actions noting the author's +rationale if known). Let the human decide. Tie-break toward the side with the +more concrete, recent (post-2024) citation. + +## Cap + +At most ONE mcp__gemini__gemini_chat call and at most ONE +mcp__gemini__gemini_search_grounded call per dispatch, unless the brief +explicitly authorizes more. Latency and token cost matter. + +## Output Format + +**CRITICAL: Your FINAL turn must contain ONLY this JSON object, with no +surrounding text, no code fences, no preamble, and no explanatory prose.** + +The verdict-handler hook parses your final assistant message with jq, so any +non-JSON content breaks the contract and the verdict is silently discarded. Do +not narrate your work in the last turn. Do not say "Here is the verdict:" before +the JSON. Do not wrap it in ```json fences. + + { + "verdict": "approved|changes_requested|unknown", + "strengths": [], + "issues": { + "critical": [], + "important": [], + "minor": [] + }, + "next_actions": [] + } + +- **approved**: no critical or important issues; merge is safe. +- **changes_requested**: at least one critical or important issue found. +- **unknown**: insufficient diff/context to judge confidently. + +Each issue string SHOULD carry a `file:line` reference where applicable. All +arrays may be empty. If verdict is approved, the critical and important arrays +MUST be empty. + +## Failure-mode discipline + +If at turn 9 you do not have enough information for a confident verdict, emit +verdict: "unknown" with a clear issues entry explaining what was missing. Never +run out of turns mid-response. Partial responses are worse than unknown. From 86d3dd501c8aecfa54f691106e75c5fdfb5e5725 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:44:34 +0200 Subject: [PATCH 02/14] test: cover gemini-reviewer agent in agents.bats --- tests/agents.bats | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/tests/agents.bats b/tests/agents.bats index f7aac4c..8e50268 100755 --- a/tests/agents.bats +++ b/tests/agents.bats @@ -2,11 +2,12 @@ AGENTS_DIR="agents" -@test "all 4 agent files exist" { +@test "all 5 agent files exist" { [ -f "$AGENTS_DIR/gemini-validator.md" ] [ -f "$AGENTS_DIR/gemini-challenger.md" ] [ -f "$AGENTS_DIR/gemini-researcher.md" ] [ -f "$AGENTS_DIR/gemini-summarizer.md" ] + [ -f "$AGENTS_DIR/gemini-reviewer.md" ] } extract_frontmatter() { @@ -50,15 +51,24 @@ extract_frontmatter() { echo "$FM" | grep -q "^memory: project" } +@test "gemini-reviewer has required frontmatter fields" { + FM=$(extract_frontmatter "$AGENTS_DIR/gemini-reviewer.md") + echo "$FM" | grep -q "^name: gemini-reviewer" + echo "$FM" | grep -q "^model: sonnet" + echo "$FM" | grep -q "^color: cyan" + echo "$FM" | grep -q "^maxTurns: 10" + echo "$FM" | grep -q "mcp__gemini__gemini_chat" +} + @test "all agents preload gemini-when-to-use skill" { - for agent in validator challenger researcher summarizer; do + for agent in validator challenger researcher summarizer reviewer; do FM=$(extract_frontmatter "$AGENTS_DIR/gemini-${agent}.md") echo "$FM" | grep -q "gemini-when-to-use" done } @test "no agent uses disallowed tools" { - for agent in validator challenger researcher summarizer; do + for agent in validator challenger researcher summarizer reviewer; do FM=$(extract_frontmatter "$AGENTS_DIR/gemini-${agent}.md") ! echo "$FM" | grep -q "Agent" ! echo "$FM" | grep -q "AskUserQuestion" @@ -68,7 +78,7 @@ extract_frontmatter() { } @test "agent descriptions start with 'Use proactively'" { - for agent in validator challenger researcher summarizer; do + for agent in validator challenger researcher summarizer reviewer; do FM=$(extract_frontmatter "$AGENTS_DIR/gemini-${agent}.md") echo "$FM" | grep -q "Use proactively" done From 9487c32fb40c21292bcc0cbef8db243e218ee0fb Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:44:56 +0200 Subject: [PATCH 03/14] feat: add gemini-consult dispatch-rule skill --- skills/gemini-consult/SKILL.md | 76 ++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 skills/gemini-consult/SKILL.md diff --git a/skills/gemini-consult/SKILL.md b/skills/gemini-consult/SKILL.md new file mode 100644 index 0000000..e0ce382 --- /dev/null +++ b/skills/gemini-consult/SKILL.md @@ -0,0 +1,76 @@ +--- +description: Dispatch rule for consulting the five Gemini agents. Read this when deciding whether to get a Gemini second opinion and which agent to route to (researcher, validator, challenger, summarizer, reviewer). Enforces a one-consult-per-turn cap on manual dispatches. +--- + +# Gemini Consult (dispatch rule) + +This skill tells you (the main Claude) WHEN to consult Gemini, WHICH of the five +agents to dispatch, and the cap that keeps consults cheap. It complements +`gemini-when-to-use` (which routes among the seven capability *skills* for raw +MCP calls); this skill routes among the five *agents* for structured, +second-opinion work. + +Gemini complements your reasoning. It does not replace it. + +## When to consult + +Dispatch a Gemini agent when ANY of these is true: + +- **Uncertain about a plausibly post-cutoff fact** (library version, API shape, + CVE, pricing, changelog). Route to gemini-researcher. +- **A specific claim needs external verification** before you rely on it. Route + to gemini-validator. +- **Two or more valid approaches are on the table** and you want an + outside-the-context-window opinion. Route to gemini-challenger. +- **Finalizing a diff or PR** for cross-cutting concerns (security, threading, + version drift, doc accuracy, dead code, complexity). Route to gemini-reviewer. +- **About to compact or hand off a long session** and want the state preserved. + Route to gemini-summarizer. + +## Routing table + +| Need | Agent | +|---|---| +| Live facts / citations | gemini-researcher | +| Verify a specific claim | gemini-validator | +| Challenge a decision / alternatives | gemini-challenger | +| Generalist diff / PR review | gemini-reviewer | +| Compress session / risk map | gemini-summarizer | + +Agents do not call each other (subagents cannot spawn subagents). You are the +router: pick the one agent that matches and dispatch it. + +## The one-consult-per-turn cap + +At most ONE manual, rule-driven Gemini consult per turn, across all five agents. +Each consult adds latency and tokens; the value comes from being selective. + +This cap counts only the consults YOU choose to dispatch from this rule. The +always-on hooks (session-start risk map, per-prompt grounding, plan validation, +destructive-op challenge, pre-compact summary, done-claim validation) are a +SEPARATE channel and are NOT counted against this cap. To quiet the automatic +channel, the user can run `/gemini-plugin:gemini-brainstorm-off`. + +## Do NOT consult when + +- The user said "no Gemini", "skip validation", or "just do it". +- The fact is project-internal (repo state, file contents, build output) and you + can Read it directly. +- You already have direct evidence (a file Read, command output) that settles + the question. +- The same question was already consulted earlier this turn. + +## Disagreement protocol + +If a Gemini agent contradicts your draft: + +1. Do NOT silently defer. +2. Surface BOTH positions to the user with their citations. +3. The user picks. If the user has no preference, default to Gemini's position + when its citation is concrete and recent (post-2024); default to yours when + Gemini's citation is stale or low-quality. + +## Do NOT use this skill for + +- Making raw Gemini MCP calls (use the capability skills via `gemini-when-to-use`). +- Non-Gemini routing decisions. From 13428a7da2e5be3642eb4a4a02a6fe38b99cd76c Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:45:07 +0200 Subject: [PATCH 04/14] test: cover gemini-consult skill in skills.bats --- tests/skills.bats | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/skills.bats b/tests/skills.bats index 57fb37d..8ae99a2 100644 --- a/tests/skills.bats +++ b/tests/skills.bats @@ -4,6 +4,7 @@ SKILLS_DIR="skills" EXPECTED_SKILLS=( "gemini-when-to-use" + "gemini-consult" "gemini-chat-and-reason" "gemini-research-grounded" "gemini-file-analysis" @@ -13,7 +14,7 @@ EXPECTED_SKILLS=( "gemini-audio-tts-music" ) -@test "all 8 skill directories exist with SKILL.md" { +@test "all 9 skill directories exist with SKILL.md" { for skill in "${EXPECTED_SKILLS[@]}"; do [ -f "$SKILLS_DIR/$skill/SKILL.md" ] done From 076aa41ebb80e58abf4e36e7f48df49a505c443a Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:45:32 +0200 Subject: [PATCH 05/14] feat: route gemini-reviewer through SubagentStop handler as advisory --- hooks/hooks.json | 2 +- tests/hooks-triggers.bats | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/hooks/hooks.json b/hooks/hooks.json index 1361bdf..0ab2079 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -45,7 +45,7 @@ ], "SubagentStop": [ { - "matcher": "gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer", + "matcher": "gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer|gemini-reviewer", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent-verdict-handler.sh", "async": false } ] diff --git a/tests/hooks-triggers.bats b/tests/hooks-triggers.bats index 1eb60eb..263c330 100644 --- a/tests/hooks-triggers.bats +++ b/tests/hooks-triggers.bats @@ -226,6 +226,13 @@ teardown() { [ "$status" -eq 0 ] } +@test "verdict-handler: reviewer changes_requested is advisory (exits 0)" { + TRANSCRIPT="$BATS_TMPDIR/transcript-$$.jsonl" + echo '{"type":"assistant","message":{"content":[{"text":"{\"verdict\":\"changes_requested\",\"issues\":{\"critical\":[\"sql injection at db.go:42\"]}}"}]}}' > "$TRANSCRIPT" + run bash -c "echo '{\"agent_type\":\"gemini-reviewer\",\"transcript_path\":\"${TRANSCRIPT}\"}' | ./hooks/subagent-verdict-handler.sh" + [ "$status" -eq 0 ] +} + # --- plugin disable --- @test "all hooks exit 0 when CLAUDE_PLUGIN_GEMINI_DISABLE_HOOKS=1" { From 3b9db72b48580e758a858d699a17417c3c4350d6 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:49:25 +0200 Subject: [PATCH 06/14] chore: bump version to 0.4.0 and update manifest description --- .claude-plugin/plugin.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 72a08a4..34d51b3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "gemini-plugin", "displayName": "Gemini Plugin", - "version": "0.3.0", - "description": "Wraps gemini-mcp into a Claude Code plugin so Gemini acts as a second opinion: validator/challenger/researcher/summarizer subagents, auto-trigger hooks, and 8 task-oriented skills.", + "version": "0.4.0", + "description": "Wraps gemini-mcp into a Claude Code plugin so Gemini acts as a second opinion: validator/challenger/researcher/summarizer/reviewer subagents, auto-trigger hooks, and 9 task-oriented skills.", "author": { "name": "azmym" }, "homepage": "https://github.com/azmym/gemini-plugin", "repository": "https://github.com/azmym/gemini-plugin", From b157f785f1ea4d91ef1b627d8d524b77e007fb2a Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:49:38 +0200 Subject: [PATCH 07/14] docs: add v0.4.0 changelog entry --- CHANGELOG.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e737e1d..57f0899 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ All notable changes to gemini-plugin are documented here. The format follows [Ke ## [Unreleased] +## [0.4.0] - 2026-05-29 + +### Added + +- **`gemini-reviewer` agent (5th subagent).** A generalist third-reviewer for diffs and PRs, covering the cross-cutting concerns the other four agents do not own: security, threading correctness, library/version drift, doc accuracy, dead code, and complexity. Modeled on the `gemini-assistant` "code review" mode from the IPTV project setup. Sonnet, `maxTurns: 10`, returns structured JSON `{verdict, strengths, issues, next_actions}`. It is advisory: a `changes_requested` verdict surfaces inline but does not block, because the reviewer is dispatched manually rather than by a hook. +- **`gemini-consult` dispatch-rule skill (9th skill).** Tells the main Claude when to consult Gemini, which of the five agents to route to, and enforces a one-consult-per-turn cap on manual dispatches (the always-on hooks are a separate, uncounted channel). Ports the disagreement protocol and "what you are NOT" scope guards from the IPTV `gemini-assistant` rule. + +### Changed + +- `gemini-reviewer` added to the `SubagentStop` matcher so its transcript is read and persisted to plan-history. + ## [0.3.0] - 2026-05-28 ### Changed From 8b30f8d147ccceea1592a905893ec120194f08af Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:49:58 +0200 Subject: [PATCH 08/14] docs: add gemini-reviewer and consult cap to using-gemini rule --- rules/using-gemini.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/rules/using-gemini.md b/rules/using-gemini.md index 39835a0..92e882e 100644 --- a/rules/using-gemini.md +++ b/rules/using-gemini.md @@ -1,6 +1,6 @@ ## Gemini Plugin: Session Rules -The gemini-plugin is loaded. Four subagents assist you: +The gemini-plugin is loaded. Five subagents assist you: | Agent | Role | Spawn via | |---|---|---| @@ -8,6 +8,7 @@ The gemini-plugin is loaded. Four subagents assist you: | gemini-challenger | Devil's advocate; proposes alternatives, challenges destructive ops | Hook (PreToolUse Bash) or /gemini-plugin:gemini-challenge | | gemini-researcher | Search-grounded facts with citations; never opines without a URL | Hook (UserPromptSubmit) or /gemini-plugin:gemini-research | | gemini-summarizer | Compresses session state; writes risk maps at SessionStart | Hook (SessionStart, PreCompact) | +| gemini-reviewer | Generalist diff/PR review: security, threading, version drift, docs, dead code | /gemini-plugin:gemini-consult rule (manual dispatch) | ### Always reach for Gemini when @@ -26,6 +27,7 @@ The gemini-plugin is loaded. Four subagents assist you: ### Cost discipline - Validator and researcher use sonnet; challenger and summarizer use opus. Per-prompt grounding now defaults on, so this is a real cost; opt out with /gemini-plugin:gemini-brainstorm-off if needed. +- Manual consults (researcher, validator, challenger, reviewer, summarizer via the gemini-consult rule) are capped at one per turn. The always-on hooks are a separate channel, not counted against that cap. - Deep research is opt-in only (via /gemini-plugin:gemini-research --deep) - One validation per artifact per session. No re-asking. - API key is configured at install time (stored in keychain). If unavailable, everything gracefully no-ops. From ecede54d00c14633fadaed2fc9d6feec513dd33d Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:50:13 +0200 Subject: [PATCH 09/14] docs: reflect 5th subagent (gemini-reviewer) in README --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8fcbea8..8450c58 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,8 @@ The plugin auto-registers the `gemini` MCP server. No separate `claude mcp add` | You ask about a library version, CVE, or live API | Prompt grounding hook | Gemini searches the web and injects citations before Claude answers | | Claude is about to compact context | Pre-compact hook | Gemini summarizes decisions and unresolved debt so the next session starts with full context | | Claude says it is finished | Done-claim hook | Gemini validates output against your original ask; blocks if something was missed | -| You want a second opinion right now | Slash command | Any of the four subagents on demand, for any artifact or question | +| You want a second opinion right now | Slash command or consult rule | Any of the five subagents on demand, for any artifact or question | +| You are finalizing a diff or PR | gemini-reviewer (manual consult) | A generalist review for security, threading, version drift, docs, dead code, and complexity | ## Architecture at a glance @@ -84,7 +85,7 @@ The plugin auto-registers the `gemini` MCP server. No separate `claude mcp add` gemini-plugin architecture: three layers (hooks coordinate, subagents reason, MCP executes) connecting Claude Code to Gemini

-Three layers do the work: **hooks** coordinate (read events, apply gates, emit directives), **subagents** reason (validator, challenger, researcher, summarizer with structured JSON verdicts), and the **gemini-mcp** server executes (calls Gemini, Imagen, Veo, and Lyria via Google AI Studio). For the full architecture write-up, see [docs/reference/architecture.md](docs/reference/architecture.md). +Three layers do the work: **hooks** coordinate (read events, apply gates, emit directives), **subagents** reason (validator, challenger, researcher, summarizer, and reviewer with structured JSON verdicts), and the **gemini-mcp** server executes (calls Gemini, Imagen, Veo, and Lyria via Google AI Studio). For the full architecture write-up, see [docs/reference/architecture.md](docs/reference/architecture.md). ## Slash commands From 374c509e61dcfaf5bf6744cbfa4b895cc4cdf0c4 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:50:29 +0200 Subject: [PATCH 10/14] docs: document gemini-reviewer in subagents reference --- docs/reference/subagents.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/reference/subagents.md b/docs/reference/subagents.md index 8425f37..7367351 100644 --- a/docs/reference/subagents.md +++ b/docs/reference/subagents.md @@ -1,6 +1,6 @@ # Subagents Reference -The plugin ships 4 specialized subagents. Each has a focused role, restricted tools, and a structured JSON output schema. They are spawned by Claude via the Agent tool (triggered by hooks or slash commands). +The plugin ships 5 specialized subagents. Each has a focused role, restricted tools, and a structured JSON output schema. They are spawned by Claude via the Agent tool (triggered by hooks or slash commands). ## Subagent summary @@ -10,6 +10,7 @@ The plugin ships 4 specialized subagents. Each has a focused role, restricted to | gemini-challenger | opus | high | 8 | (none) | red | false | | gemini-researcher | sonnet | medium | 12 | (none) | green | true | | gemini-summarizer | opus | high | 4 | project | purple | false | +| gemini-reviewer | sonnet | medium | 10 | (none) | cyan | false | All subagents preload the `gemini-when-to-use` skill via the `skills:` frontmatter field. @@ -153,6 +154,31 @@ Output schema: **Memory:** project-scoped. Accumulates knowledge about the codebase across sessions. +## gemini-reviewer + +**Role:** Generalist third-reviewer for diffs/PRs: security, threading correctness, library/version drift, doc accuracy, dead code, complexity. Covers concerns the other four agents do not own. + +**Tools:** +- `mcp__gemini__gemini_chat` +- `mcp__gemini__gemini_search_grounded` +- Read, Grep, Glob, Bash + +**Output schema:** + +```json +{ + "verdict": "approved | changes_requested | unknown", + "strengths": ["what the change does well"], + "issues": {"critical": [], "important": [], "minor": []}, + "next_actions": ["concrete fixes with file:line where possible"] +} +``` + +**Triggered by:** +- the `/gemini-plugin:gemini-consult` dispatch rule (manual). Not wired to any trigger hook. + +**Advisory note:** `changes_requested` surfaces inline but does not block (the verdict handler only blocks on fail/block). + ## Plugin subagent constraints Per Claude Code documentation, plugin subagents: From be3bd3d4f4e01eab0a7f97b686a5fd3dde14d4b1 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:50:46 +0200 Subject: [PATCH 11/14] docs: document gemini-consult in skills reference --- docs/reference/skills.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/reference/skills.md b/docs/reference/skills.md index 2b2e8c0..ff28ac0 100644 --- a/docs/reference/skills.md +++ b/docs/reference/skills.md @@ -1,12 +1,13 @@ # Skills Reference -The plugin ships 8 task-oriented skills. Skills tell Claude WHEN to reach for Gemini and WHICH MCP tool to use. They load on-demand when Claude determines a match based on the description field. +The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Gemini and WHICH MCP tool to use. They load on-demand when Claude determines a match based on the description field. ## Skill index | Skill | MCP tools | Auto-invoked? | |---|---|---| | [gemini-when-to-use](#gemini-when-to-use) | (none, decision guide) | Yes (broadest description) | +| [gemini-consult](#gemini-consult) | (none, dispatch rule) | Yes (routes among the 5 agents) | | [gemini-chat-and-reason](#gemini-chat-and-reason) | `gemini_generate`, `gemini_chat` | Yes | | [gemini-research-grounded](#gemini-research-grounded) | `gemini_search_grounded`, `gemini_start_research`, `gemini_get_research_report` | Yes | | [gemini-file-analysis](#gemini-file-analysis) | `gemini_analyze_file` | Yes | @@ -27,6 +28,14 @@ The plugin ships 8 task-oriented skills. Skills tell Claude WHEN to reach for Ge **Invocation:** `/gemini-plugin:gemini-when-to-use` or auto-invoked when Claude is uncertain +## gemini-consult + +**Description:** Dispatch rule for the five Gemini agents. Routes a consult to the right agent and enforces a one-consult-per-turn cap on manual dispatches. + +**Purpose:** Complements gemini-when-to-use. Where gemini-when-to-use routes among the seven capability skills (raw MCP calls), gemini-consult routes among the five subagents (researcher, validator, challenger, reviewer, summarizer) for structured second-opinion work, and holds the per-turn cap plus the disagreement protocol. + +**Invocation:** Auto-consulted when Claude is deciding whether and how to get a Gemini second opinion. No MCP tools (decision guide only). + ## gemini-chat-and-reason **Description:** Get a second opinion from Gemini via text generation or multi-turn chat. From 86767a4320ae5fdc7ee297bb33ed0d266cbb4679 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:51:17 +0200 Subject: [PATCH 12/14] docs: update architecture and hooks references for gemini-reviewer --- docs/reference/architecture.md | 11 +++++++---- docs/reference/hooks.md | 4 ++-- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index e8908ce..2af736a 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -8,7 +8,7 @@ This document describes the system architecture of gemini-plugin: how the compon graph TB subgraph "Claude Code Session" User[User] --> Claude[Main Claude Agent] - Claude --> Skills[8 Skills] + Claude --> Skills[9 Skills] Claude --> Commands[5 Slash Commands] end @@ -26,6 +26,7 @@ graph TB Claude --> |Agent tool| Challenger[gemini-challenger] Claude --> |Agent tool| Researcher[gemini-researcher] Claude --> |Agent tool| Summarizer[gemini-summarizer] + Claude --> |Agent tool| Reviewer[gemini-reviewer] end subgraph "MCP (execution layer)" @@ -33,6 +34,7 @@ graph TB Challenger --> MCP Researcher --> MCP Summarizer --> MCP + Reviewer --> MCP end subgraph "Google AI Studio" @@ -121,8 +123,8 @@ sequenceDiagram | Component | Count | Location | Purpose | |---|---|---|---| | Plugin manifest | 1 | `.claude-plugin/plugin.json` | Metadata, userConfig prompt, MCP server registration | -| Skills | 8 | `skills/*/SKILL.md` | When/how to use Gemini capabilities | -| Subagents | 4 | `agents/*.md` | Role-specific reasoning with structured output | +| Skills | 9 | `skills/*/SKILL.md` | When/how to use Gemini capabilities | +| Subagents | 5 | `agents/*.md` | Role-specific reasoning with structured output | | Commands | 5 | `commands/*.md` | User-invoked slash commands | | Hooks | 7 | `hooks/hooks.json` + `hooks/*.sh` | 6 triggers + 1 verdict handler | | Shared library | 2 | `hooks/lib/*.sh` | JSON helpers, gates, prompt builders | @@ -166,7 +168,7 @@ The plugin manifest auto-registers the gemini MCP server on install: } ``` -All 4 subagents inherit this MCP connection from the parent session (plugin subagents cannot define their own `mcpServers` in frontmatter). +All 5 subagents inherit this MCP connection from the parent session (plugin subagents cannot define their own `mcpServers` in frontmatter). ## State management @@ -199,5 +201,6 @@ State is local, session-scoped, and disposable. Deleting the data directory rese | gemini-challenger | Opus | Hardest reasoning task (creative alternatives + objections); bumped from Sonnet in v0.3.0 | | gemini-researcher | Sonnet | Multi-source synthesis and citation discipline; bumped from Haiku in v0.3.0 | | gemini-summarizer | Opus | Large-input compression with structured output; bumped from Sonnet in v0.3.0 | +| gemini-reviewer | Sonnet | Generalist diff/PR review; manual consult via the gemini-consult rule (added in v0.4.0) | All subagents call Gemini models via MCP (default: `gemini-3.5-flash` for chat/search, `gemini-3.1-pro-preview` for generate). The Claude model handles orchestration and JSON structuring; the Gemini model handles reasoning and web access. The Claude-side model bumps in v0.3.0 fixed a class of partial-response failures where validator and other agents were exiting before producing the final JSON verdict. diff --git a/docs/reference/hooks.md b/docs/reference/hooks.md index 55a4409..6f4d227 100644 --- a/docs/reference/hooks.md +++ b/docs/reference/hooks.md @@ -124,11 +124,11 @@ Patterns that look destructive but pass through (intentional false-positive guar | Field | Value | |---|---| | Event | `SubagentStop` | -| Matcher | `gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer` | +| Matcher | `gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer|gemini-reviewer` | | Gate | Transcript must exist and contain parseable JSON verdict | | Blocking | Conditional: exit 2 if verdict=fail or verdict=block; exit 0 otherwise | -**What it does:** Reads the subagent's transcript, extracts the final JSON verdict, applies the loop guard (identical verdict twice in a row is demoted to advisory), persists to plan-history.jsonl, and decides whether to block. +**What it does:** Reads the subagent's transcript, extracts the final JSON verdict, applies the loop guard (identical verdict twice in a row is demoted to advisory), persists to plan-history.jsonl, and decides whether to block. gemini-reviewer's verdict (changes_requested) is advisory and does not trigger the exit-2 block path (only fail/block block). **Stdin JSON:** `{"agent_type": "gemini-validator", "transcript_path": "/path/to/transcript.jsonl"}` From 6f4c5928ffdffd438deb72e2cc958a5b52b9ab55 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:54:14 +0200 Subject: [PATCH 13/14] docs: fix stale 'four subagent roles' to five in skills reference --- docs/reference/skills.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/skills.md b/docs/reference/skills.md index ff28ac0..1710a4e 100644 --- a/docs/reference/skills.md +++ b/docs/reference/skills.md @@ -18,7 +18,7 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge ## gemini-when-to-use -**Description:** Master router for the Gemini plugin. Covers cost discipline, anti-hallucination triggers, and the four subagent roles. +**Description:** Master router for the Gemini plugin. Covers cost discipline, anti-hallucination triggers, and the five subagent roles. **Purpose:** Loaded first, before any other gemini-* skill. Tells Claude: - Which subagent to use for which situation From be70b477c4304e6dba2cbaf59cdf9b38c8ae3e24 Mon Sep 17 00:00:00 2001 From: azmym Date: Fri, 29 May 2026 16:58:15 +0200 Subject: [PATCH 14/14] docs: update index and when-to-use router for 5 agents / 9 skills --- docs/index.md | 11 ++++++----- skills/gemini-when-to-use/SKILL.md | 5 +++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index b9d9745..75c64dc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,8 +13,8 @@ A Claude Code plugin that turns Google Gemini into a second-opinion assistant la | [Configure hooks](how-to/configure-hooks.md) | Enable, disable, or customize the automatic triggers | | **Reference** | | | [Architecture](reference/architecture.md) | System architecture, data flow, and component diagram | -| [Skills](reference/skills.md) | All 8 skills with descriptions and MCP tool mappings | -| [Subagents](reference/subagents.md) | All 4 subagents with frontmatter, tools, and output schemas | +| [Skills](reference/skills.md) | All 9 skills with descriptions and MCP tool mappings | +| [Subagents](reference/subagents.md) | All 5 subagents with frontmatter, tools, and output schemas | | [Hooks](reference/hooks.md) | All 7 hooks with event types, gates, and exit behavior | | [Commands](reference/commands.md) | All 5 slash commands with usage examples | | **Explanation** | | @@ -29,9 +29,10 @@ Plugin installs via marketplace ┌─────────────────────────────────────────────┐ │ gemini-plugin │ │ │ -│ 8 skills - when/how to use Gemini │ -│ 4 subagents - validator, challenger, │ -│ researcher, summarizer │ +│ 9 skills - when/how to use Gemini │ +│ 5 subagents - validator, challenger, │ +│ researcher, summarizer, │ +│ reviewer │ │ 7 hooks - auto-trigger on key events │ │ 5 commands - manual slash invocation │ │ 1 rule - session-level guidance │ diff --git a/skills/gemini-when-to-use/SKILL.md b/skills/gemini-when-to-use/SKILL.md index 80b761e..0862cfb 100644 --- a/skills/gemini-when-to-use/SKILL.md +++ b/skills/gemini-when-to-use/SKILL.md @@ -1,5 +1,5 @@ --- -description: Master router for the Gemini plugin. Use when uncertain whether a Gemini consult is warranted; covers cost discipline, anti-hallucination triggers, and the four subagent roles. Invoke before any other gemini-* skill. +description: Master router for the Gemini plugin. Use when uncertain whether a Gemini consult is warranted; covers cost discipline, anti-hallucination triggers, and the five subagent roles. Invoke before any other gemini-* skill. --- # Gemini When To Use @@ -28,7 +28,7 @@ Invoke a Gemini skill whenever the response would otherwise rely on: - A claim about a living document (spec, RFC, standard) that may have been updated. - An assertion about the current state of a third-party service or cloud provider. -## The four subagent roles (agents/ directory) +## The five subagent roles (agents/ directory) These are pre-built agent configurations for common Gemini workflows. Prefer them over raw MCP calls for structured tasks: @@ -38,6 +38,7 @@ These are pre-built agent configurations for common Gemini workflows. Prefer the | Summarizer | `agents/gemini-summarizer.md` | Condensing long documents, transcripts, or codebases | | Validator | `agents/gemini-validator.md` | Fact-checking claims, verifying logic, sanity-checking before commit | | Challenger | `agents/gemini-challenger.md` | Devil's advocate critique, stress-testing designs or decisions | +| Reviewer | `agents/gemini-reviewer.md` | Generalist diff/PR review (security, threading, version drift, docs, dead code); manual, advisory via the gemini-consult rule | ## The seven capability skills