Plan Mode

Relevant source files

The following files were used as context for generating this wiki page:

• packages/coding-agent/src/prompts/system/plan-mode-active.md
• packages/coding-agent/src/prompts/agents/plan.md
• packages/coding-agent/src/prompts/system/plan-mode-subagent.md
• packages/coding-agent/test/modes/components/plan-toc.test.ts
• packages/coding-agent/test/plan-mode/approved-plan.test.ts
• packages/coding-agent/examples/extensions/plan-mode.ts
• packages/coding-agent/src/prompts/system/plan-mode-compact-instructions.md

Plan Mode is a specialized architectural phase in the Oh My Pi coding harness designed for safe codebase exploration and the creation of comprehensive execution specifications. In this mode, the agent is restricted to read-only operations, preventing any accidental state changes such as file modifications, commits, or package installations. The primary output of this mode is a "plan file" (typically a .md file located at a local:// URL), which serves as a complete, decision-complete manual for a future implementation agent.

Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:1-12, packages/coding-agent/examples/extensions/plan-mode.ts:7-12

Core Architecture and Constraints

Plan Mode enforces a strict boundary between discovery and implementation. The system ensures that all architectural decisions are finalized before a single line of code is modified.

Operational Restrictions

When Plan Mode is active, the agent is prohibited from:

• Creating, editing, or deleting files (except for the designated plan file).
• Running state-changing commands like git commit, npm install, or database migrations.
• Making any system changes.

Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:4-9, packages/coding-agent/src/prompts/system/plan-mode-subagent.md:4-11

Execution Workflow

The planning process follows a structured four-phase lifecycle to ensure technical accuracy and completeness.

The Plan File

A plan is defined as an execution spec, not a design document. It must be sufficiently detailed that a competent implementer who has not seen the planning conversation can execute it top-to-bottom without making additional design decisions.

Required Plan Content

The plan file (e.g., local://auth-token-refresh-plan.md) must be structured with specific sections to remove ambiguity:

Section	Description
Context	Explains the literal ask and the intended end state.
Approach	Ordered steps for change, naming existing utilities to reuse and exact signatures.
Critical Files	List of ≤5 files that disambiguate non-obvious work.
Verification	Concrete input/output checks to prove the new behavior works.
Assumptions	Decisions made that the user might want to override.

Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:76-114, packages/coding-agent/src/prompts/agents/plan.md:44-52

Plan Manipulation (Hashline Edit Mode)

When isHashlineEditMode is active, the plan is managed using block-level operations to allow incremental updates without rewriting the entire file:

• SWAP.BLK N: Rewrites an entire section in place.
• DEL.BLK N: Removes a whole section.
• INS.BLK.POST N: Adds a new section after an existing one.

Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:45-56, packages/coding-agent/test/modes/components/plan-toc.test.ts:54-72

Implementation and Transitions

Once a plan is completed, the agent must transition to implementation mode. This is triggered by calling the resolve tool with specific metadata.

Approval Mechanisms

Approval is never requested through prose or the ask tool; it is handled exclusively via the resolve tool.

Plan File Resolution Logic

The system uses slugs to map human-readable titles to local:// file paths. A slug like auth-refactor maps to local://auth-refactor-plan.md. If a specific slug is not found, the system may fall back to scanning listed plan files or using a default state path.

Sources: packages/coding-agent/test/plan-mode/approved-plan.test.ts:11-45

Technical Utilities

Several internal components manage the lifecycle and display of plans.

Title Normalization

The system ensures that plan titles are safe for the filesystem.

• Normalization: Converts "My Plan" to "My-Plan" and strips non-alphanumeric characters.
• Humanization: Replaces separators with spaces and capitalizes (e.g., "fix-naming" becomes "Fix naming").

Sources: packages/coding-agent/test/plan-mode/approved-plan.test.ts:60-105

Compact Instructions

When transitioning from planning to execution, the system "compacts" the context. It preserves rationale, rejected alternatives, and discovered code paths while dropping tool-call noise and superseded drafts. This ensures the executor stays focused on the final approved spec.

Sources: packages/coding-agent/src/prompts/system/plan-mode-compact-instructions.md:3-12

Summary

Plan Mode provides a robust safety net for complex architectural changes within the Oh My Pi harness. By enforcing read-only exploration and requiring a decision-complete execution spec, it ensures that implementation is deterministic and grounded in verified codebase facts. The use of specialized tools for block-based editing and title resolution allows for a highly structured and scalable planning workflow.