collaborating-with-gemini

name	collaborating-with-gemini
description	Use the Gemini CLI as a breadth-exploration co-pilot for paper-from-zero. Primary role: candidate direction expansion, adjacent work scanning, keyword cluster generation, and alternative framing proposals. Also supports generic code collaboration as fallback.
metadata	{"short-description":"Breadth co-pilot (Gemini) for paper-from-zero"}

Collaborating with Gemini (Codex)

Use Gemini CLI as a breadth-exploration collaborator for paper-from-zero, or as a generic code collaborator in fallback mode.

This skill provides a lightweight bridge script that returns structured JSON and supports multi-turn sessions via SESSION_ID.

Shared rules: This skill inherits all shared rules from ../../_shared/collaboration-base.md (core rules, candidates-only constraint, fallback code-collaboration mode, safety guardrails, and collaboration state capsule format). Only Gemini-specific additions are listed below.

When to Use

• paper-from-zero needs to expand the candidate literature pool.
• topic-brief initial draft exists but adjacent research areas are uncovered.
• contribution-map needs 3-5 alternative framing candidates.
• evidence-matrix has coverage gaps that need broader search directions.
• Fallback: generic code collaboration tasks (analysis, patch, review).

When NOT to Use

• Claim-level logical analysis or reviewer objection stress tests (use Claude).
• Final routing judgment between review/empirical (use Claude).
• Generating ref.bib entries or verified citations.
• Tasks requiring depth reasoning rather than breadth scanning.

Gemini-Specific Rules

• Optional: pass --sandbox to run Gemini in sandbox mode.
• Auth/home notes:
  • The bridge defaults GEMINI_CLI_HOME to a writable repo-local directory (<repo>/.gemini_cli_home/) to avoid Gemini CLI hanging in some runners.
  • If your local gemini is already logged in, reuse that login with --use-user-home.
  • If you have GEMINI_API_KEY set but want to use OAuth creds, add --prefer-oauth to unset API-key env vars for this run.

Quick Start (shell-safe)

If your prompt contains Markdown backticks, use a heredoc; see references/shell-quoting.md.

PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py --cd "." --PROMPT "$PROMPT"

Output: JSON with success, SESSION_ID, agent_messages, and optional error / all_messages.

Multi-turn Sessions

# Start a session
PROMPT="$(cat <<'EOF'
Analyze the bug in foo(). Keep it short.
EOF
)"
python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py --cd "." --PROMPT "$PROMPT"

# Continue the same session
PROMPT="$(cat <<'EOF'
Now propose a minimal fix as Unified Diff Patch ONLY.
EOF
)"
python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py --cd "." --SESSION_ID "<SESSION_ID>" --PROMPT "$PROMPT"

Prompting Patterns (Paper Mode)

Use assets/prompt-template.md as a starter when crafting --PROMPT. Paper-mode templates (top of the file):

• literature-map — expand candidate papers and adjacent research areas
• innovation-candidates — generate 3-5 candidate contribution framings
• evidence-matrix-gap-check — audit evidence coverage gaps

Each template specifies its input sources, output artifact mappings, and constraints.

Advanced Flags

• --sandbox: Run Gemini in sandbox mode.
• --model <name>: Override the default Gemini model.
• --return-all-messages: Include all raw messages (tool calls, traces) in output JSON.
• --use-user-home: Reuse your normal home (and existing ~/.gemini login) for this run.
• --prefer-oauth: Unset GEMINI_API_KEY/GOOGLE_API_KEY so OAuth creds can be used (if present in the selected home).
• --seed-user-auth: Copy OAuth/settings files from your ~/.gemini into <repo>/.gemini_cli_home/.gemini/ (avoids --use-user-home hangs).
• --fake-responses <path.jsonl>: Offline deterministic run using Gemini CLI fake responses (for smoke tests).

Verification

• Cross-check both collaborators: use the check-collaborators skill
• Smoke-test the bridge: python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py --help

References

• ../../_shared/collaboration-base.md (shared rules)
• assets/prompt-template.md (prompt patterns)
• references/shell-quoting.md (shell quoting/backticks)