Gemini CLI Playbook

Provision Gemini for the toolkit

1. Install Gemini CLI using the official quickstart (or the bundled terminal guide) and authenticate with your API key.
2. Clone (or symlink) AI-toolkit/ into the project root so relative paths work in every command.
3. Export helper env vars in your shell profile:

   export GEMINI_TOOLKIT=$PWD/AI-toolkit
   export GEMINI_OUTPUT_DIR=$PWD/.gemini
   mkdir -p "$GEMINI_OUTPUT_DIR"

4. Copy the Gemini briefing template from the toolkit docs bundle into the repo root and skim it before every large engagement to refresh context.
5. Smoke test with gemini chat "ready for the toolkit" and verify the CLI reads files from $GEMINI_TOOLKIT.

Keep a dedicated virtualenv or uv project for Gemini tooling so dependencies (markdown parsing, jq, yq) are isolated from application code.

Start a new project with Gemini

1. Run gemini prompt --file $GEMINI_TOOLKIT/prompts/create_brief.md < brief.txt to generate a north-star summary and share it with Claude.
2. Call gemini agent --file $GEMINI_TOOLKIT/agents/orchestration/tech-lead-orchestrator.md with your story description to obtain a cross-tool execution plan.
3. Populate a research log (for example notes/research.md) by piping web results through general-research-agent.md.
4. Before shipping code, run gemini prompt --file $GEMINI_TOOLKIT/prompts/code_review.md --input git.diff so Gemini highlights risky chunks you should verify in Claude.
5. Finish the cycle with gemini prompt --file $GEMINI_TOOLKIT/prompts/write_docs.md and paste the bundle into /project:session-end.

Recover context on a legacy project

