A poor person's plan mode for the Gemini CLI

# A poor person's plan mode for the Gemini CLI

![Read-only Mode Diagram](assets/readonly.png)

**If you don't like Gemini eagerly or randomly modifying, or even
deleting, files in your projects, look no further.**

This project provides a set of custom commands and skills to enforce a
structured, mode-based workflow for the Gemini CLI agent. These modes
guide the agent through the distinct phases of a software engineering
task—Perceive, Reason, Act, and Refine (`PRAR`)—ensuring a safe,
deliberate, and verifiable process.

**Important:** _Assuming you have hooks properly installed, all sessions
begin in `readonly` mode._

## Core concepts: Operational modes

Each custom command transitions the Gemini CLI agent into a specific
**operational mode**, each with its own set of permissions and
protocols. The system relies on the `.gemini_readonly` marker file,
which enforces a "Safe-Default" `readonly` state, preventing accidental
modifications.

- **Read-Only Modes (`/readonly`):** Assuming you have hooks properly
  installed, the agent starts all sessions in `readonly` mode. The mode
  serves as a perfect base for investigation, analysis, and planning.
  The system disables all file modification tools.
- **Write-Enabled Modes (`/writable`, `/build`, `/implement`):** Use
  these set of commands to disable `readonly` mode and enable file
  modification tools. These modes allow executing an approved plan. The
  agent removes the `.gemini_readonly` marker and enables file
  modification tools under strict protocols.

## Setup and installation

To use these custom modes, place the project files into your
`~/.gemini/` directory and configure your `settings.json` file.

### 1. Required directory structure

Place the files and directories from this project directly inside your
`~/.gemini/` directory. Your `~/.gemini/` folder should look like this:

```bash
~/.gemini/
├── settings.json
├── SYSTEM.md                              # Foundational operating principles
├── GEMINI.md                              # Project-specific directives
├── commands/
│   ├── build.toml
│   ├── implement.toml
│   ├── plan.toml
│   ├── readonly.toml
│   ├── review.toml
│   └── writable.toml
├── hooks/                                  # Enforcement and behavior hooks
│   ├── disable-readonly-sessionend.sh    # NEW: Clean session termination
│   ├── enable-readonly-startup.sh
│   ├── enforce-eprime.sh
│   ├── enforce-readonly.sh
│   └── remind-readonly-dynamic.sh
├── kbase/                                  # CONSOLIDATED: Unified knowledge base
│   ├── GEMINI.md
│   ├── agent-protocols.md
│   ├── cloud-patterns.md
│   ├── data-science-workflow.md
│   ├── e-prime-protocol.md
│   ├── engineering-principles.md
│   ├── gemini-prompt-engineering.md
│   └── ui-ux-design.md
└── skills/                                 # NEW: Skills-based architecture
    ├── build-mode/
    │   └── SKILL.md
    ├── implement-mode/
    │   └── SKILL.md
    ├── plan-mode/
    │   └── SKILL.md
    ├── readonly-mode/
    │   ├── SKILL.md
    │   ├── scripts/
    │   └── tests/
    ├── review-mode/
    │   └── SKILL.md
    └── write-mode/
        ├── SKILL.md
        ├── scripts/
        └── tests/
```

### 2. `settings.json` configuration

The `settings.json` file plays a crucial role for the Gemini CLI agent
to locate the `kbase` directory, enable the experimental skills feature,
configure hooks, and manage session lifecycle. Copy the settings in
`settings.json` from this project to your own in `~/.gemini/`. The file
includes:

- Experimental skills feature activation
- Tools hooks configuration (`enableHooks`)
- Context configuration for loading knowledge base
- Model configuration with custom aliases for temperature and output
  control
- Hooks configuration (`hooksConfig`) to enable hook system
- Hook definitions for read-only enforcement and session lifecycle

**Key hooks configured:**

- `SessionStart`: Creates `.gemini_readonly` marker when session begins
- `BeforeAgent`: Injects `readonly` reminders and enforces E-Prime
  communication protocol before agent execution
- `BeforeTool`: Blocks write operations (write, replace, shell commands,
  file operations, etc.) when `.gemini_readonly` marker exists
- `SessionEnd`: Removes `.gemini_readonly` marker when session
  terminates, ensuring clean exit state

The configuration follows this structure:

```json
{
  "experimental": {
    "skills": true
  },
  "tools": {
    "enableHooks": true
  },
  "context": {
    "loadMemoryFromIncludeDirectories": true,
    "includeDirectories": ["~/.gemini/kbase"]
  },
  "modelConfigs": {
    "customAliases": {
      "base": {
        "modelConfig": {
          "generateContentConfig": {
            "temperature": 0.1,
            "topP": 0.95
          }
        }
      },
      "chat-base": {
        "extends": "base",
        "modelConfig": {
          "generateContentConfig": {
            "temperature": 0.2,
            "topP": 0.9,
            "topK": 1
          }
        }
  

... (truncated)