plugin(gemini-delegate): v0.1.0 — deterministic pipeline for Gemini CLI

.claude-plugin/marketplace.json

@@ -198,6 +198,29 @@
         "evidence-driven",
         "experiment-design"
       ]
+    },
+    {
+      "name": "gemini-delegate",
+      "description": "Offload text, code, research, large-file analysis, and UI generation to the Gemini CLI behind a deterministic validation pipeline. Exploits Gemini's Google Search grounding, 1M token context, and multi-model routing (Flash/Pro).",
+      "version": "0.1.0",
+      "author": {
+        "name": "Nuno Salvacao",
+        "email": "nuno.salvacao@gmail.com"
+      },
+      "source": "./plugins/gemini-delegate",
+      "category": "productivity",
+      "tags": [
+        "gemini",
+        "delegation",
+        "deterministic-validation",
+        "pipeline",
+        "google-search",
+        "code-generation",
+        "ui-generation",
+        "large-context",
+        "token-economy",
+        "multi-llm"
+      ]
     }
   ]
 }

plugins/gemini-delegate/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "gemini-delegate",
+  "version": "0.1.0",
+  "description": "Offload text, code, research, large-file analysis, and UI generation to the Gemini CLI behind a deterministic validation pipeline. Exploits Gemini's Google Search grounding, 1M token context, and multi-model routing (Flash/Pro). Claude only intervenes on persistent failures.",
+  "author": {
+    "name": "Nuno Salvacao",
+    "email": "nuno.salvacao@gmail.com"
+  },
+  "homepage": "https://github.com/nsalvacao/nsalvacao-claude-code-plugins",
+  "repository": "https://github.com/nsalvacao/nsalvacao-claude-code-plugins",
+  "license": "MIT",
+  "keywords": ["gemini", "delegation", "deterministic-validation", "pipeline", "google-search", "code-generation", "ui-generation", "large-context", "token-economy", "multi-llm"]
+}

plugins/gemini-delegate/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuno Salvacao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/gemini-delegate/README.md

@@ -0,0 +1,106 @@
+# gemini-delegate
+
+Offload text, code, research, large-file analysis, and UI generation to the Gemini CLI behind a deterministic validation pipeline. Claude only intervenes on persistent failures.
+
+**Version:** 0.1.0
+
+## Overview
+
+`gemini-delegate` bridges Claude Code and the `gemini` CLI (Gemini Code), routing delegatable tasks through a deterministic validation layer. Gemini handles the generation; bash validators (linters, parsers, hash checks, structural checks) gate delivery. Claude reads output only on escalation — not on the happy path.
+
+> **Note:** The `gemini` CLI uses Google OAuth — content is sent to Google/Gemini infrastructure.
+
+## Unique Capabilities vs. Other Delegation Targets
+
+| Capability | gemini-delegate | Why it matters |
+|---|---|---|
+| **Google Search grounding** | `delegate-research.sh` | Real-time web search, citations, current info |
+| **1M token context** | `delegate-analyze.sh` | Entire codebases in a single pass |
+| **UI generation** | `delegate-ui.sh` | HTML5, React/TS, CSS with structural validators |
+| **Multi-model routing** | Flash / Pro | Fast for text, Pro for code/research/UI |
+| **Truly read-only mode** | `--approval-mode plan` | No tool execution risk for text tasks |
+
+## Prerequisites
+
+- `gemini` CLI installed and authenticated (v0.36.0+)
+- Verify: `gemini --version`
+- Authenticate: run `gemini` interactively → Google OAuth
+- Python 3 (required for JSON syntax validation and Python codegen validators)
+- `jq` (required for JSON response parsing)
+
+## Installation
+
+### Via marketplace (recommended)
+
+```
+/plugin marketplace add nsalvacao/nsalvacao-claude-code-plugins
+/plugin install gemini-delegate@nsalvacao-claude-code-plugins
+```
+
+### Local development
+
+```bash
+claude --plugin-dir /path/to/nsalvacao-claude-code-plugins/plugins/gemini-delegate
+```
+
+## Components
+
+### Skill: `gemini-delegate` (cognitive)
+
+Auto-activates when Claude recognises a delegatable task. Routes through validated bash scripts.
+
+### Command: `ask-gemini`
+
+Direct delegation:
+
+```
+/gemini-delegate:ask-gemini Summarise this PR description in 3 bullets
+/gemini-delegate:ask-gemini Research the latest breaking changes in React 19
+/gemini-delegate:ask-gemini Analyse what this 5000-line file does
+/gemini-delegate:ask-gemini Generate a responsive landing page for my CLI tool
+```
+
+### Agent: `gemini-advisor`
+
+Proactive triage of task lists — identifies Google Search tasks, large-context opportunities.
+
+## Delegation Categories
+
+| Category | Script | Model | Validators |
+|---|---|---|---|
+| Summarisation | `delegate-summary.sh` | Flash | Word count, bullet structure |
+| JSON / YAML / Markdown | `delegate-format.sh` | Flash | Syntax, idempotency, linters |
+| Code generation | `delegate-codegen.sh` | Pro | py\_compile / mypy / tsc / shellcheck |
+| Research (Google Search) | `delegate-research.sh` | Pro | Word count (substantive) |
+| Large file analysis | `delegate-analyze.sh` | Pro | Non-empty, word count |
+| UI (HTML/React/CSS) | `delegate-ui.sh` | Pro | DOCTYPE, closing tags, rule blocks |
+
+## Validation Pipeline
+
+```
+gemini output (JSON)
+    ↓
+jq response extraction (.response field)
+    ↓
+Deterministic validators (0 Claude tokens)
+    ├─ PASS → deliver in <gemini_output> with attribution
+    └─ FAIL → retry with error feedback (max 2×)
+           → persistent fail → <gemini_escalation> to Claude
+```
+
+Claude reads only the error message on escalation — not the raw Gemini output.
+
+## Security
+
+- Pre-flight rejects sensitive paths: `.env`, `*.pem`, `*.key`, credentials, `.git/`
+- Auth error (exit 41) stops immediately — no retry loop
+- All Gemini output wrapped in `<gemini_output>` — untrusted data, not instructions
+- `--approval-mode plan` (not yolo) for all text tasks — no tool execution
+
+## Known Limitations
+
+- **Cloud dependency:** requires internet and valid Google OAuth
+- **Pro model capacity:** `gemini-2.5-pro` may return 429 under high load — retry or use Claude
+- **Research mode:** uses `--approval-mode yolo` (Google Search requires tool invocation)
+- **Stateless invocations:** each delegation call starts fresh (no conversation context)
+- **Privacy:** content is sent to Google — do not delegate secrets or NDA code

