hplan — Hierarchical Persistent Planning#

Use the file system as persistent working memory for complex multi-phase tasks. This skill solves two problems that arise in long task executions:

• Goal drift — the agent gradually forgets the original objective as the work progresses
• Spec loss — detailed requirements, deliverables, and dependencies vanish from context

Core Idea#

text

Context window = RAM (volatile, limited)
File system    = Disk (persistent, unlimited)
Memory system  = Long-term recall (cross-session, searchable)
→ Task structure and specs go to .plan/ (file system)
→ Key milestones and decisions go to memory (MEMORY.md / daily notes)
→ The overview stays concise for quick re-reading
→ All three layers work together to prevent drift and loss

.plan/ Directory Structure#

All plan files are stored in the .plan/ directory under the current workspace:

text

.plan/
├── overview.md              ← Global summary (≤25 lines, re-read frequently)
├── decisions.md             ← Decision log
├── errors.md                ← Error log
└── phases/
    ├── phase1_xxx/
    │   ├── spec.md          ← Detailed spec for this phase
    │   └── checklist.md     ← Item-by-item completion status
    ├── phase2_xxx/
    │   └── ...
    └── ...

Use the templates in templates/ as starting points for each file. Always use relative paths ( .plan/...) when reading and writing plan files.

Integration with OpenClaw Memory#

hplan uses the file system for structured task data (.plan/ directory) and OpenClaw's memory system for cross-session awareness. They serve different purposes:

LayerWhat it storesWhy.plan/ filesFull specs, checklists, detailed plansStructured, complete, not subject to compactionMEMORY.mdTask goal, current phase, key decisionsSurvives session restarts, loaded automaticallyDaily notesProgress snapshots, phase completionsSearchable history, compaction-safe via memory

When to write to memory#

• Plan creation: Save the task goal and phase list to memory ( "Active hplan: [goal], phases: [list], plan at .plan/")
• Phase completion: Save a progress snapshot ( "hplan progress: completed phase2_xxx, now on phase3_xxx, 2/4 phases done")
• Important decisions: When recording in decisions.md, also save a one-line summary to memory
• Session ending with incomplete work: Save current state ( "hplan paused: phase2_xxx in_progress (3/5), next step: [description]")

When to search memory#

• New session: Use memory_search("hplan") to quickly find if there's an active plan and what state it was in
• Resuming after interruption: Search for the latest progress snapshot to orient quickly
• Cross-referencing past decisions: Search memory for decision context from earlier sessions

Mandatory Behaviors#

Since this environment does not have automatic hook injection, you must follow these behaviors manually to maintain plan awareness:

1. Check .plan/ before any action#

This is the first thing to do in every conversation, before any file writes.

Check if .plan/overview.md already exists:

• Exists with incomplete phases: Show the user the current goal and progress, then ask: "There is an unfinished plan. Would you like to continue it, or discard it and start a new plan?" Wait for the user's answer before doing anything else.
• Exists with all phases complete: Silently delete the entire .plan/ directory and proceed normally.
• Does not exist: Proceed normally.

Never overwrite or modify an existing .plan/ without checking its status first.

2. Re-read overview.md frequently#

Before every significant action (producing deliverables, making decisions, starting a new step), re-read .plan/overview.md to stay aligned with the goal and current phase. This is the most important behavior — it prevents goal drift.

3. Re-read the current phase spec before working#

When starting work on any phase, always read the full spec.md and checklist.md for that phase first. Do not skip this step.

4. Update progress after each subtask#

After completing a subtask, immediately update:

• The phase's checklist.md ( [ ] → [x])
• The progress count in overview.md (e.g., in_progress (3/6))

5. Context recovery on new conversations#

When a user says "continue" or references an existing plan:

1. First, use memory_search("hplan") to find the latest plan state
2. Then check if .plan/overview.md exists and read it
3. Read the current phase's spec.md and checklist.md
4. Confirm the current state with the user before proceeding

6. Save progress before session ends#

When the conversation is ending with incomplete phases:

