Proposal: Replace Chat-Based Planning with Document-Based Slice Plans

[AmirTlinov]

Problem

The current planning mode in Codex outputs plans as plain chat messages in the conversation stream. The plan does remain in the agent's context somehow, but this process is completely opaque to the user. There is no way to see what plan the agent is following, whether it's still in context, or what stage of execution the agent is at. Over the course of a complex task, this turns into implicit magic — the user has to trust that the agent is still on track without any way to verify it.

This creates three specific issues:

1. Planning Is Opaque

The plan currently lives somewhere in the agent's context, but there is no explicit, referenceable artifact the user can inspect. You cannot open the plan, check its status, or confirm the agent is still following it. If the plan degrades or gets lost from context mid-execution, the user has no way to know. This lack of transparency makes it impossible to audit or steer the agent's work.

2. Plans Are Shallow and Lack Detail

Because plans are produced as a single chat output, they tend to be compressed and high-level. Implementation details, edge cases, dependencies, and acceptance criteria are often missing. This hurts the agent itself — when it later tries to execute a vague plan, it has to re-infer details, leading to inconsistent or incomplete results.

3. No Progress Tracking

There is no mechanism for the agent to mark which parts of the plan are done, in progress, or remaining. As execution proceeds, the agent can lose track, repeat work, or skip steps. The user is similarly blind — there is no live status of plan execution.

---

Proposed Solution: Persistent Plan Documents Decomposed into Slices

Instead of keeping the plan as an implicit part of the chat context, the agent should create explicit plan documents on disk — decomposed into multiple slice files.

Proposed Structure

Plans should be stored outside the repository, in a dedicated directory like:

~/.codex/plans/<repository_name>_<session_id>/<plan_name>/
  PLAN.md          # Master plan — the index document
  slice-1.md       # First slice
  slice-2.md       # Second slice
  ...

• PLAN.md serves as the index: it defines the overall goal, requirements, and links to each slice document.
• Each slice-*.md is a self-contained unit of work with its own context, steps, and acceptance criteria.
• The agent updates slice documents as it works — marking steps complete, adding notes, flagging blockers.

Why Decompose into Slices?

• Forces the agent to be specific. When the agent must create a dedicated document for each slice, it naturally produces richer, more detailed plans — because each slice must stand on its own.
• Solves context loss. Each slice is small enough to be fully loaded into context when needed. The agent can explicitly re-read any slice file at any time, so the plan never silently disappears.
• Enables progress tracking. The agent can update checkboxes and status fields in each slice as it works. The user can inspect any slice file at any time to see exactly what has been done.
• Makes planning transparent. The plan is no longer implicit magic inside the chat — it is a set of files on disk that the user can open, read, review, and even edit before execution.

---

Benefits

• The plan becomes an explicit, persistent artifact rather than an ephemeral chat message.
• The user can inspect, audit, and review the plan at any point.
• The agent can re-read any slice to restore context, eliminating silent plan loss.
• Slice decomposition incentivizes detailed, actionable plans rather than vague outlines.
• Progress tracking becomes built-in — both for the agent and the user.
• Storing plans in ~/.codex/plans/ keeps them outside the repository, avoiding pollution of the working tree.

---

Integration with Scout Models: Slice-Driven Context Delivery

