Gemini CLI Installation

Gemini CLI runs skills inline within a single context window. While it doesn’t support true sub-agent delegation, the structured SDD workflow still provides significant value for planning and implementation.

Prerequisites

Gemini CLI installed and configured
Git installed for cloning the repository
Access to ~/.gemini/ directory
GEMINI_SYSTEM_MD=1 environment variable set

Installation Steps

Clone the repository

git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite

Run the installer

./scripts/install.sh
# Choose option 3: Gemini CLI

./scripts/install.sh --agent gemini-cli

This copies skills to ~/.gemini/skills/sdd-*/You should see output like:

Installing skills for Gemini CLI...
  ✓ _shared (3 convention files)
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-propose
  ✓ sdd-spec
  ✓ sdd-design
  ✓ sdd-tasks
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  9 skills installed → ~/.gemini/skills

Configure system prompt

Gemini CLI requires the system prompt to be enabled via environment variable.Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export GEMINI_SYSTEM_MD=1

Apply changes:

source ~/.bashrc  # or ~/.zshrc

Add orchestrator to GEMINI.md

Open or create the Gemini system prompt file:

code ~/.gemini/GEMINI.md

If the file doesn’t exist, create it. This file contains system-level instructions for Gemini CLI.

Append the contents from examples/gemini-cli/GEMINI.md to your existing file.

View orchestrator instructions

The orchestrator section teaches Gemini CLI to:

Detect SDD triggers and commands
Read skill files from ~/.gemini/skills/sdd-*/SKILL.md
Execute skills inline (within current context)
Track state between phases
Follow artifact storage policies

Key sections added:

Operating Mode (delegate-only principle)
Artifact Store Policy
Commands table
Command → Skill Mapping
Engram Artifact Convention

Verify installation

Start Gemini CLI in any project:

gemini

Type:

/sdd-init

Expected response:

Reading sdd-init skill from ~/.gemini/skills/sdd-init/SKILL.md...

