melodic-software/gemini-plan

Gemini Plan Command

Generate structured implementation plans using Gemini CLI. Plans are formatted for Claude to execute, with clear task breakdowns, file modifications, and sequence ordering.

Usage

/google-ecosystem:gemini-plan <task-description> [options]

Arguments

• $ARGUMENTS (required): Description of what you want to implement
• --context <glob> (optional): File patterns to include as context (e.g., src/**/*.ts)
• --output <path> (optional): Output path for plan (default: docs/ai-artifacts/plans/)
• --pro (optional): Use Gemini Pro for complex planning (default: Flash)

Examples

• /google-ecosystem:gemini-plan "Add user authentication with JWT"
• /google-ecosystem:gemini-plan "Refactor database layer to use repository pattern" --context "src/db/**"
• /google-ecosystem:gemini-plan "Implement dark mode toggle" --output ./plans/
• /google-ecosystem:gemini-plan "Migrate from REST to GraphQL" --pro

When to Use

Use this command when:

• Planning complex multi-file changes
• Want a "second brain" perspective on implementation approach
• Need to break down a large feature into actionable steps
• Validating your own implementation plan
• Getting alternative approaches to consider

Philosophy: "Claude Orchestrates, Gemini Plans"

Gemini's different reasoning approach often provides:

• Alternative architectural perspectives
• Edge cases Claude might miss
• Different sequencing of implementation steps
• Fresh eyes on potential issues

Execution

Step 1: Parse Arguments

task_description="$ARGUMENTS"
context_pattern=""
output_dir="docs/ai-artifacts/plans"
model="gemini-2.5-flash"

# Parse optional flags
while [[ $# -gt 0 ]]; do
  case $1 in
    --context)
      context_pattern="$2"
      shift 2
      ;;
    --output)
      output_dir="$2"
      shift 2
      ;;
    --pro)
      model="gemini-2.5-pro"
      shift
      ;;
    *)
      shift
      ;;
  esac
done

Step 2: Gather Context

# Read CLAUDE.md for project conventions
claude_context=""
if [ -f "CLAUDE.md" ]; then
  claude_context=$(cat CLAUDE.md)
fi

# Gather specified context files
file_context=""
if [ -n "$context_pattern" ]; then
  file_context=$(find . -path "$context_pattern" -type f | xargs cat 2>/dev/null | head -c 500000)
fi

Step 3: Build Planning Prompt

prompt="PLANNING MODE: Generate an implementation plan for Claude Code to execute.

## Task
$task_description

## Project Context (from CLAUDE.md)
$claude_context

## Relevant Code Context
$file_context

## Instructions

Generate a detailed implementation plan with the following structure:

### 1. Summary
Brief description of the approach (2-3 sentences)

### 2. Prerequisites
- Dependencies to install
- Configuration changes needed
- Files to read/understand first

### 3. Implementation Tasks
Numbered list of specific, actionable tasks:
1. [FILE: path/to/file.ts] Description of change
2. [FILE: path/to/another.ts] Description of change
...

### 4. File Modifications
Table format:
| File | Action | Description |
| --- | --- | --- |
| path/to/file.ts | CREATE/MODIFY/DELETE | What changes |

### 5. Sequence Order
Which tasks depend on others, what order to execute

### 6. Testing Strategy
How to verify the implementation works

### 7. Potential Risks
- Risk 1: Mitigation
- Risk 2: Mitigation

### 8. Recommendations for Claude
Specific guidance for Claude when executing this plan

Format the output as structured markdown that another AI agent can parse and execute."

Step 4: Execute Planning

result=$(echo "$prompt" | gemini "$(cat)" --output-format json -m "$model")

Step 5: Parse Results

response=$(echo "$result" | jq -r '.response // "Planning failed"')
total_tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
model_used=$(echo "$result" | jq -r '.stats.models | keys[0] // "unknown"')

Step 6: Generate Plan Document

Create structured markdown plan:

---
generated-by: gemini-cli
model: {model_used}
timestamp: {ISO8601}
tokens: {total_tokens}
task: "{task_description}"
---

# Implementation Plan

## Machine-Readable Summary
```json
{
  "type": "plan",
  "task": "{task_description}",
  "tokens_used": {total_tokens},
  "model": "{model_used}",
  "files_to_modify": [
    "path/to/file1.ts",
    "path/to/file2.ts"
  ],
  "estimated_complexity": "low|medium|high"
}
```

{response}

---
*Generated by Gemini CLI via `/gemini-plan` command*
*Review and validate before execution*

Step 7: Save Plan

mkdir -p "$output_dir"
timestamp=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
# Create slug from task description
slug=$(echo "$task_description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | head -c 50)
output_file="$output_dir/plan-${slug}-${timestamp}.md"
echo "$plan" > "$output_file"
echo "Plan saved to: $output_file"

Output Format

Plans include YAML frontmatter for machine parsing:

• generated-by: Always "gemini-cli"
• model: Which Gemini model was used
• timestamp: ISO 8601 format
• tokens: Total tokens consumed
• task: Original task description

Integration with Claude

After generating a plan:

1. Review: Claude reads the plan from docs/ai-artifacts/plans/
2. Validate: Claude checks plan against project conventions
3. Execute: Claude implements tasks in sequence
4. Verify: Claude runs tests per the testing strategy

Plan Quality Checklist

Good plans should have:

• [ ] Clear, atomic task descriptions
• [ ] Specific file paths (not "the component file")
• [ ] Logical sequence with dependencies noted
• [ ] Testing strategy for verification
• [ ] Risk assessment with mitigations

Notes

• Uses Flash model by default (Pro for --pro flag)
• Includes CLAUDE.md context automatically
• Plans are saved to docs/ai-artifacts/plans/ (git-tracked)
• Review plans before having Claude execute them
• Plans are suggestions - Claude should validate against project conventions