gemini-plan

What this skill does

# 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

```text
/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

```bash
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

```bash
# 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

```bash
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

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

### Step 5: Parse Results

```bash
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:

````markdown
---
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

```bash
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