ollie/doc/PLANNING.md

Planning in Ollie

Design

Planning is executive functioning — breaking a goal into ordered steps before acting. It lives in the task server alongside task_complete, which closes the loop by marking steps done as work progresses.

Two tools handle the full planning lifecycle:

Tool	When to call
task_plan	Before beginning a multi-step task
task_complete	Immediately after each step finishes

Everything else — adding steps, editing descriptions, renaming the plan file — goes through the standard file_* tools. The task server handles creation and completion only.

task_plan

task_plan takes a goal and an ordered list of steps (each with an optional description and depends_on index list). It:

1. Topologically sorts the steps (blockers before dependents)
2. Writes a markdown checklist to the plan directory as YYYYMMDDTHHmmss_{uid}--{goal-slug}__todo.md
3. Returns the filename and step count

The returned filename is what the agent passes to task_complete and any file_* calls on the plan.

Plan lifecycle

task_plan  →  __todo.md created
file_edit (rename __todo → __wip)  →  work begins
task_complete (per step)  →  [ ] → [x], remaining steps returned
file_edit (rename __wip → __done)  →  goal realized

Renaming is intentional: __todo / __wip / __done is a visible filesystem-level state machine. Plans survive crashes and context compaction because they live on disk, not in the conversation.

Re-planning

If a step fails or new information changes the approach, call task_plan again with the revised goal and steps. Abandon the old plan file (rename it __abandoned or delete it) and proceed with the new one.

task_complete

task_complete takes the plan filename and a step title (substring, case-insensitive). It finds the first unchecked step whose title contains the substring, flips [ ] to [x], writes the file back, and returns the remaining unchecked step titles.

Returning the remaining steps serves two purposes: the agent always knows what's left without a separate file read, and the explicit list nudges continuation rather than premature termination.

task_complete errors if no matching unchecked step is found. This prevents silent skips — the agent must match a real step or handle the error explicitly.

Discipline

Call task_complete immediately after each step finishes, before starting the next. This keeps the plan file current throughout execution and ensures that if the session is interrupted, the state on disk reflects actual progress.

Memory

Memory is handled separately by the memory server (memory_remember / memory_recall). It is not part of the planning system. Memory persists facts across sessions; plans persist work-in-progress within a task.