✓ Detected stack: [your project's stack]
✓ Project: [project-name]
✓ SDD initialized

Configuration Locations

Skills Directory

~/.gemini/skills/sdd-*/Contains 9 skill folders + _shared/ conventions

System Prompt

~/.gemini/GEMINI.mdOrchestrator instructions and system configuration

Environment

~/.gemini/.envMust contain GEMINI_SYSTEM_MD=1

How Inline Execution Works

Unlike Claude Code or OpenCode, Gemini CLI doesn’t have a Task tool for sub-agent delegation. Instead: Key differences:

Skills run in the same context window as the orchestrator
No fresh context per phase (more context usage)
Still provides structured workflow and artifact management
Planning phases work well; implementation may hit context limits on large features

Example Usage

Initialize SDD

You: /sdd-init

Gemini: Reading sdd-init skill...
        
        Detecting project stack...
        ✓ Framework: Express.js
        ✓ Language: TypeScript
        ✓ Database: PostgreSQL + TypeORM
        
        Checking for Engram MCP server...
        ✓ Engram detected
        
        Artifact store: engram
        SDD initialized for project: my-api

Start a New Feature

You: /sdd-new add-rate-limiting

Gemini: Reading sdd-explore skill...
        
        Analyzing codebase for existing rate limiting...
        ✓ No rate limiting middleware detected
        ✓ Express middleware stack found in app.ts
        ✓ Redis client available (for distributed rate limiting)
        
        Reading sdd-propose skill...
        
        Creating proposal for: add-rate-limiting
        
        Proposal Summary:
        - Intent: Add API rate limiting with Redis backend
        - Scope: Rate limiter middleware, Redis integration, per-endpoint config
        - Approach: express-rate-limit + rate-limit-redis
        - Rollback: Remove middleware, keep Redis (used elsewhere)
        
        Artifact stored: sdd/add-rate-limiting/proposal
        
        Ready to continue with specs and design?

Fast-Forward Planning

You: /sdd-ff add-rate-limiting

Gemini: Fast-forwarding through planning phases...
        
        [1/4] Creating specifications...
        ✓ Requirements: 4 (SHALL enforce limits, SHALL use Redis, etc.)
        ✓ Scenarios: 9 (normal request, rate limit exceeded, etc.)
        ✓ Stored: sdd/add-rate-limiting/spec
        
        [2/4] Creating technical design...
        ✓ Middleware architecture
        ✓ Redis key structure: ratelimit:{ip}:{endpoint}
        ✓ Configuration: per-route limits in config.ts
        ✓ Stored: sdd/add-rate-limiting/design
        
        [3/4] Breaking down into tasks...
        ✓ Phase 1: Redis setup (2 tasks)
        ✓ Phase 2: Middleware implementation (3 tasks)
        ✓ Phase 3: Per-route configuration (2 tasks)
        ✓ Stored: sdd/add-rate-limiting/tasks
        
        All planning complete (7 tasks total).
        Run /sdd-apply to implement.

Artifact Storage

engram (Recommended)
openspec
none

# Auto-detected if Engram MCP server is available

Gemini CLI can use Engram’s mem_observe tool if the MCP server is installed and running.Storage format:

title:     sdd/add-rate-limiting/proposal
topic_key: sdd/add-rate-limiting/proposal
type:      architecture
project:   my-api

Recovery:

1. mem_search(query: "sdd/add-rate-limiting/proposal", project: "my-api")
2. mem_get_observation(id)

# Only when you explicitly request file artifacts

Creates file-based artifacts in your project:

openspec/
├── config.yaml
├── specs/
└── changes/
    └── add-rate-limiting/
        ├── proposal.md
        ├── specs/
        ├── design.md
        └── tasks.md

# Ephemeral mode - default fallback

Results returned inline. No persistence.Good for:

Quick exploration
Privacy-sensitive environments
When you don’t need artifact history

System Prompt Setup

Gemini CLI requires the system prompt to be explicitly enabled:

Option 1: Environment Variable (Global)

Add to shell profile:

# ~/.bashrc or ~/.zshrc
export GEMINI_SYSTEM_MD=1

Option 2: .env File (Per-Session)

Create or edit ~/.gemini/.env:

GEMINI_SYSTEM_MD=1

Verify System Prompt is Loaded

gemini
# In Gemini prompt:
What system instructions do you have about SDD?

If loaded correctly, Gemini should reference the orchestrator instructions from GEMINI.md.

Verification Checklist

Check skills are installed

ls ~/.gemini/skills/sdd-*/

Should show 9 directories:

sdd-apply/  sdd-design/  sdd-init/  sdd-spec/
sdd-archive/  sdd-explore/  sdd-propose/  sdd-tasks/  sdd-verify/

Check shared conventions

ls ~/.gemini/skills/_shared/

Should show:

engram-convention.md
openspec-convention.md
persistence-contract.md

Verify GEMINI.md exists

cat ~/.gemini/GEMINI.md | grep -i "sdd"

Should return matches if orchestrator instructions are present.

Check environment variable

echo $GEMINI_SYSTEM_MD

Should output: 1

Test SDD command

gemini
# In Gemini prompt:
# /sdd-init

Should recognize the command and read the sdd-init skill.

Troubleshooting

Command not recognized

Problem: Gemini doesn’t recognize /sdd-initSolutions:

Check GEMINI_SYSTEM_MD=1 is set: echo $GEMINI_SYSTEM_MD
Verify ~/.gemini/GEMINI.md contains SDD orchestrator instructions
Restart terminal session to reload environment variables
Try alternative phrasing: “Initialize SDD for this project”

Skills not found

Problem: Gemini can’t read skill filesSolutions:

Verify skills are in ~/.gemini/skills/sdd-*/
Check file permissions allow reading
Ensure each skill has SKILL.md file
Try absolute path in orchestrator instructions

System prompt not loading

Problem: Orchestrator instructions not activeSolutions:

Set environment variable: export GEMINI_SYSTEM_MD=1
Add to shell profile for persistence
Verify ~/.gemini/GEMINI.md exists and is readable
Restart Gemini CLI after making changes

Context window issues

Problem: Errors about context length on large featuresSolutions:

Use /sdd-explore first to understand scope before committing
Break large features into smaller changes
Use none artifact mode to reduce context usage
Consider using Claude Code or OpenCode for large features (true sub-agents)

Limitations vs Claude Code/OpenCode

Feature	Gemini CLI	Claude Code / OpenCode
Sub-agent delegation	❌ Inline execution	✅ Fresh context per phase
Context isolation	❌ Shared context	✅ Isolated per sub-agent
Large feature support	⚠️ Context limits	✅ Scales better
Setup complexity	✅ Simple	⚠️ Requires Task tool
Planning phases	✅ Works well	✅ Works well
Implementation	⚠️ May hit limits	✅ Batched execution

For the best sub-agent experience with fresh context windows, consider using Claude Code or OpenCode.

Next Steps

Quick Start

Learn the SDD workflow

Commands Reference

Complete command documentation

Engram Setup

Install recommended persistence

Upgrade to OpenCode

Get true sub-agent support

Get Started

Installation

Guides

Commands

Prerequisites

Installation Steps

Configuration Locations

Skills Directory

System Prompt

Environment

How Inline Execution Works

Example Usage

Initialize SDD

Start a New Feature

Fast-Forward Planning

Artifact Storage

System Prompt Setup

Option 1: Environment Variable (Global)

Option 2: .env File (Per-Session)

Verify System Prompt is Loaded

Verification Checklist

Troubleshooting

Limitations vs Claude Code/OpenCode

Next Steps

Quick Start

Commands Reference

Engram Setup

Upgrade to OpenCode

​Prerequisites

​Installation Steps

​Configuration Locations

Skills Directory

System Prompt

Environment

​How Inline Execution Works

​Example Usage

​Initialize SDD

​Start a New Feature

​Fast-Forward Planning

​Artifact Storage

​System Prompt Setup

​Option 1: Environment Variable (Global)

​Option 2: .env File (Per-Session)

​Verify System Prompt is Loaded

​Verification Checklist

​Troubleshooting

​Limitations vs Claude Code/OpenCode

​Next Steps

Quick Start

Commands Reference

Engram Setup

Upgrade to OpenCode

Prerequisites

Installation Steps

Configuration Locations

How Inline Execution Works

Example Usage

Initialize SDD

Start a New Feature

Fast-Forward Planning

Artifact Storage

System Prompt Setup

Option 1: Environment Variable (Global)

Option 2: .env File (Per-Session)

Verify System Prompt is Loaded

Verification Checklist

Troubleshooting

Limitations vs Claude Code/OpenCode

Next Steps