• Session sync: Pull the latest Claude session via tail -n 120 .claude/sessions/*.md > /tmp/session.txt and feed it to gemini chat --input /tmp/session.txt so Gemini offers a status recap.
• Architecture mapping: Use project-analyst.md to list stacks, build commands, and risk areas: gemini agent --file $GEMINI_TOOLKIT/agents/orchestration/project-analyst.md --input repo-scan.txt.
• Hotfix plan: When inheriting urgent bugs, run gemini prompt --file $GEMINI_TOOLKIT/prompts/plan_feature.md --mode bug and have Gemini call out blast radius, rollback, and targeted tests.
• Knowledge capture: Export the conversation to .claude/sessions/<date>-gemini-notes.md and reference it in /project:session-update.

High-leverage Gemini agents

Capture agent output to $GEMINI_OUTPUT_DIR/<timestamp>-agent.md so you can attach the evidence to tickets or pull requests.

Run multi-agent chains with Gemini

1. Generate the orchestration: gemini agent --file $GEMINI_TOOLKIT/agents/orchestration/tech-lead-orchestrator.md --input epic.md to produce a phase map that lists downstream agents and expected artefacts.
2. Plan the team topology: Feed the orchestrator output into team-configurator.md so you know which agent hands over to whom and what evidence is required.
3. Execute sequentially: For each phase, pipe the previous agent’s summary into the next command, e.g. gemini agent --file $GEMINI_TOOLKIT/agents/frameworks/django/django-api-developer.md --input plan-phase1.md.
4. Agent-controlled automation: When Gemini recommends calling another agent, capture its instructions with session-closer.md or a custom handoff template, then feed that file to the next command.
5. Audit the chain: After the specialists, run reliability-commander.md and testing-expert.md to validate readiness, then append their output to the Claude session log for shared visibility.

Store each agent’s output in $GEMINI_OUTPUT_DIR/chain/<step>.md. You can replay or resume the sequence by reusing those artefacts as inputs.

Sample scenario: incident response research

1. Prompt & brief: Start with gemini prompt --file $GEMINI_TOOLKIT/prompts/create_brief.md --input incident.md to capture severity, affected services, and stakeholders. Share the brief within Claude.
2. Agent orchestration: Use tech-lead-orchestrator.md to lay out the chain (project-analyst → reliability-commander → testing-expert) and run team-configurator.md to document roles.
3. Deep dives: Pipe log extracts into project-analyst.md, run reliability-commander.md for mitigation checklists, then let testing-expert.md design regression tests. Save outputs to $GEMINI_OUTPUT_DIR.
4. Session syncing: Tail the Claude log, feed it into gemini chat --input ... for a summary, and append new findings back via /project:session-update.
5. Docs & wrap-up: Generate a post-incident report with gemini prompt --file $GEMINI_TOOLKIT/prompts/write_docs.md --input summary.md, then mirror the report to the session log and ticketing system.

Keep every agent output referenced by filename inside the session log so responders can audit how Gemini assisted during the incident.

Generative modes & creation catalogue

Text & code generation

• Default model: gemini prompt --model gemini-pro --file $GEMINI_TOOLKIT/prompts/plan_feature.md --input story.txt for architectural plans, PRDs, or code skeletons.
• Code-specific: gemini prompt --model gemini-pro --code --input sourcefile.py to request refactors, docstrings, or test suites.
• Research digests: Stream URLs into gemini prompt --model gemini-pro --stdin to summarise articles, RFCs, or incident timelines into bullet points.

Image generation & editing

• Static renders: gemini prompt --model imagen-3 --text "hero illustration of secure payment" --output assets/payment.png.
• Image-to-image: gemini prompt --model imagen-3 --image mocks/dashboard.png --text "add dark theme" --output assets/dashboard-dark.png.
• Prompt drafting: Have Claude craft detailed visual prompts, then feed them to Gemini for consistent brand-aligned assets.

Video & audio snippets

• Storyboard shots: Use gemini prompt --model imagen-3 --text "sequence of 6 storyboard panels for onboarding" --frames 6 to generate concept art.
• Voiceover scripts: Pair gemini prompt --model gemini-pro with TTS tooling (e.g. edge-tts) to produce narrated walkthroughs.
• Video outlines: Request shot lists and timing cues using gemini prompt --model gemini-pro --file scripts/video-outline.md, then hand the plan to production teams.

Data & spreadsheet helpers

• CSV analysis: gemini prompt --model gemini-pro --input data/metrics.csv --analyze to summarise trends, anomalies, and suggested actions.
• SQL generation: Combine gemini prompt --model gemini-pro --text "Generate SQL for..." with --schema schema.sql to produce queries that match your database.
• JSON transforms: Pipe JSON into gemini prompt --json to create API payload examples or contract tests.

Set GEMINI_MODEL in your environment to swap defaults quickly (e.g. export GEMINI_MODEL=gemini-pro-vision for multimodal prompts).

Prompt workflows in the terminal

Keep sessions in sync

Store every Gemini summary in a searchable session insights archive so new contributors can replay historical research.

How Gemini accelerates different disciplines

• Backend engineering: Feed schema snapshots or open API specs to Gemini, then run django-orm-expert.md or api-architect.md for migration strategies and compatibility checks.
• Frontend development: Provide design tokens or component APIs and ask react-nextjs-expert.md for SSR/ISR decisions. Gemini can also script Playwright test outlines.
• Ops & reliability: Pipe log excerpts into reliability-commander.md to produce runbooks, then schedule follow-up actions in Claude.
• Design & documentation: Use content-writer.md for release notes, prd-writer.md for product docs, and vibe-coding-coach.md for creative direction.

Integrations and supporting tools

• Terminal companions: fzf for fast file selection, entr for rerunning commands when files change, jq/yq for massaging JSON/YAML before sending to Gemini.
• Data sources: Use curl + httpie to gather API responses and feed them into agents as evidence.
• Testing harness: Automate pytest, npm test, or go test runs, capture the logs, and let Gemini suggest additional coverage.
• Knowledge management: Sync Gemini research outputs to Notion, Confluence, or Obsidian using simple CLI exporters (notionx, obsidian-export).

Best practices for maximizing Gemini

• Always describe the environment (language, framework, target platform) at the top of each chat so Gemini tailors guidance.
• Chunk large diffs using git diff --stat plus targeted git diff -- src/file attachments to keep prompts under token limits.
• Run critical prompts twice: once for the raw answer, once with --system "act as a critic" to stress-test the plan.
• Mirror every Gemini recommendation back into Claude via the session commands so other tools stay aligned.