persistent-planning

Persistent Planning

Persistent markdown-based planning for Claude Code -- the context engineering pattern pioneered by Manus AI.

A Claude Code plugin that uses on-disk markdown files as "working memory" for planning, progress tracking, and knowledge storage. Plans persist across sessions and support multiple concurrent tasks.

[!NOTE] New in 3.0.0 — sm/lg modes + layered planning. Solo work and quick spikes still get the original single-task flow (now called sm mode). Multi-week projects with multiple contributors get a new lg mode with layered phase / task / atom / notes artifacts that subagents can pick up via semantic-memory's MCP. Mode is auto-detected from 90-day git author count; sm preserved bit-for-bit from v2. See .documentation/architecture/lg-mode.md for the layered model + .documentation/standards/atom-granularity.md for the inline-checkbox-vs-standalone-atom decision rule.

Two new slash commands ship in 3.0: /start-task "Name" --parent <phase> and /start-atom "Name" --parent <task> (lg-mode only). /start-planning now dispatches to either flow based on detected mode (with --mode sm|lg override).

All lg-mode artifacts carry HEWTD 2.2.0+ frontmatter (tier: "plan").

---

Why This Plugin?

Claude Code (and most AI agents) suffer from:

• Volatile memory -- in-memory task tracking disappears on context reset
• Goal drift -- after 50+ tool calls, original goals get forgotten
• Hidden errors -- failures aren't tracked, so the same mistakes repeat
• Context stuffing -- everything crammed into context instead of stored on disk

Persistent Planning solves all of these with the same approach that made Manus AI worth $2 billion: use the filesystem as external memory.

The 3-File Pattern

For every complex task, create three files:

.planning/[task-name]/task_plan.md   -> Track phases and progress
.planning/[task-name]/notes.md       -> Store research and findings
[deliverable].md                     -> Final output

The Loop

1. Create task_plan.md with goal and phases
2. Research -> save to notes.md -> update task_plan.md
3. Read notes.md -> create deliverable -> update task_plan.md
4. Deliver final output

Key insight: By reading task_plan.md before each decision, goals stay in the attention window. This is how Manus handles ~50 tool calls without losing track.

Installation

v1 → v2 breaking change: the hand-rolled persistent-planning install --scope ... flow was removed. Skills and slash commands are now placed automatically — either by the Claude Code plugin marketplace, or by npm's postinstall symlinking. See CHANGELOG.md for the full migration guide.

Option A: Claude Code Plugin Marketplace (Recommended)

/plugin marketplace add TheGlitchKing/persistent-planning
/plugin install persistent-planning@persistent-planning-marketplace

Option B: Project-level npm install

Pins the exact version in package.json, visible to teammates, CI, and LLMs reading the repo. Postinstall symlinks skills/persistent-planning/ into <project>/.claude/skills/, writes a default .claude/persistent-planning.json (update policy nudge), and registers a SessionStart hook in .claude/settings.json if one is present. Dedup: if the plugin marketplace version is already enabled in ~/.claude/settings.json, the npm hook registration is skipped.

npm install --save-dev @theglitchking/persistent-planning

Option C: Try it (no install)

npx @theglitchking/persistent-planning status

Update management

Each install ships with an update policy. By default the plugin checks npm at session start and prints a one-liner when a newer version is available — no changes made. Opt into automatic updates or silence the check entirely:

# Slash commands
/persistent-planning:policy auto    # auto-update on session start
/persistent-planning:policy nudge   # one-liner nudge only (default)
/persistent-planning:policy off     # silent

# CLI equivalents
npx --no @theglitchking/persistent-planning policy auto
npx --no @theglitchking/persistent-planning status     # installed, latest, policy, hook state
npx --no @theglitchking/persistent-planning update     # runs npm update + relinks skills
npx --no @theglitchking/persistent-planning relink     # re-symlink skills only

Policy resolution order: PERSISTENT_PLANNING_UPDATE_POLICY env var → <project>/.claude/persistent-planning.json → default nudge.

Usage

Quick Start

/start-planning "Your task name here"

This creates:

.planning/
└── your-task-name/
    ├── task_plan.md    # Track phases and progress
    └── notes.md        # Store research and findings

Session Persistence

Session 1:

/start-planning "Complex feature"
[Work, update plans]

Session 2 (next day):

Read .planning/complex-feature/task_plan.md  <- Plans are still here
Read .planning/complex-feature/notes.md      <- Notes are still here
[Continue work]

