# hplan

Adopt this skill: https://proskills.md/skills/other/noirewinter-hplan-skills-hplan-openclaw

Page: https://proskills.md/skills/other/noirewinter-hplan-skills-hplan-openclaw
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/hplan-openclaw/SKILL.md
size: 8107
upstream: https://github.com/noirewinter/hplan/blob/main/skills/hplan-openclaw/SKILL.md

````text
---
name: hplan
description: >
  Hierarchical persistent planning for complex multi-phase tasks. Use when the user
  asks to plan, break down, or execute a task involving multiple steps, deliverables,
  or coordinated work streams. Creates a .plan/ directory with overview.md (global
  summary) and per-phase directories (specs, checklists). Integrates with OpenClaw's
  memory system for cross-session continuity. Trigger phrases: plan, break down task,
  create plan, phased plan, multi-step task, start planning.
version: 1.0.0
metadata:
  openclaw:
    emoji: "📋"
    homepage: https://github.com/Noirewinter/hplan
    files:
      - "templates/*"
---

# 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

```
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:

```
.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:

| Layer | What it stores | Why |
|-------|---------------|-----|
| `.plan/` files | Full specs, checklists, detailed plans | Structured, complete, not subject to compaction |
| MEMORY.md | Task goal, current phase, key decisions | Survives session restarts, loaded automatically |
| Daily notes | Progress snapshots, phase completions | Searchable 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

```
1st failure: Diagnose and fix → record in errors.md
2nd failure: Try a different a
````

## File: README.md
upstream: https://github.com/noirewinter/hplan/blob/main/README.md

````text
# hplan

Hierarchical Persistent Planning for Claude Code

> Use the file system as AI's working memory, organized into a directory tree by phases, so Claude never loses sight of the goal or forgets progress during complex tasks.

## What Problem Does It Solve

Claude Code faces three challenges when executing complex multi-phase tasks:

**Goal drift** — After 50+ tool calls, the model gradually forgets the original task objective and starts drifting off course.

**Detailed spec loss** — Complex tasks require tracking which files to modify in each phase, how to modify them, how interfaces change, and how call chains need adjusting. This information is substantial, but the model's context window is limited.

## How hplan Works

Split the plan into a **concise summary + phase-organized detailed specs**, maintained automatically by 4 hooks:

```
.plan/
├── overview.md              ← Global summary (≤25 lines), injected by hook each time
├── decisions.md             ← Decision log
├── errors.md                ← Error log
└── phases/
    ├── phase1_xxx/
    │   ├── spec.md          ← Detailed spec (≤60 lines), auto-injected when phase is active
    │   ├── call_chain.md    ← Call chain change diagram (optional)
    │   └── checklist.md     ← Item-by-item checklist
    ├── phase2_xxx/
    │   └── ...
    └── ...
```

## Features

- **Persistent overview injection** — Automatically injects overview.md (≤25 lines) before every tool call, maintaining goal awareness
- **Auto context recovery** — When a user sends a message, if there's an active phase, automatically injects overview + current spec + checklist
- **Completion verification** — Stop hook checks checkbox status across all phases, prevents Claude from finishing if not all complete
- **Progressive disclosure** — Overview contains only the summary; detailed specs are split by phase; hooks only inject what's currently needed
- **Call chain documentation** — call_chain.md template supports recording before/after call relationship comparisons
- **Decision & error tracking** — Separate files for logging, avoiding clutter in the plan body

## Quick Install

```bash
git clone https://github.com/Noirewinter/hplan.git
cp -r hplan/skills/hplan ~/.claude/skills/
```

After installation, **restart Claude Code**. Trigger manually via `/hplan`, or Claude will use it automatically when you describe a complex task.

## Quick Start

Tell Claude a complex task:

```
Migrate the existing user auth module from Session-based to JWT + Refresh Token.
Need to create a token management module, modify login/register endpoints, update
middleware auth logic, modify the frontend axios interceptor, and run full end-to-end tests.
```

Claude will create the `.plan/` directory, then hooks take over automatically:

| Timing | Hook | Behavior |
|--------|------|----------|
| When user sends a message | UserPromptSubmit | If there's an active phase, inject overview + spec + checklist |
| Before all tool calls | PreToolUse | Inject overview.md (≤25 lines) |
| After Write/Edit | PostToolUse | Remind to update checklist and overview |
| When Claude wants to finish | Stop | Check if all phases are complete; block if not |

See [docs/workflow.md](docs/workflow.md) and [docs/examples.md](docs/examples.md) for more details.

## overview.md Example

overview.md is the file repeatedly injected by hooks and must stay concise (≤25 lines):

```markdown
# JWT Auth Migration
current_phase: phase2_backend

## Goal
Migrate user auth from Session-based to JWT + Refresh Token

## Phases
- [x] phase1_analyze: Audit existing auth flow → complete
- [ ] phase2_backend: JWT module + endpoint refactor → in_progress (3/6)
- [ ] phase3_frontend: Frontend auth adaptation → pending
- [ ] phase4_test: End-to-end testing → pending

## Blockers
None

## Last Decision
Store Refresh Token in Redis, 7-day expiry

## Last Error
None
```

Detailed file change lists, code changes, interface designs, call chains — all go in the corresponding phase's spec.md and call_chain.md, keeping overview.md uncluttered.

## Project Structure

```
hplan/
├── README.md
├── LICENSE
├── docs/
│   ├── workflow.md              # Detailed workflow documentation
│   └── examples.md              # Usage examples
└── skills/hplan/                # ← Copy to ~/.claude/skills/
    ├── SKILL.md                 # Skill definition (frontmatter hooks + instructions)
    ├── templates/               # Plan file templates
    │   ├── overview.md
    │   ├── spec.md
    │   ├── call_chain.md
    │   ├── checklist.md
    │   ├── decisions.md
    │   └── errors.md
    └── scripts/                 # Hook scripts + utilities
        ├── recover-context.sh   # UserPromptSubmit: inject plan context when active phase exists
        ├── inject-overview.sh   # PreToolUse: inject overview
        ├── post-edit-remind.sh  # PostToolUse: remind to update progress
        ├── check-complete.sh    # Stop: check all phase completion status
        ├── validate-plan.sh     # Validate overview.md and phases/ directory consistency
        ├── init-plan.sh         # Utility: initialize .plan/ directory
        └── advance-phase.sh     # Utility: advance to next phase
```

## When to Use

- Multi-phase system refactoring (auth migration, database switching, architecture upgrades, etc.)
- Feature development involving multi-file modifications
- Interface refactoring that requires tracking call chain changes
- Any complex task exceeding 5 tool calls

## When Not to Use

- Simple Q&A, single-file edits, quick lookups

## Acknowledgments

hplan's design is inspired by the Context Engineering philosophy of [Manus AI](https://manus.im) — using the file system as persistent working memory for AI agents.

## License

MIT
````