plugins/gemini-delegate/agents/gemini-advisor.md

@@ -0,0 +1,74 @@
+---
+name: gemini-advisor
+description: Use this agent when the user asks "what could I delegate to Gemini?", "which tasks can Gemini handle?", "help me save tokens", "analyse this conversation for delegation opportunities", or when the user explicitly asks to identify tasks suitable for the Gemini CLI. Also use proactively after a long task list is presented and token economy is a concern.
+model: inherit
+color: blue
+---
+
+# Gemini Advisor
+
+Proactive delegation triage agent for the Gemini CLI. Analyses task lists or conversations and identifies which tasks can be delegated to Gemini behind the deterministic validation pipeline.
+
+## Unique Gemini capabilities (vs. other delegation targets)
+
+- **Google Search grounding** — real-time web search, current information, citations
+- **1M token context** — entire codebases, large logs, lengthy documents in a single pass
+- **UI generation** — HTML5, React/TypeScript, CSS with structural validators
+- **Code generation with Pro model** — Gemini 2.5 Pro for complex code tasks
+- **`--approval-mode plan`** — truly read-only (no tool execution) for text tasks
+
+## Delegation Decision Framework
+
+### Delegate to Gemini
+
+- **Summarisation**: meeting notes, PR descriptions, changelogs, long documents
+- **Text formatting**: JSON cleanup, YAML normalisation, Markdown consistency
+- **Research / web search**: current events, library comparisons, version info, best practices
+- **Large file analysis**: reviewing entire repos, log analysis, document Q&A
+- **Code generation**: boilerplate, utility functions, typed interfaces, bash scripts
+- **UI generation**: landing pages, components, CSS layouts, React components
+- **Translation**: documents, UI strings (preserve structure)
+
+### Keep with Claude
+
+- **Architectural decisions**: system design, database schema, API contracts
+- **Security-critical code**: auth flows, crypto, input validation
+- **Deep debugging**: stack traces, race conditions, complex logic errors
+- **Multi-step reasoning**: chains of dependent decisions
+- **Mechanical refactoring**: Prefer deterministic tools first (`black`, `prettier`, `libcst`, `jscodeshift`). Delegate to Gemini only if no suitable tool exists.
+
+### Research tasks — Gemini-first
+
+For any task requiring current information (library versions, recent changes, comparisons with up-to-date data): **always prefer Gemini with Google Search** over Claude's static knowledge.
+
+## Agent Instructions
+
+1. Read all tasks or conversation context provided by the user.
+2. For each task, classify: Delegate (with script) / Keep with Claude / Use deterministic tool.
+3. Estimate net token savings (validation is 0 Claude tokens on happy path).
+4. Produce structured triage output.
+
+## Output Format
+
+```
+## Gemini Delegation Triage
+
+### Delegate to Gemini
+- [Task]: [script] — [why]
+- ...
+
+### Keep with Claude
+- [Task]: [why it needs Claude]
+- ...
+
+### Use deterministic tools first
+- [Task]: [tool] (e.g., `black`, `prettier`, `jq`)
+- ...
+
+### Token Economy Summary
+- Estimated token saving (net of validation): High (>50%) / Medium (20–50%) / Low (<20%)
+  Note: validation is deterministic (0 Claude tokens on happy path).
+
+### Suggested execution order
+1. ...
+```

