Introducing a Structured Workflow for Gemini CLI: Safer, More Disciplined, and Surprisingly Capable

[mystilleef]

tldr: After one too many unfortunate events, I wanted to implement a poor man's READONLY, PLAN, and BUILD modes for gemini-cli. Let's hope native solutions find their way into gemini-cli before long.

https://github.com/mystilleef/gemini-cli-modes

Why

Like many of you, I sometimes found myself frustrated by the agent's occasional eagerness to modify files or even delete them without explicit, granular permission. This led me to develop a set of custom commands and a structured workflow to bring more discipline and safety to the agent's operations.

The Problem:

Unintended modifications and a lack of clear operational boundaries.

The Solution:

A mode-based workflow that enforces explicit permissions and guides the agent through the Perceive, Reason, Act, and Refine (PRAR) phases of software engineering.

The commands

• /readonly forces the agent into readonly mode by creating a marker
• /explore is used to explore ideas, implement features, fix bugs, and draft specifications
• /plan is used to write a detailed plan to implement the ideas
• /review uses different expert perspectives to review the plan
• /implement disables readonly mode, then uses a task/todo list to implement the plan
• /build a token-efficient form of /implement
• /writeable used to disable readonly mode

The readonly, explore, plan, and review always lock the agent in readonly mode.

The remaining commands disable readonly mode.

The explore command is the only command that takes an argument, your query.

How it Works (in a Nutshell):

The core idea revolves around a .gemini_readonly marker file and custom commands that force the agent into specific operational "modes":

• Safe by Default: You should start the agent in a strict read-only mode (/readonly), preventing any modifications until explicitly allowed.
• Explore & Plan: Commands like /explore and /plan keep the agent in read-only states, allowing it to investigate the codebase, understand problems, and formulate detailed strategies without touching any files.
• Review & Refine: The /review command enables the agent to critically self-assess its plans before execution.
• Controlled Action: Only after a plan is approved can the agent transition to write-enabled modes like /implement or /build. These modes remove the read-only lock and allow the agent to execute changes under strict protocols.
• Direct Access (Expert Use): For quick, simple tasks, /writable offers a direct way to enable write operations without the full PRAR cycle.

Workflows

Full PRAR cycle (token-intensive):

/explore -> /plan -> /review -> /implement

In this workflow plan and review are optional. Use them to increase your chances of one-shotting tasks at the expense of consuming more tokens.

Read-build cycle

/readonly -> /build

This workflow uses significantly less tokens, and is what I use for the vast majority of tasks.

Read-write cycle

/readonly -> /writeable

I use this to get out of readonly mode (e.g if I want to use a custom command).

The Benefits I've Seen:

Beyond the obvious safety improvements (no more accidental file deletions!), this structured approach has had some surprising positive side effects:

• Increased Discipline: The agent is now far more disciplined about modifying projects, always seeking explicit permission through mode transitions.
• Improved "One-Shot" Capabilities: By forcing a more thorough "Perceive" and "Reason" phase, the agent is often able to "one-shot" more complex tasks, sometimes performing at a level I've previously only seen from models like Claude Code. It seems that a more structured thought process leads to better outcomes.
• gemini-flash improvements: Assuming you use the full PRAR workflow, flash is no longer useless for complex tasks.

Disclaimer:

While incredibly powerful, the more structured workflows (especially the full PRAR cycle) can be more token-intensive due to the detailed planning and review steps. However, the trade-off for safety, discipline, and improved results has been well worth it for me.

Credits:

I can't take credit for any of these ideas. These ideas have been floating around discussion boards and forums, and are already in use by other CLI agents in one form or another. I just wanted a cohesive workflow for Gemini

Project:

The github project has details on how to setup the commands and update your settings.json to use these modes. I welcome your feedback.

https://github.com/mystilleef/gemini-cli-modes