/gemini-skill

name: gemini
description: >
  Delegate a coding task to Gemini CLI and supervise the result via git diff.
  Trigger: /gemini <instruction>. Claude orchestrates, Gemini codes.
  Also handles /gemini-report [--since N] [--project NAME] [--fails] — token/cost/failure report.
license: MIT
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Grep

/geminion | /geminioff | /geministatus

Toggle auto-delegate mode — Gemini automatically handles all coding tasks without requiring `/gemini` each time.

| Command | Action | |---------|--------| | `/geminion` | `touch ~/.local/share/gemini-auto.flag` → confirm "Auto-gemini ON" | | `/geminioff` | `rm -f ~/.local/share/gemini-auto.flag` → confirm "Auto-gemini OFF" | | `/geministatus` | check `~/.local/share/gemini-auto.flag` → report ON or OFF |

Run the bash command, print one confirmation line, and stop.

---

/gemini-report

If the user invokes `/gemini-report`, run `~/tools/delegate-report` with any flags extracted from the arguments, display output verbatim, and stop.

| User says | Flag | |-----------|------| | "last 7 days", "7d" | `--since 7` | | "last 30 days", "30d" | `--since 30` | | "project foo" | `--project foo` | | "only failures", "fails", "bugs" | `--fails` | | (nothing) | (no flags — full report) |

---

Gemini Orchestrator

When the user invokes `/gemini <instruction>`, Claude delegates the implementation to Gemini CLI via its headless mode (`-p/--prompt`), monitors in real time, and reports.

---

Known Limits

Hard constraints of the Gemini CLI — not config options.

1. No `--max-turns` flag

Vibe lets you cap turn count (`--max-turns 8`). Gemini CLI has no equivalent. **Timeout is the only runaway-control lever.** A stuck run burns the full timeout before dying. Set timeouts conservatively and decompose tasks.

2. High context overhead (~900–10k tokens before your task starts)

Gemini CLI loads a large default system prompt on every run:

• Simple prompt → ~883 tokens before the model responds
• File-read task → ~10k tokens of context before first tool call

This means:

• Each run costs more than token-naive estimates suggest
• Short timeouts can expire during context-loading on a slow connection
• The overhead is mostly cached on repeated calls to the same model in a session

3. 503 backoff eats your timeout silently

On the free-tier Gemini API, the model is frequently "under high demand." The CLI auto-retries with exponential backoff — observed taking **60–90s** before work even begins. This is invisible until you see the first tool call.

Always add 90s buffer to your "real work" estimate:

Timeout budget = expected_work_secs + 90s backoff buffer + 30s context load

4. No `--agent` flag

Gemini CLI is single-mode only. There is no way to switch to a review-only or plan-only agent. Use `plan` mode (`--approval-mode plan`) as a partial substitute.

5. No `--workdir` flag

The delegate script handles this by `cd`-ing into the workdir before running.

6. No pseudo-TTY needed (positive difference vs Vibe)

Gemini CLI works fine in a plain pipe — no `script -q -c` wrapper needed.

7. Orchestration chain has 5 independent failure points

The delegation pipeline is: Gemini CLI -> plain pipe -> Python stream parser -> result event tokens -> git diff -> JSON log. Each link can fail independently:

| Link | Failure mode | Symptom | |------|-------------|---------| | Gemini CLI | Auth expired, quota hit, 503 | Immediate exit or silent 90s hang | | Stream parser | Gemini changes its JSON event schema | Tool calls not detected, token count 0 | | result event | Missing on timeout or crash | Tokens logged as 0, cost not computed | | git diff | Not a git repo, or Gemini committed mid-run | Wrong file count | | JSON log | ~/.local/share/ not writable | Silent log skip |

When a run produces unexpected results, check these links top to bottom.

Step 1 — Detect workdir

1. `git rev-parse --show-toplevel` in the current directory. 2. If ambiguous or no git repo → ask with `AskUserQuestion`.

---

Step 2 — Choose mode

| Mode | Flag | Writes files? | Use for | |--------|-------------------------|---------------|-------------------------------------| | `impl` | `--yolo` | Yes | Implementing changes (default) | | `plan` | `--approval-mode plan` | No | Safe exploration, reading, planning |

Use `plan` mode when you want Gemini to read the codebase and report back without touching any files. Proposed writes appear as `[plan-write]` and are blocked.

---

Step 3 — Decompose the task

**Critical rule**: Gemini works best on **atomic, focused tasks**. Given the context overhead and 503 risk, keep tasks smaller than you might expect.

**Decide whether to delegate at all:**

`gemini-delegate` has real overhead (503 backoff, context load, stream parser, git diff, JSON log). For trivial changes the setup cost exceeds the savings.

| Signal | Action | |--------|--------| | 1 file, ≤ ~10 lines to change, location already known | **Do it directly** — don't delegate | | 1 file, logic non-trivial OR location unclear | Delegate | | 2–3 files, single objective | Delegate | | >3 files OR multi-step logic OR migrations | Delegate, broken into sub-tasks |

The sweet spot is **medium to heavy tasks**.

| Size | Definition | Approach | |------|-----------|----------| | **Trivial** | 1 file, change is obvious and located | **Skip delegation — edit directly** | | **Simple** | 1 file, non-trivial logic or unknown location | 1 gemini call, impl mode | | **Medium** | 2–3 related files, 1 goal | 1 gemini call with structured prompt | | **Complex** | >3 files OR business logic OR DB migrations | **Decompose** |

**Decomposition for complex tasks:**

Sub-task 1: Explore relevant files — plan mode, 120s
Sub-task 2: Implement change A in file X — impl mode, 180s
Sub-task 3: Implement change B in file Y — impl mode, 180s
Sub-ta