plugins/gemini-delegate/commands/ask-gemini.md

@@ -0,0 +1,122 @@
+---
+name: ask-gemini
+description: Delegate a task directly to the Gemini CLI (Google OAuth, cloud-backed). Selects the appropriate delegate script, runs deterministic validators, and returns the validated result.
+argument-hint: "<task or prompt to delegate to Gemini>"
+allowed-tools:
+  - Bash
+---
+
+# Ask Gemini — Direct Delegation
+
+Execute a user-specified task via the `gemini` CLI (Gemini Code, Google OAuth). No Anthropic API calls during delegation.
+
+> **Privacy:** Gemini CLI sends content to Google/Gemini infrastructure. Do not delegate secrets, credentials, private keys, personal data, or NDA-protected code.
+
+## Execution Steps
+
+1. **Get the task** — Use the argument provided. If none: ask *"What task would you like to delegate to Gemini?"*
+
+2. **Pre-flight check:**
+
+```bash
+ls ~/.gemini/settings.json
+```
+
+If absent, stop and tell user to run `gemini` interactively (Google OAuth).
+
+3. **Classify the task:**
+
+   - Summarisation → `delegate-summary.sh`
+   - JSON / YAML / Markdown formatting → `delegate-format.sh <type>`
+   - Code generation or boilerplate → `delegate-codegen.sh <lang> "<spec>"`
+   - Research / web search → `delegate-research.sh "<question>"`
+   - Large file analysis → `delegate-analyze.sh "<question>" <files...>`
+   - UI / HTML / CSS / React → `delegate-ui.sh <type> "<spec>"`
+
+4. **Execute** the appropriate command.
+
+5. **Handle output** — see "Output handling" section.
+
+## Commands
+
+### Summarisation
+
+```bash
+echo "CONTENT" | bash plugins/gemini-delegate/scripts/delegate-summary.sh
+bash plugins/gemini-delegate/scripts/delegate-summary.sh path/to/file.md
+```
+
+### JSON formatting
+
+```bash
+echo 'RAW_JSON' | bash plugins/gemini-delegate/scripts/delegate-format.sh json
+```
+
+### YAML formatting
+
+```bash
+bash plugins/gemini-delegate/scripts/delegate-format.sh yaml path/to/file.yaml
+```
+
+### Markdown formatting
+
+```bash
+bash plugins/gemini-delegate/scripts/delegate-format.sh markdown path/to/file.md
+```
+
+### Code generation
+
+```bash
+bash plugins/gemini-delegate/scripts/delegate-codegen.sh python "SPEC"
+bash plugins/gemini-delegate/scripts/delegate-codegen.sh typescript "SPEC"
+bash plugins/gemini-delegate/scripts/delegate-codegen.sh bash "SPEC"
+```
+
+### Research (Google Search grounded)
+
+```bash
+bash plugins/gemini-delegate/scripts/delegate-research.sh "RESEARCH QUESTION"
+```
+
+### Large file / codebase analysis
+
+```bash
+bash plugins/gemini-delegate/scripts/delegate-analyze.sh "QUESTION" path/to/file
+bash plugins/gemini-delegate/scripts/delegate-analyze.sh "QUESTION" path/to/directory/
+```
+
+### UI / HTML / CSS / React generation
+
+```bash
+bash plugins/gemini-delegate/scripts/delegate-ui.sh html "SPEC"
+bash plugins/gemini-delegate/scripts/delegate-ui.sh react "SPEC"
+bash plugins/gemini-delegate/scripts/delegate-ui.sh css "SPEC"
+```
+
+## Output handling
+
+**Success (`<gemini_output>`, exit 0):** Present content to user with:
+
+```
+[content from <gemini_output> block]
+
+---
+*Drafted by Gemini CLI (Google OAuth), validated by deterministic pipeline.*
+```
+
+**Escalation (`<gemini_escalation>`, exit 70):** Read only `error` and `validators` from the JSON — do NOT re-read raw Gemini output. Decide: fix directly, or tell user: *"Gemini output failed validation ([error]). Handle with Claude directly — shall I?"*
+
+**Auth failure (exit 41 or exit 80):** Tell user: *"Gemini not authenticated. Run `gemini` interactively to complete Google OAuth login."*
+
+**Pro model at capacity (exit 1, 429):** Tell user: *"gemini-2.5-pro is temporarily at capacity. Retry in a few minutes, or use Claude directly."*
+
+## Error troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| `gemini: command not found` | CLI not installed | Install Gemini CLI; verify with `gemini --version` |
+| Exit 80 or 41 — not authenticated | OAuth never run / token expired | Run `gemini` interactively (Google OAuth) |
+| Exit 70 — escalation after retry | Gemini persistently invalid output | Handle with Claude directly |
+| Empty response | Model returned blank | Script retries automatically; escalates on failure |
+| 429 / capacity exhausted | Pro model overloaded | Retry in a few minutes |
+| Network error | No internet | Gemini CLI requires cloud access |