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

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 and docs/examples.md for more details.

overview.md Example

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

# 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 — using the file system as persistent working memory for AI agents.

License

MIT