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 docs/lg-mode.md for the layered model + docs/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