melodic-software/gemini-workspace-bridge

Gemini Workspace Bridge

Documentation Delegation

Documentation Source: For authoritative workspace patterns and current conventions, query gemini-cli-docs skill. This skill provides integration guidance; gemini-cli-docs provides official Gemini CLI documentation.

Overview

This skill defines the hybrid workspace architecture for Claude Code and Gemini CLI collaboration. It establishes conventions for file storage, artifact exchange, and cross-CLI communication.

When to Use This Skill

Keywords: workspace structure, artifact storage, cross-cli, shared files, gemini artifacts, claude artifacts, file locations, where to store

Use this skill when:

• Setting up a project for dual-CLI workflow
• Deciding where to store AI-generated artifacts
• Understanding the hybrid tracked/gitignored strategy
• Managing cross-CLI file exchange

Core Architecture

Hybrid Approach

The workspace uses a hybrid strategy:

• Tracked files: Memory files, valuable artifacts (plans, reports)
• Gitignored temp: Session state, caches, transient outputs

Directory Structure

project-root/
├── CLAUDE.md                    # Source of truth (tracked)
├── GEMINI.md                    # Points to CLAUDE.md + overrides (tracked)
│
├── .claude/
│   ├── settings.json            # Claude Code configuration
│   └── temp/                    # (gitignored) Session artifacts
│       └── gemini-results/      # Parsed Gemini outputs
│
├── .gemini/
│   ├── settings.json            # Gemini CLI configuration
│   └── temp/                    # (gitignored) Gemini session state
│
└── docs/                        # (tracked) Persistent AI artifacts
    └── ai-artifacts/            # Version-controlled reports
        ├── explorations/        # Codebase exploration reports
        └── plans/               # Implementation plans

Artifact Location Guide

Decision Tree

Is this artifact valuable long-term?
├── YES: Should others see it in git history?
│   ├── YES → docs/ai-artifacts/
│   └── NO  → .claude/temp/ or .gemini/temp/
└── NO: Is it session-specific?
    ├── YES → .claude/temp/ or .gemini/temp/
    └── NO  → Consider not storing it

Location Matrix

| Artifact Type | Location | Tracked? | Rationale | | --- | --- | --- | --- | | Memory/context | CLAUDE.md, GEMINI.md | Yes | Core project knowledge | | Implementation plans | docs/ai-artifacts/plans/ | Yes | Want to see evolution | | Exploration reports | docs/ai-artifacts/explorations/ | Yes | Reference material | | Session results | .claude/temp/gemini-results/ | No | Transient | | Second opinions | .claude/temp/gemini-results/ | No | Transient | | Checkpoints | ~/.gemini/history/<hash>/ | No | System-managed | | Sync state | .claude/temp/sync-state.json | No | Internal tracking |

Gitignore Recommendations

Add to project .gitignore:

# AI session artifacts (transient)
.claude/temp/
.gemini/temp/

# System-managed
.gemini/history/

# Keep these tracked:
# CLAUDE.md
# GEMINI.md
# docs/ai-artifacts/

File Naming Conventions

Timestamped Artifacts

Format: {type}-{scope}-{timestamp}.md

# Exploration reports
exploration-architecture-2025-11-30T12-00-00Z.md
exploration-dependencies-2025-11-30T14-30-00Z.md

# Implementation plans
plan-add-auth-2025-11-30T12-00-00Z.md
plan-refactor-db-2025-11-30T14-30-00Z.md

Session Results

Format: {operation}-{timestamp}.{json|md}

# Raw Gemini results
query-2025-11-30T12-00-00Z.json
analysis-2025-11-30T12-00-00Z.json

# Processed results
analysis-summary-2025-11-30T12-00-00Z.md

Workspace Initialization

Initialize for Dual-CLI

# Create directory structure
mkdir -p .claude/temp/gemini-results
mkdir -p .gemini/temp
mkdir -p docs/ai-artifacts/explorations
mkdir -p docs/ai-artifacts/plans

# Create GEMINI.md if not exists
if [ ! -f "GEMINI.md" ]; then
  cat > GEMINI.md << 'EOF'