Multiple Concurrent Tasks

/start-planning "Refactor authentication"
  -> Creates .planning/refactor-authentication/

/start-planning "Fix memory leak"
  -> Creates .planning/fix-memory-leak/

Each task gets its own directory. No conflicts, no overwrites.

Core Principles

Principle	Implementation
Filesystem as memory	Store in files, not context
Attention manipulation	Re-read plan before decisions
Error persistence	Log failures in plan file
Goal tracking	Checkboxes show progress
Append-only context	Never modify history

When to Use

Use for:

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating projects
• Tasks spanning many tool calls

Skip for:

• Simple questions
• Single-file edits
• Quick lookups

File Structure

persistent-planning/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (marketplace loader)
├── bin/
│   └── persistent-planning.js  # CLI (update/policy/status/relink)
├── commands/
│   ├── start-planning.md    # /start-planning slash command
│   ├── plan-status.md       # /plan-status
│   ├── archive-plan.md      # /archive-plan
│   ├── update.md            # /persistent-planning:update
│   ├── policy.md            # /persistent-planning:policy
│   ├── status.md            # /persistent-planning:status
│   └── relink.md            # /persistent-planning:relink
├── hooks/
│   ├── hooks.json           # SessionStart hook manifest
│   └── session-start.js     # Runtime-delegated hook
├── scripts/
│   ├── init-*.sh            # planning artifact creation (sm + lg)
│   ├── plan-status.sh       # completion scan (single implementation)
│   ├── archive-plan.sh      # retire a completed plan
│   └── link-skills.js       # Postinstall (runtime-delegated)
├── skills/
│   └── persistent-planning/
│       └── SKILL.md         # Core skill definition
├── templates/lg/            # phase / task / atom / notes templates (lg mode)
├── tests/
│   └── run.sh               # bash smoke tests (npm test)
├── .documentation/          # hewtd-managed docs — start at INDEX.md
│   ├── architecture/        # lg-mode layer model, context-engineering rationale
│   ├── standards/           # mandatory closing phases, atom granularity
│   ├── reference/           # workspace.json schema
│   ├── testing/             # test suite guide
│   └── quickstart/          # worked examples
├── README.md
├── LICENSE
└── CHANGELOG.md

Status tracking and archive

A plan is complete when every checkbox in it is checked (or its top-level artifact says status: done). Completion is derived from the artifacts, so it cannot drift from what the plan actually says — checking the last box is the signal.

/plan-status                  # what's in progress, blocked, or complete
/archive-plan <slug>          # retire a completed plan
/archive-plan --all-complete  # retire all of them

Archiving moves .planning/<slug>/ to the gitignored .planning/.archive/<slug>/ and stamps it status: archived + archived_on. Nothing is deleted — restore by moving the directory back out.

The SessionStart hook mentions complete-but-unarchived plans at the top of the next session, so a finished plan gets retired instead of rediscovered. Full protocol: Plan Completion and Archive.

Documentation

Docs are managed by hit-em-with-the-docs and live in .documentation/, split by domain. Start at .documentation/INDEX.md.

Doc	What it covers
Lg-Mode Layered Planning Guide	phase / task / atom / notes layer model, scheduling, subagent contract
Manus Context Engineering Principles	the rationale the whole plugin is built on
Mandatory Closing Phases	the two phases every plan must end with, and why
Atom Granularity	inline checkbox vs. standalone atom file
workspace.json Reference	mode tracker schema
Plan Completion and Archive	how completion is detected and how plans are retired
Test Suite	what npm test covers, how to add a case
Worked Examples	end-to-end planning walkthroughs

INDEX.md and REGISTRY.md are generated — change the documents, then run npx hewtd maintain --quick.

Testing

npm test          # bash smoke tests over the init scripts (tests/run.sh)

Cleanup

Prefer archiving — it keeps the record of what was done:

/archive-plan [task-name]

Hard deletion still works, but throws that record away:

rm -rf .planning/[task-name]/   # one plan
rm -rf .planning/               # everything, archive included

Acknowledgments

• Manus AI -- for pioneering context engineering patterns
• Ahmad Othman Ammar Adi (OthmanAdi) -- for the original planning-with-files skill
• Anthropic -- for Claude Code and the skills framework

License

MIT License -- see LICENSE

---

Author: TheGlitchKing