β³ This skill is pending AI review.
Scores will appear once the review pipeline completes.
hplan
>
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
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
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/hplan-openclaw/SKILL.md7.9 KBupstream β
--- 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 aREADME.mdupstream β
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/noirewinter-hplan-skills-hplan-openclaw.md