# Hybrid Mode

> >

- **Type:** Skill
- **Install:** `agentstack add skill-manceps-skills-hybrid-mode`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [manceps](https://agentstack.voostack.com/s/manceps)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [manceps](https://github.com/manceps)
- **Source:** https://github.com/manceps/skills/tree/main/hybrid_mode

## Install

```sh
agentstack add skill-manceps-skills-hybrid-mode
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hybrid Mode: Claude  Gemini Collaboration

## Overview

Hybrid Mode lets Claude (the lead) consult Gemini CLI as an independent expert
peer. Claude frames a question, hands Gemini the relevant context, and Gemini
returns a focused critique or validation. Claude then weighs that counsel,
states whether it agrees, and proceeds. Gemini is an advisor, not the decider:
Claude remains the lead architect and owns the final call.

This formalizes the manual "ask Gemini for an architectural review / decision"
workflow into a single, reliable, repeatable tool.

### When to use

Reach for Hybrid Mode when an independent second opinion materially de-risks a
decision:

- **Architectural review**, before committing to a design, get a critique of the
  approach, its tradeoffs, and alternatives.
- **Plan validation**, hand Gemini a proposed implementation plan and ask it to
  find gaps, hidden coupling, or sequencing problems.
- **Code review**, ask Gemini to review a diff or file for correctness,
  security, and maintainability issues Claude may have anchored past.
- **Decision arbitration**, when torn between two approaches, present both and
  ask Gemini for a verdict with reasoning.
- **High-stakes / irreversible actions**, cross-check before a migration,
  cutover, schema change, or production deploy.
- **The user explicitly asks** for Gemini's input, a "hybrid" review, or a
  "second opinion."

### When NOT to use

- Trivial, low-risk, or easily reversible changes, the round-trip cost is not
  worth it.
- Questions Claude can answer with full confidence from the code in front of it.
- As a way to offload work Claude should do, Gemini advises; Claude still does
  the engineering and owns correctness.
- Anything requiring Gemini to make edits, this skill runs Gemini read-only by
  design. Claude makes all changes.

## How it works

```
  Claude                      consult_gemini.sh                Gemini CLI
  ------                      -----------------                ----------
  1. frame question  ──────>  build prompt on stdin  ──────>  read-only (plan)
  2. pick context dirs        gemini -o json --skip-trust      reasons over
                              --approval-mode plan             provided context
  3. invoke wrapper           --include-directories           │
                                      │                            ▼
  6. read .response   stderr/log
```

Claude does the thinking on both ends: it writes the prompt, and it interprets
the answer. The script is plumbing that makes the Gemini round-trip clean and
reliable (stdin for large prompts, read-only safety, JSON parsing, timeouts,
diagnostics).

## The workflow Claude follows

### Step 1, Decide it is worth a consult

Confirm the decision is non-trivial and an independent view adds value (see
"When to use"). If not, just proceed without Gemini.

### Step 2, Construct a well-formed prompt

This is the most important step. The quality of Gemini's counsel is bounded by
the quality of the prompt. A good Hybrid Mode prompt has five parts:

1. **Role + framing** — tell Gemini it is an independent senior reviewer in a
   hybrid collaboration and that Claude wants its honest, independent judgment
   (not validation-seeking agreement).
2. **Context** — the relevant facts: what the system is, what is being built or
   changed, and any constraints. Reference files by absolute path; the wrapper
   makes them readable via `--context`.
3. **What Claude proposes** — Claude's current plan or position, stated plainly
   so Gemini can agree or push back on something concrete.
4. **The specific question** — one sharp question, not a vague "thoughts?".
5. **Output contract** — how to answer. Always ask Gemini to **lead with a
   verdict** (e.g. `VERDICT: AGREE / DISAGREE / NEEDS-CHANGES`) and to be
   concise. Cap the length when you only need a focused take.

Use `assets/prompt_template.md` as the scaffold. Write the prompt to a temp
file (e.g. `/tmp/hybrid_.txt`) so it is easy to pass and to log.

Avoid leading the witness: do not phrase the prompt so the only natural answer
is "yes, Claude is right." The whole value is independent judgment.

### Step 3, Launch Gemini via the wrapper

Run the script, passing the prompt and the directories Gemini needs to read.

```bash
scripts/consult_gemini.sh \
  --prompt-file /tmp/hybrid_.txt \
  --context /path/to/your/project/src \
  --timeout 600
```

Or pipe the prompt on stdin:

```bash
echo "$PROMPT" | scripts/consult_gemini.sh --context /path/to/your/project
```

For a long consult that should not block, run it in the background and collect
the result when it finishes:

```bash
scripts/consult_gemini.sh --prompt-file /tmp/hybrid_arch.txt \
  --context /path/to/your/project/src > /tmp/hybrid_arch.out 2> /tmp/hybrid_arch.err
```

(If your agent runtime supports background execution, run the wrapper there
rather than polling in a sleep loop. The response lands on stdout, diagnostics
on stderr.)

### Step 4, Read and weigh Gemini's response

Gemini's answer arrives on stdout. Read it critically:

- Does the verdict and reasoning hold up against what Claude knows?
- Did Gemini surface something Claude missed? Adopt it.
- Did Gemini misunderstand the context? That signals the prompt needed more
  detail, refine and re-consult if the point is material.
- Disagreement is a feature. If Gemini disagrees, engage with the reasoning;
  do not reflexively defer, and do not reflexively dismiss.

### Step 5, State the synthesis and proceed

Tell the user, briefly: what Claude asked Gemini, what Gemini said (verdict +
key point), and Claude's resulting decision, including where Claude diverges
from Gemini and why. Then act. Claude owns the outcome.

## Script reference: consult_gemini.sh

Launches Gemini CLI headlessly, read-only by default, and returns only Gemini's
response on stdout.

| Flag | Default | Description |
|------|---------|-------------|
| `--prompt-file PATH` | (stdin) | Read the prompt from a file instead of stdin. |
| `--context DIR` | (none) | Add a directory to Gemini's readable workspace. Repeatable. Pass repo roots holding files under review. |
| `--model NAME` | CLI default | Override the Gemini model. |
| `--mode MODE` | `plan` | Approval mode. `plan` = read-only (recommended). Other values (`auto_edit`, `yolo`, `default`) allow side effects; avoid for reviews. |
| `--timeout SECONDS` | `600` | Hard wall-clock cap. |
| `--format FORMAT` | `text` | `text` = just the response; `json` = full envelope incl. stats. |
| `--log PATH` | temp file | Sidecar diagnostics log (prompt size, banners, raw JSON, latency, tokens). |

**Exit codes:** `0` success; `2` bad usage / empty prompt; `3` missing
`gemini`/`jq`; `4` timeout; `5` ran but no usable response (auth, quota, model
error). On non-zero exit, read the sidecar log path printed to stderr.

**Design choices baked in:**
- Prompt is delivered on **stdin** so large reviews (code, diffs) never hit
  argv limits.
- `--skip-trust` is set because headless Gemini refuses untrusted workspaces;
  read-only `plan` mode keeps this safe.
- Output is parsed from `-o json` via `jq '.response'`, the only clean way to
  separate Gemini's answer from its banners and stats footer.
- Diagnostics (model, latency, tokens, session) go to **stderr + log**, never
  stdout, so the captured response stays clean.

## Prompt templates

See `assets/prompt_template.md` for ready-to-fill scaffolds for the common
consult types (architectural review, plan validation, code review, decision
arbitration). See `references/prompting_guide.md` for the principles behind
writing prompts that elicit genuinely useful, independent counsel.

## Examples

### Architectural review

```bash
cat > /tmp/hybrid_cache.txt  /tmp/hybrid_migration.out 2> /tmp/hybrid_migration.err
# collect /tmp/hybrid_migration.out when done
```

## Troubleshooting

| Symptom | Likely cause | Resolution |
|---------|--------------|------------|
| Exit 3, "gemini not found" | Gemini CLI not on PATH | Ensure `gemini` is installed and on PATH (`which gemini`). |
| Exit 4, timeout | Prompt too large or Gemini slow | Raise `--timeout`; trim context; ask a narrower question. |
| Exit 5, empty response | Auth/quota/model error | Read the sidecar log; verify Gemini auth (`gemini -p "hi" --skip-trust`); check quota. |
| Gemini misunderstands context | Prompt lacked detail or wrong `--context` | Add the right repo root via `--context`; reference files by absolute path; restate constraints. |
| Gemini just agrees with everything | Prompt led the witness | Reframe neutrally; ask it to argue the strongest case against the proposal. |
| Response references files it could not read | File outside provided context | Add the containing dir with `--context`. |

## Scope & limitations

**In scope:**
- Read-only consultation: review, critique, validation, arbitration.
- Passing code/diffs/plans as context for Gemini to reason over.
- Single-turn consults framed by Claude.

**Out of scope:**
- Letting Gemini edit files or run side-effecting tools (read-only by design;
  Claude makes all changes).
- Multi-turn back-and-forth sessions with Gemini (each consult is one shot;
  Claude can issue follow-up consults but should re-state context).
- Treating Gemini's verdict as binding, Claude is the lead and owns the call.

**Caveats:**
- Gemini's counsel is only as good as the prompt and context it receives.
- Independent does not mean correct; weigh Gemini's view against the code and
  Claude's own judgment.
- Do not send secrets or credentials in prompts or context dirs.
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [manceps](https://github.com/manceps)
- **Source:** [manceps/skills](https://github.com/manceps/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-manceps-skills-hybrid-mode
- Seller: https://agentstack.voostack.com/s/manceps
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.