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