{
  "markdown": "# Persistent Planning\n\n> Persistent markdown-based planning for Claude Code -- the context engineering pattern pioneered by Manus AI.\n\nA 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.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://github.com/TheGlitchKing/persistent-planning)\n\n> [!NOTE]\n> **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](https://github.com/TheGlitchKing/semantic-sidekick)'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`](./.documentation/architecture/lg-mode.md) for the layered model + [`.documentation/standards/atom-granularity.md`](./.documentation/standards/atom-granularity.md) for the inline-checkbox-vs-standalone-atom decision rule.\n>\n> 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).\n>\n> All lg-mode artifacts carry [HEWTD](https://github.com/TheGlitchKing/hit-em-with-the-docs) 2.2.0+ frontmatter (`tier: \"plan\"`).\n\n---\n\n## Why This Plugin?\n\nClaude Code (and most AI agents) suffer from:\n\n- **Volatile memory** -- in-memory task tracking disappears on context reset\n- **Goal drift** -- after 50+ tool calls, original goals get forgotten\n- **Hidden errors** -- failures aren't tracked, so the same mistakes repeat\n- **Context stuffing** -- everything crammed into context instead of stored on disk\n\nPersistent Planning solves all of these with the same approach that made [Manus AI worth $2 billion](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus): use the filesystem as external memory.\n\n## The 3-File Pattern\n\nFor every complex task, create three files:\n\n```\n.planning/[task-name]/task_plan.md   -> Track phases and progress\n.planning/[task-name]/notes.md       -> Store research and findings\n[deliverable].md                     -> Final output\n```\n\n### The Loop\n\n```\n1. Create task_plan.md with goal and phases\n2. Research -> save to notes.md -> update task_plan.md\n3. Read notes.md -> create deliverable -> update task_plan.md\n4. Deliver final output\n```\n\n**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.\n\n## Installation\n\n> **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](./CHANGELOG.md) for the full migration guide.\n\n### Option A: Claude Code Plugin Marketplace (Recommended)\n\n```\n/plugin marketplace add TheGlitchKing/persistent-planning\n/plugin install persistent-planning@persistent-planning-marketplace\n```\n\n### Option B: Project-level npm install\n\nPins 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.\n\n```bash\nnpm install --save-dev @theglitchking/persistent-planning\n```\n\n### Option C: Try it (no install)\n\n```bash\nnpx @theglitchking/persistent-planning status\n```\n\n## Update management\n\nEach 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:\n\n```bash\n# Slash commands\n/persistent-planning:policy auto    # auto-update on session start\n/persistent-planning:policy nudge   # one-liner nudge only (default)\n/persistent-planning:policy off     # silent\n\n# CLI equivalents\nnpx --no @theglitchking/persistent-planning policy auto\nnpx --no @theglitchking/persistent-planning status     # installed, latest, policy, hook state\nnpx --no @theglitchking/persistent-planning update     # runs npm update + relinks skills\nnpx --no @theglitchking/persistent-planning relink     # re-symlink skills only\n```\n\nPolicy resolution order: `PERSISTENT_PLANNING_UPDATE_POLICY` env var → `<project>/.claude/persistent-planning.json` → default `nudge`.\n\n## Usage\n\n### Quick Start\n\n```\n/start-planning \"Your task name here\"\n```\n\nThis creates:\n```\n.planning/\n└── your-task-name/\n    ├── task_plan.md    # Track phases and progress\n    └── notes.md        # Store research and findings\n```\n\n### Session Persistence\n\n**Session 1:**\n```\n/start-planning \"Complex feature\"\n[Work, update plans]\n```\n\n**Session 2 (next day):**\n```\nRead .planning/complex-feature/task_plan.md  <- Plans are still here\nRead .planning/complex-feature/notes.md      <- Notes are still here\n[Continue work]\n```\n\n### Multiple Concurrent Tasks\n\n```\n/start-planning \"Refactor authentication\"\n  -> Creates .planning/refactor-authentication/\n\n/start-planning \"Fix memory leak\"\n  -> Creates .planning/fix-memory-leak/\n```\n\nEach task gets its own directory. No conflicts, no overwrites.\n\n## Core Principles\n\n| Principle | Implementation |\n|-----------|----------------|\n| Filesystem as memory | Store in files, not context |\n| Attention manipulation | Re-read plan before decisions |\n| Error persistence | Log failures in plan file |\n| Goal tracking | Checkboxes show progress |\n| Append-only context | Never modify history |\n\n## When to Use\n\n**Use for:**\n- Multi-step tasks (3+ steps)\n- Research tasks\n- Building/creating projects\n- Tasks spanning many tool calls\n\n**Skip for:**\n- Simple questions\n- Single-file edits\n- Quick lookups\n\n## File Structure\n\n```\npersistent-planning/\n├── .claude-plugin/\n│   └── plugin.json          # Plugin manifest (marketplace loader)\n├── bin/\n│   └── persistent-planning.js  # CLI (update/policy/status/relink)\n├── commands/\n│   ├── start-planning.md    # /start-planning slash command\n│   ├── plan-status.md       # /plan-status\n│   ├── archive-plan.md      # /archive-plan\n│   ├── update.md            # /persistent-planning:update\n│   ├── policy.md            # /persistent-planning:policy\n│   ├── status.md            # /persistent-planning:status\n│   └── relink.md            # /persistent-planning:relink\n├── hooks/\n│   ├── hooks.json           # SessionStart hook manifest\n│   └── session-start.js     # Runtime-delegated hook\n├── scripts/\n│   ├── init-*.sh            # planning artifact creation (sm + lg)\n│   ├── plan-status.sh       # completion scan (single implementation)\n│   ├── archive-plan.sh      # retire a completed plan\n│   └── link-skills.js       # Postinstall (runtime-delegated)\n├── skills/\n│   └── persistent-planning/\n│       └── SKILL.md         # Core skill definition\n├── templates/lg/            # phase / task / atom / notes templates (lg mode)\n├── tests/\n│   └── run.sh               # bash smoke tests (npm test)\n├── .documentation/          # hewtd-managed docs — start at INDEX.md\n│   ├── architecture/        # lg-mode layer model, context-engineering rationale\n│   ├── standards/           # mandatory closing phases, atom granularity\n│   ├── reference/           # workspace.json schema\n│   ├── testing/             # test suite guide\n│   └── quickstart/          # worked examples\n├── README.md\n├── LICENSE\n└── CHANGELOG.md\n```\n\n## Status tracking and archive\n\nA 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.\n\n```\n/plan-status                  # what's in progress, blocked, or complete\n/archive-plan <slug>          # retire a completed plan\n/archive-plan --all-complete  # retire all of them\n```\n\nArchiving 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.\n\nThe 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/procedures/plan-completion-and-archive.md).\n\n## Documentation\n\nDocs are managed by [hit-em-with-the-docs](https://github.com/TheGlitchKing/hit-em-with-the-docs) and live in `.documentation/`, split by domain. Start at [`.documentation/INDEX.md`](./.documentation/INDEX.md).\n\n| Doc | What it covers |\n|---|---|\n| [Lg-Mode Layered Planning Guide](./.documentation/architecture/lg-mode.md) | phase / task / atom / notes layer model, scheduling, subagent contract |\n| [Manus Context Engineering Principles](./.documentation/architecture/context-engineering-principles.md) | the rationale the whole plugin is built on |\n| [Mandatory Closing Phases](./.documentation/standards/mandatory-closing-phases.md) | the two phases every plan must end with, and why |\n| [Atom Granularity](./.documentation/standards/atom-granularity.md) | inline checkbox vs. standalone atom file |\n| [workspace.json Reference](./.documentation/reference/workspace-json.md) | mode tracker schema |\n| [Plan Completion and Archive](./.documentation/procedures/plan-completion-and-archive.md) | how completion is detected and how plans are retired |\n| [Test Suite](./.documentation/testing/test-suite.md) | what `npm test` covers, how to add a case |\n| [Worked Examples](./.documentation/quickstart/examples.md) | end-to-end planning walkthroughs |\n\n`INDEX.md` and `REGISTRY.md` are generated — change the documents, then run `npx hewtd maintain --quick`.\n\n## Testing\n\n```bash\nnpm test          # bash smoke tests over the init scripts (tests/run.sh)\n```\n\n## Cleanup\n\nPrefer archiving — it keeps the record of what was done:\n\n```bash\n/archive-plan [task-name]\n```\n\nHard deletion still works, but throws that record away:\n\n```bash\nrm -rf .planning/[task-name]/   # one plan\nrm -rf .planning/               # everything, archive included\n```\n\n## Acknowledgments\n\n- **Manus AI** -- for pioneering context engineering patterns\n- **Ahmad Othman Ammar Adi** ([OthmanAdi](https://github.com/OthmanAdi)) -- for the original [planning-with-files](https://github.com/OthmanAdi/planning-with-files) skill\n- **Anthropic** -- for Claude Code and the skills framework\n\n## License\n\nMIT License -- see [LICENSE](./LICENSE)\n\n---\n\n**Author:** [TheGlitchKing](https://github.com/TheGlitchKing)\n",
  "bytes": 11182,
  "sha": "8432f304678d5d7f4efc0145d04b89be41cdd6813900e762c9f2d19259b09257",
  "repo_slug": "theglitchking/persistent-planning",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_theglitchking_persistent_planning_persis_51eca3c9/readme"
}