# GEMINI.md

@CLAUDE.md

## Gemini-Specific Overrides

You are Gemini CLI. You have access to:
- Large context window (exceeds typical LLM limits)
- Interactive PTY shell (vim, git rebase -i)
- Checkpointing with instant rollback
- Policy engine for tool control

When working with this codebase, prioritize bulk analysis
and exploration tasks that benefit from your large context.
EOF
fi

# Update .gitignore
grep -q ".claude/temp/" .gitignore 2>/dev/null || echo ".claude/temp/" >> .gitignore
grep -q ".gemini/temp/" .gitignore 2>/dev/null || echo ".gemini/temp/" >> .gitignore

Artifact Exchange Patterns

Pattern 1: Claude → Gemini (Context Handoff)

# Claude prepares context
cat CLAUDE.md relevant-files/* > .claude/temp/context-bundle.txt

# Gemini consumes
cat .claude/temp/context-bundle.txt | gemini "Analyze this context"

Pattern 2: Gemini → Claude (Result Consumption)

# Gemini produces result
gemini "Explore architecture" --output-format json > .claude/temp/gemini-results/exploration.json

# Claude parses result
cat .claude/temp/gemini-results/exploration.json | jq -r '.response'

Pattern 3: Persistent Artifacts

# For valuable artifacts that should be tracked
result=$(gemini "Create implementation plan" --output-format json)
echo "$result" | jq -r '.response' > docs/ai-artifacts/plans/plan-feature-$(date -u +%Y-%m-%dT%H-%M-%SZ).md

Cleanup Strategies

Automatic Cleanup (Session-based)

# Clean artifacts older than 7 days
find .claude/temp/gemini-results -type f -mtime +7 -delete
find .gemini/temp -type f -mtime +7 -delete

Manual Cleanup

# Clear all session artifacts
rm -rf .claude/temp/*
rm -rf .gemini/temp/*

Selective Cleanup

# Keep recent, delete old
find .claude/temp/gemini-results -name "*.json" -mtime +3 -delete

Best Practices

1. Single Source of Truth

• CLAUDE.md is the authoritative memory file
• GEMINI.md imports from CLAUDE.md and adds overrides
• Don't duplicate information

2. Artifact Lifecycle

• Start in temp directories
• Promote valuable artifacts to docs/ai-artifacts/
• Clean up regularly

3. Clear Naming

• Use descriptive prefixes (exploration-, plan-, analysis-)
• Include timestamps for ordering
• Use ISO 8601 format (sortable)

4. Gitignore Discipline

• Temp directories should always be gitignored
• Memory files should always be tracked
• docs/ai-artifacts/ should be tracked

Related Skills

• gemini-memory-sync - CLAUDE.md ↔ GEMINI.md synchronization
• gemini-exploration-patterns - Exploration output standards
• gemini-context-bridge - Legacy context sharing patterns

Related Commands

• /sync-context - Synchronize memory files
• /gemini-explore - Generates exploration reports
• /gemini-plan - Generates implementation plans

Test Scenarios

Scenario 1: Workspace Setup

Query: "How do I set up a project for Claude and Gemini collaboration?" Expected Behavior:

• Skill activates on "workspace structure" or "cross-cli"
• Provides directory structure and initialization script Success Criteria: User receives complete workspace setup workflow

Scenario 2: Artifact Location

Query: "Where should I store Gemini exploration results?" Expected Behavior:

• Skill activates on "artifact storage" or "where to store"
• Provides location matrix (tracked vs gitignored) Success Criteria: User receives clear guidance on temp vs persistent storage

Scenario 3: Cross-CLI Exchange

Query: "How do I pass context from Claude to Gemini?" Expected Behavior:

• Skill activates on "artifact exchange" or "shared files"
• Provides context handoff pattern Success Criteria: User receives file-based exchange workflow

Version History

• v1.1.0 (2025-12-01): Added MANDATORY section, Test Scenarios, Version History
• v1.0.0 (2025-11-25): Initial release