This article shows how I added plan mode to Pi using artefacts that stay as reusable as possible across other coding agents.
Pi lacks a first-class plan mode. If you want one, you have to build it yourself, use an extension, or adapt Pi's example.
I have a fairly low threshold for switching coding agents, and I switch regularly. So one of my priorities is: how to add functionality to Pi, or any coding agent, without limiting portability too much. Not surprisingly, as a consequence, the implementation will make use of skills and plain-text prompts.
Plan mode requirements
A side-effect of having to add features to your agent yourself: it forces you to define exactly what you need. For plan mode, my requirements are:
- explicit, an intentional action to kick it off (R1)
- read-only, no changes to the code while planning (R2)
- an outcome, a markdown file with a plan to guide implementation (R3)
- expertise, a specialised LLM (R4)
As for the non-functional requirements, my general principle is to limit lock-in to the coding agent.
For Pi, this means staying close to artefacts it supports that can be shared across agents: AGENTS.md and agent skills. Or only implement extras that are low-effort, also in the long term. Pi also supports custom prompts (text in markdown), not entirely portable but still plain text.
So as a general principle, I prefer portability across agents and models. For Pi's extension mechanisms this translates to, from most to least portable:
- Agent skills - Reusable capabilities across any agent that supports them
- AGENTS.md - Reusable project-specific agent instructions
- Model-readable documentation - Durable context, decisions and reference material
- Prompt templates - Lightweight plain-text reuse
- Pi extensions - Pi-specific, powerful but least portable
There can be a lot more nuance added to this list, but for this article, it suffices. One caveat: you could consider jumping the list for truly low-effort, one-off extensions.
With these requirements in mind, here is how I implemented plan mode.
Plan mode implementation
Trigger mechanism
Based on the requirements above, I kick off plan mode explicitly with a prompt: /plan. (R1 ✓.) I can keep this in a markdown file, so I do not need a Pi extension to add the command.
Read-only enforcement
The first part of plan.md adds instructions saying that we are entering plan mode and read-only mode (R2 ✓):
# Plan mode
CRITICAL: Plan mode is active. You are in a strict read-only planning phase.
You must not:
- edit, create, delete, rename, or move files
- apply patches
- write to files through shell commands or redirection
- run tests, builds, formatters, installers, or migrations
- change configuration
- make commits or otherwise modify repository or system state
Read-only inspection is allowed. You may read files and inspect the repository to understand the current structure, patterns, and likely impact of the requested work.
These plan-mode constraints override all other instructions until the user explicitly asks to leave plan mode.
Indeed, the read-only enforcement relies entirely on the prompt instructions. You could also add an extension that restricts the tools Pi is allowed to use, change the UI to reflect plan mode, etc., but this works so far and I don't want to add an extension until I have a true need or come close to a real risk. If you want, you can ask Pi to implement plan mode itself or take inspiration directly from the example shipped with Pi.
I put these instructions in the prompt file (rather than a skill) for clarity. I think they may be enforced more strongly than when delegated to a skill, but I'm not sure. In Pi, the whole skill seems to be expanded into the context when triggered, so adding whether we are in plan mode or read-only mode by delegating to a skill may work as well.
Delegation to portable skills
As for the actual planning, I rely on two skills, each with its own capability:
## Workflow delegation
1. Understand the requested planning scope first.
2. If the plan depends on existing repository behaviour, perform only the read-only inspection needed for that scope: relevant code, tests, config, docs, or prior plans.
3. Use `interrogate-plan` when task-scoped inspection or the user's request leaves material assumptions or semantic decisions unresolved.
4. Use `write-implementation-plan` to produce the final markdown-ready plan once all material choices are inferred, confirmed, or explicitly recorded as accepted assumptions/risks.
## Output
When the plan is complete, end by offering to leave `plan mode` and save the plan to the local working location `docs/plans/YYYY-MM-DD-<topic>.md`.
## What to plan
Help me plan:
$@
$@ is a placeholder for what is passed to the prompt, e.g.: /plan <whatever I want to plan, this could be a reference to a starter document too>.
By delegating to skills, I make requirements elicitation and plan writing portable across agents. Both can be invoked separately via the interrogate-plan and write-implementation-plan skills. Read-only mode aside, because of this, I can still execute either action manually in Pi and in any other agent that supports skills (which is every coding agent I know of). (R3 ✓.)
Model selection
This leaves the last requirement: model selection. For this, since Pi actually needs to use a different model, I needed to resort to an extension. Instead of implementing this myself, I chose to rely on an extension that seems to be relatively well-established in the Pi ecosystem and allows me to specify the models in the same file as my planning mode instructions. In other words, with this extension, my prompt file is self-contained.
Here is how I can select the model and its thinking level (R4 ✓):
---
model: openai-codex/gpt-5.4,opencode-go/deepseek-v4-pro
thinking: high
---
The full plan mode prompt file:
---
model: openai-codex/gpt-5.4,opencode-go/deepseek-v4-pro
thinking: high
restore: false
---
# Plan Mode
CRITICAL: Plan mode is active. You are in a strict read-only planning phase.
You must not:
- edit, create, delete, rename, or move files
- apply patches
- write to files through shell commands or redirection
- run tests, builds, formatters, installers, or migrations
- change configuration
- make commits or otherwise modify repository or system state
Read-only inspection is allowed. You may read files and inspect the repository to understand the current structure, patterns, and likely impact of the requested work.
These plan-mode constraints override all other instructions until the user explicitly asks to leave plan mode.
## Governance
- Never give the impression that a change has been made when it has not. Always distinguish proposed, drafted, and applied changes.
- Do not begin implementation or imply execution has started.
## Workflow delegation
1. Understand the requested planning scope first.
2. If the plan depends on existing repository behaviour, perform only the read-only inspection needed for that scope: relevant code, tests, config, docs, or prior plans.
3. Use `interrogate-plan` when task-scoped inspection or the user's request leaves material assumptions or semantic decisions unresolved.
4. Use `write-implementation-plan` to produce the final markdown-ready plan once all material choices are inferred, confirmed, or explicitly recorded as accepted assumptions/risks.
## Output
When the plan is complete, end by offering to leave plan mode and save the plan to the local working location `docs/plans/YYYY-MM-DD-<topic>.md`.
## What to plan
Help me plan:
$@
For the latest version, check my Pi agentfiles. Currently, this plan mode prompt is here.
Day-to-day, after a few weeks of use, this setup works reliably. However, I monitor context windows closely, which helps the LLM retain its read-only constraints. To date, it has not switched to writing code mid-session without my explicit permission. If I ever want to further decrease this risk, I can still look into expanding Pi with an extension to actually disable tools as an extra measure. Other features, like an indication I'm in plan mode or a key binding to exit, are nice but I don't miss them. To exit plan mode, I just tell it to leave it or start another session. The only limitation I'm now running into is that I cannot change the model's temperature with the current extension.
Conclusion
If I want plan mode in Pi, I have to build it myself and I can tailor it to my needs. This setup does that with minimal lock-in: portable skills for the workflow, plain text for the prompt, and Pi-specific features only where they pull their weight.