Gemini CLI

Integration Architecture

Gemini CLI uses GEMINI.md for context and .gemini/commands/*.tomlfor structured commands. Fulcrum maps to both:

┌─────────────────────────────────────────────────┐
│              fulcrum/                           │
│  ├── agents/        → GEMINI.md (agents section)│
│  ├── commands/      → .gemini/commands/*.toml   │
│  └── skills/        → GEMINI.md (skills section)│
└─────────────────────────────────────────────────┘

Generated Structure

Running fulcrum sync --vendor gemini generates:

project-root/
├── GEMINI.md                   # Agents + skills + project context
├── GEMINI.local.md             # Your additions (gitignored)
└── .gemini/
    └── commands/
        ├── start.toml          # Start workflow command
        ├── execute-work.toml   # Execute work command
        ├── status.toml         # Status check command
        ├── review.toml         # Code review command
        └── pr.toml             # PR creation command

GEMINI.md Contents

# Project Context

This project uses Fulcrum for AI-assisted development workflows.

## Agents

### @tech-lead
**Role:** Technical leadership and architectural decisions

**Expertise:**
- System design and architecture
- Code review and quality standards
- Cross-team coordination
- Risk assessment and mitigation

**Invoke when:**
- Making architectural decisions
- Reviewing designs for scalability
- Resolving technical disagreements

**Decision Framework:**
1. Evaluate against project principles
2. Consider long-term maintainability
3. Document rationale

---

### @backend-engineer
**Role:** Server-side implementation specialist

**Expertise:**
- API design and RESTful conventions
- Database schema and optimization
- Authentication and authorization
- Performance tuning

---

## Skills

### brainstorming
**Trigger:** Beginning new features, exploring requirements
**Process:**
1. Clarify the problem domain
2. Generate 3-5 distinct approaches
3. Evaluate trade-offs for each
4. Recommend with clear rationale

### code-reviewer
**Trigger:** "review", "check this code"
**Checklist:**
- Security vulnerabilities (injection, XSS, auth)
- Performance (N+1, memory leaks, blocking)
- Maintainability (naming, structure, tests)
- Style (conventions, formatting)

---

Using Agents

Reference agents in Gemini CLI prompts using natural language or @ mentions:

# Natural language
gemini "As the tech lead, review this architecture proposal"

# @ mention style  
gemini "Get @backend-engineer perspective on this API design"

# Multiple agents
gemini "Need @tech-lead and @devops-engineer input on deployment strategy"

Using TOML Commands

Each command is a TOML file in .gemini/commands/:

# .gemini/commands/start.toml

[command]
name = "start"
description = "Initialize a new work session"
category = "workflow"

[command.parameters]
task = { type = "string", required = true, description = "Task description" }
priority = { type = "string", required = false, default = "medium" }

[command.steps]
analyze = """
Parse the task description and identify:
- Scope and requirements
- Dependencies and blockers
- Estimated complexity
"""

create_bead = """
Create a work item (bead) with:
- Unique ID (BEAD-XXX format)
- Status: planned
- Task description
- Created timestamp
"""

load_context = """
Find and load relevant context:
- Related source files
- Recent changes to affected areas
- Team conventions and patterns
"""

present_plan = """
Output a structured plan:
- Approach summary
- Key milestones
- Risks and mitigations
- Next immediate action
"""

TOML Command Structure

Invoking Commands

# Direct command invocation
gemini /start "Implement OAuth 2.0 with Google"

# With parameters
gemini /start --task "Add user auth" --priority high

# List available commands
gemini /help

# Command help
gemini /start --help

Available Commands

TOML Command Example

Here's a complete example of a code review command:

# .gemini/commands/review.toml

[command]
name = "review"
description = "Review code changes for quality, security, and style"
category = "quality"

[command.parameters]
scope = { type = "string", required = false, default = "staged" }
focus = { type = "string", required = false, description = "security|performance|style" }

[command.steps]
gather_changes = """
Collect code changes based on scope:
- staged: git diff --staged
- branch: git diff main...HEAD
- commit: git show HEAD
"""

security_review = """
Check for security issues:
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization flaws
- Sensitive data exposure
- Dependency vulnerabilities
"""

performance_review = """
Analyze performance implications:
- Database query efficiency (N+1)
- Memory usage patterns
- Blocking operations
- Cache utilization
"""

style_review = """
Verify code style compliance:
- Naming conventions
- File organization
- Comment quality
- Test coverage
"""

generate_report = """
Produce structured review report:
- Critical issues (must fix)
- Important issues (should fix)
- Suggestions (consider fixing)
- Overall assessment
"""

[command.output]
format = "markdown"
sections = ["summary", "critical", "important", "suggestions", "verdict"]

Using Skills

Skills are documented in GEMINI.md and trigger from context:

# In GEMINI.md

## Skills

### brainstorming
**Trigger:** "brainstorm", "explore options", "what approaches"
**Behavior:**
1. Don't jump to implementation
2. Generate multiple distinct approaches
3. Compare trade-offs objectively
4. Recommend with rationale

### test-engineer
**Trigger:** "write tests", "test coverage", "testing"
**Behavior:**
1. Analyze code under test
2. Identify boundary conditions
3. Generate comprehensive test cases
4. Aim for meaningful coverage, not 100%

### documentation-writer
**Trigger:** "document", "add docs", "explain"  
**Behavior:**
1. Match existing doc style
2. Include examples
3. Document the "why" not just "what"
4. Keep it concise

Triggering Skills

# Natural triggers
gemini "Let's brainstorm caching strategies"

# Explicit reference
gemini "Use the test-engineer skill to write tests for auth.ts"

# Context-based (auto-detected)
gemini "I need to add documentation for the API"  # Triggers docs skill

Customization

Add project-specific context in GEMINI.local.md:

# GEMINI.local.md (gitignored)

## Team Conventions

### Branch Naming
- feature/TICKET-123-description
- bugfix/TICKET-456-description  
- release/v1.2.3

### Commit Format
type(scope): subject

Types: feat, fix, docs, style, refactor, perf, test, chore

### Code Review Policy
- 2 approvals required
- Security team review for auth changes
- Load test required for database changes

---

## Custom Skills

### deploy-staging
**Trigger:** "deploy to staging", "staging deploy"
**Steps:**
1. Verify all tests pass
2. Build production bundle
3. Deploy to staging environment
4. Run smoke tests
5. Report deployment status

Custom Commands

# Create custom command
cat > .gemini/commands/deploy-staging.toml << 'EOF'
[command]
name = "deploy-staging"
description = "Deploy current branch to staging"
category = "deployment"

[command.parameters]
skip_tests = { type = "boolean", required = false, default = false }

[command.steps]
verify = "Run test suite unless skip_tests is true"
build = "Build production bundle"
deploy = "Deploy to staging environment"
smoke_test = "Run smoke tests against staging"
report = "Output deployment URL and status"
EOF

Vendor Comparison

Google Ecosystem Integration

Gemini CLI naturally integrates with other Google services:

# Use with Google Cloud context
export GOOGLE_CLOUD_PROJECT=my-project
gemini "Deploy this to Cloud Run"

# Vertex AI integration
gemini --model gemini-pro "Analyze this codebase"

# Cloud Build triggers
gemini /review --scope "cloudbuild.yaml changes"

Troubleshooting

GEMINI.md not loading

# Verify file exists in project root
ls -la GEMINI.md

# Check for UTF-8 encoding
file GEMINI.md

# Test with explicit path
gemini --context ./GEMINI.md "test"

TOML parse errors

# Validate TOML syntax
npx toml-lint .gemini/commands/start.toml

# Common issues:
# - Unquoted strings with special characters
# - Missing closing brackets
# - Multi-line strings need triple quotes

# Multi-line string example (correct):
step = """
This is a
multi-line step
"""

Commands not found

# Ensure .gemini directory structure
mkdir -p .gemini/commands

# Check command discovery
gemini /help

# Force refresh
gemini --refresh-commands /help