git:20260714.061716b to git:20260714.4fd0952

+ description: Reference knowledge for Google Gemini CLI compatibility. Describes how Gemini CLI discovers context (GEMINI.md), configures settings.json, and overrides its system prompt so Forge can interoperate on a dual-platform project. Use when a user asks how Forge coexists with Gemini CLI, how GEMINI.md / @imports / .gemini/settings.json work, or how to add Gemini support alongside Claude Code. DO NOT create files from this skill — it is reference material only.

+ > **REFERENCE ONLY.** Do NOT create `GEMINI.md`, `.gemini/`, playbooks, or rules files in the user's project unless the user explicitly asks to add Gemini CLI support. NXTG-Forge delivers all agent functionality through the Claude Code plugin system; this skill only explains the *other* tool so you can advise on interop.

+ Gemini CLI builds its instructional context ("memory") by **concatenating** (not overriding) every `GEMINI.md` it finds, from broadest to most specific:

+ 2. Current directory and each parent up to the `.git` root — project instructions

+ It respects `.gitignore` and `.geminiignore` when scanning. The context filename is configurable via `context.fileName` (see below), so it is not always literally `GEMINI.md`.

+ `GEMINI.md` supports `@path/to/file.md` imports (relative or absolute), which pull in:

+ - `@.gemini/playbooks/feature-planning.md` — on-demand skill-equivalents

+ - `/memory show` — inspect the fully-assembled loaded context

+ - `/memory refresh` — rescan after editing any `GEMINI.md`

+ ## `.gemini/settings.json`

+ Project-level config (global variant: `~/.gemini/settings.json`). Modern Gemini CLI groups keys under **nested categories** — `general`, `ui`, `model`, `context`, `tools`, `mcpServers`:

+ "general": { "vimMode": true, "defaultApprovalMode": "default" },

+ "ui": { "theme": "Default", "hideBanner": true },

+ "context": { "fileName": ["GEMINI.md"] },

+ "tools": { "useRipgrep": true }

+ - `context.fileName` accepts a **single string OR an array of strings**.

+ - `general.defaultApprovalMode` values: `"default"` (prompt), `"auto_edit"` (auto-approve edits), `"plan"` (read-only). This is the tool-approval gate — it lives under `general`, **not** `tools` (see Gotchas).

+ ## System Prompt Override (`.gemini/system.md`)

+ Set `GEMINI_SYSTEM_MD` in `.gemini/.env` (or the shell env) to **fully replace** Gemini CLI's built-in system prompt — this is a hard replacement, not a merge:

+ - `GEMINI_SYSTEM_MD=1` (or `true`) → loads `.gemini/system.md`

+ - `GEMINI_SYSTEM_MD=/abs/path/to/file.md` → treats the value as a path to the prompt file

+ Template variables let you re-inject the built-in pieces you replaced:

+ - `${AvailableTools}` — bulleted list of currently enabled tool names

+ - `${AgentSkills}` — the full agent-skills section

+ - `${SubAgents}` — the available sub-agents section

+ - `${<toolName>_ToolName}` — the resolved name of a specific tool

+ When an override is active, Gemini CLI shows a `|⌐■_■|` indicator in the UI. No indicator = your `system.md` was not picked up.

+

+ ## Typical Dual-Platform Layout

+

+ │ ├── settings.json # nested-category CLI config

+ │ ├── system.md # optional full system-prompt replacement

+ │ ├── .geminiignore # context exclusions

+ │ ├── rules/ # always-on @imported rules

+ │ └── playbooks/ # on-demand @imported skill-equivalents

+ ├── GEMINI.md # main context file (Gemini's CLAUDE.md analog)

+ └── src/module/GEMINI.md # optional module-scoped context

+ When a project must support BOTH Claude Code (via Forge) and Gemini CLI:

+ 1. **Forge owns Claude Code** — commands, agents, skills, hooks (the plugin).

+ 2. **Gemini reads only its own files** — `GEMINI.md`, `.gemini/`.

+ 3. **Shared state** — both can read `.claude/governance.json` for project context.

+ 4. **No duplication** — keep platform-specific agent instructions in separate files; Gemini has no plugin/slash-command layer, so the portable pattern is `GEMINI.md` + `@imports` (playbooks) + an optional `system.md` override.

+ ## Claude Code vs Gemini CLI

+ |--------|--------------------|------------|

+ | Config file | `CLAUDE.md` | `GEMINI.md` (name configurable) |

+ | Hierarchical scan | `@import` chain, no auto parent-scan | Yes — scans parents to `.git` root |

+ | Imports | `@path` in CLAUDE.md | `@file.md` in GEMINI.md |

+ | Plugin/marketplace | Yes | No |

+ | System prompt | Fixed; extend via CLAUDE.md | Full replacement via `system.md` |

+ | MCP servers | `.mcp.json` | `mcpServers` in settings.json |

+ ## Gotchas

+

+ - **`approvalMode` is under `general`, not `tools`.** It is `general.defaultApprovalMode`. Older examples that wrote `tools.approvalMode` silently no-op — the key is ignored, and the CLI keeps prompting. Do not repeat that mistake when advising a user.

+ - **settings.json migrated flat → nested.** Pre-migration blog posts and README snippets use flat keys (`contextFileName`, `vimMode`, `autoAccept`) that are silently ignored by current versions. The live schema nests them (`context.fileName`, `general.vimMode`, `general.defaultApprovalMode`). Verify against `schemas/settings.schema.json` in the gemini-cli repo before quoting a key.

+ - **`GEMINI_SYSTEM_MD` wipes ALL built-in instructions**, including tool-use guidance. A minimal `system.md` that omits `${AvailableTools}`/`${AgentSkills}` produces a model that can't see its own tools/skills. Always re-inject the pieces you still need via template variables.

+ - **`GEMINI_SYSTEM_MD` value is overloaded.** `1`/`true` means "load `.gemini/system.md`"; any other string is treated as a **file path**, not a boolean. A typo'd truthy value (`yes`, `on`) becomes a path that doesn't exist and the override silently fails to apply.

+ - **Context is concatenated, not overridden.** A subdirectory `GEMINI.md` does NOT replace the project root's — both load. Contradictory instructions across levels both reach the model. There is no "most-specific-wins" resolution like some tools have.

+ - **`.geminiignore` filters context, not just tool access.** A `GEMINI.md` (or `@import` target) under an ignored path won't load, so context can silently go missing without an error.

+

+ - Gemini CLI configuration reference — https://geminicli.com/docs/reference/configuration/

+ - Gemini CLI system-prompt override — https://geminicli.com/docs/cli/system-prompt/

+ - settings.schema.json — https://github.com/google-gemini/gemini-cli/blob/main/schemas/settings.schema.json