• Save the current state to memory: goal, current phase, progress count, and next action
• This ensures the next session can pick up quickly even before reading .plan/ files

7. Check completion before finishing#

Before ending your response on a planning task, verify whether all phases in overview.md are marked [x]. If incomplete phases remain, continue working or inform the user about remaining tasks. The user can exit the plan at any time by deleting the .plan/ directory.

Workflow#

Step 1: Create the Plan#

After receiving a complex task:

1. Check .plan/ status as described in Mandatory Behavior #1
2. Create the .plan/ directory structure
3. Write overview.md using the template (≤25 lines)
4. Create phase directories with spec.md (≤60 lines each) and checklist.md
5. Create decisions.md and errors.md
6. Save the task goal and phase list to memory for cross-session recall

Step 2: User Confirmation (cannot be skipped)#

Present the plan to the user and wait for explicit confirmation before executing.

What to show:

• The full overview.md content (goal and phase breakdown)
• A summary of each phase's spec.md (key deliverables and scope)
• Total number of phases

What to ask:

• Is the phase breakdown reasonable? Need to add, remove, or split phases?
• Is the scope for each phase correct? Anything missing?
• Ready to start execution?

Iterating on the plan:

• If the user suggests changes, update the plan files accordingly
• Present the updated plan and ask for confirmation again
• Repeat until the user explicitly agrees
• Keep overview.md and phase directories in sync during any modifications: adding a phase means both an overview entry AND a new directory; removing a phase means both are deleted

Only proceed to execution after the user explicitly confirms.

Step 3: Execute Phase by Phase#

1. Read the current phase's spec.md and checklist.md in full
2. Work through checklist items one by one
3. Update checklist.md after each completed item
4. When a phase is complete:
   • Update overview.md and move to the next phase
   • Save a progress snapshot to memory

Step 4: Phase Switching#

When moving to the next phase:

1. Mark the completed phase as [x] ... → complete in overview.md
2. Update current_phase to the next phase ID
3. Read the new phase's spec.md and checklist.md before starting work
4. Save the phase transition to memory

Step 5: Error Handling#

text

1st failure: Diagnose and fix → record in errors.md
2nd failure: Try a different approach → record in errors.md
3rd failure: Re-examine assumptions → update spec.md
Still failing: Explain the situation to user, request guidance

Plan Lifecycle#

New conversation with existing .plan/#

When a new conversation starts, check if .plan/overview.md exists:

• Has incomplete phases: Ask the user whether to continue the existing plan or discard it and start fresh. Wait for the user's decision before proceeding.
• All phases complete: Delete the entire .plan/ directory automatically, then proceed with the new task.

After plan completion#

When all phases are marked [x]:

1. Save a completion summary to memory: "hplan completed: [goal], all N phases done"
2. Inform the user that all tasks are complete

overview.md Format (≤25 lines)#

markdown

# [Project Name]
current_phase: phase2_xxx

## Goal
[One sentence describing the final objective]

## Phases
- [x] phase1_xxx: [Phase description] → complete
- [ ] phase2_xxx: [Phase description] → in_progress (2/4)
- [ ] phase3_xxx: [Phase description] → pending

## Blockers
None

## Last Decision
[One-sentence summary]

## Last Error
None

Never put detailed task descriptions, lengthy requirements, or step-by-step procedures in overview.md. Those belong in the phase directories.

Key Constraints#

• overview.md ≤ 25 lines (re-read it frequently to prevent goal drift)
• spec.md ≤ 60 lines per phase (split into multiple phases if longer)
• Always read phase spec before starting work on it
• Update checklist immediately after completing each item
• Record decisions in decisions.md, errors in errors.md
• Save key milestones to memory for cross-session continuity
• You should aim to execute all checklist items yourself rather than handing them off to the user

When to Use#

• Multi-phase tasks (3+ phases)
• Complex projects with multiple deliverables or work streams
• Tasks requiring coordination across many steps or dependencies
• Long-running projects spanning multiple sessions

When NOT to Use#

• Simple questions or short tasks
• Single-step work that needs no tracking