This proposal is designed to work in concert with the Scout Models proposal (#11751), which introduces lightweight, read-only context-delivery agents (scouts) that gather precisely anchored code fragments for the primary model.

Slices and scouts are complementary — slices define what needs to be done in manageable units, and scouts deliver the exact context needed to do it.

The Problem Slices Solve for Scouts

A large plan for a complex task might require context from dozens of files across an entire repository. If a scout tries to gather all context for the full plan at once, the result is either:

• Context overflow — the scout attempts to deliver the entire repository (or a large portion of it) in a single context package, exceeding practical token limits.
• Context dilution — the scout is forced to aggressively compress or omit fragments, and the primary model receives incomplete information.

Slices eliminate this problem by decomposing the plan into small, self-contained units of work. Each slice has a narrow, well-defined scope — which means a scout can gather a focused, complete context package for that specific slice without touching unrelated parts of the codebase.

How the Execution Loop Works

The primary (executor) agent does not need to understand the entire repository at once. Instead, it works iteratively — one slice at a time:

┌─────────────────────────────────────────────────────────────┐
│ PLAN.md (master plan — index of all slices)                 │
└──────────────┬──────────────────────────────────────────────┘
               │
               │  Agent picks next pending slice
               ▼
┌─────────────────────────────────────────────────────────────┐
│ slice-N.md                                                  │
│ • Goal, steps, acceptance criteria                          │
│ • Files likely involved (hints for scouts)                  │
└──────────────┬──────────────────────────────────────────────┘
               │
               │  Scout receives slice scope
               ▼
┌─────────────────────────────────────────────────────────────┐
│ SCOUT LAYER                                                 │
│ • Reads slice-N.md to understand what is needed             │
│ • Traverses only the relevant parts of the repo             │
│ • Places precise anchors on code fragments                  │
│ • Delivers a clean, complete context package                │
│   scoped to this slice only                                 │
└──────────────┬──────────────────────────────────────────────┘
               │
               │  Focused context package
               ▼
┌─────────────────────────────────────────────────────────────┐
│ PRIMARY AGENT (executor)                                    │
│ • Receives slice-N.md + targeted context package            │
│ • Has everything needed — no additional repo searches       │
│ • Executes the slice: produces patches / changes            │
│ • Updates slice-N.md (marks steps complete, adds notes)     │
└──────────────┬──────────────────────────────────────────────┘
               │
               │  Loop continues with slice-N+1
               ▼
              ...

What This Enables

Quality context packages. Because each slice has a narrow scope, the scout can deliver a complete, high-fidelity context package — every relevant type definition, every import, every interface — without hitting token limits. The primary model receives everything it needs and nothing it doesn't.

No additional clarifications or searches. The primary model can execute a slice immediately upon receiving the context package. There is no need to ask the user for clarification or perform its own file-by-file repository traversal — the scout has already done that work.

Iterative execution without context loss. The agent works through slices sequentially. For each slice, it gets a fresh, complete context package. This means the agent never accumulates stale context from previous slices, and never needs to hold the entire plan's context in memory at once.

Scalability to large plans. A plan that touches 50 files across 20 modules would overwhelm any single context window. But decomposed into 8 slices — each touching 5-8 files — every individual context package stays well within limits. Scouts can handle each slice independently, even in parallel if the slices are independent.

Slice Document Hints for Scouts

To help scouts work efficiently, each slice-*.md can include optional hints:

## Slice 3: Refactor AuthService token validation

**Likely files:**
- src/services/auth.ts (AuthService class, validateToken method)
- src/types/auth.types.ts (ValidationResult, TokenRefreshStrategy)
- src/middleware/auth.middleware.ts (where validateToken is called)

**Context needs:**
- Full type definitions for ValidationResult and TokenRefreshStrategy
- Constructor and DI dependencies of AuthService
- All call sites of validateToken in middleware

**Steps:**
- [ ] Extract token validation logic into a separate TokenValidator class
- [ ] Update AuthService to delegate to TokenValidator
- [ ] Update middleware imports

**Acceptance criteria:**
- All existing tests pass
- No changes to public API signatures

The scout reads this slice document and knows exactly where to look and what to anchor — without scanning the entire repository.

---

Summary

The current planning mode works but is opaque — the plan lives implicitly in the agent's context, invisible to the user. By materializing plans as persistent documents on disk, decomposed into slices, we make planning transparent, auditable, and trackable. This eliminates the implicit magic and gives both the agent and the user a reliable source of truth for complex tasks.

Combined with the Scout Models proposal (#11751), slices become the natural unit of work for iterative, context-aware execution. Scouts deliver focused context packages scoped to individual slices, the primary agent executes one slice at a time with full context and no guesswork, and the plan stays grounded in reality from start to finish — without ever requiring the entire repository to fit in a single context window.