@theglitchking/persistent-planning 1.0.0

package/.claude/commands/start-planning.md

@@ -0,0 +1,65 @@
+---
+name: start-planning
+description: "Initialize persistent planning structure for a task. Creates .planning/[task-slug]/ with task_plan.md and notes.md for on-disk working memory that persists across sessions."
+---
+
+# /start-planning
+
+Initialize the persistent planning structure for a task.
+
+---
+
+## Usage
+
+```
+/start-planning "Your task name here"
+```
+
+## Examples
+
+```
+/start-planning "Refactor authentication system"
+/start-planning "Build REST API with JWT"
+/start-planning "Fix memory leak in worker process"
+```
+
+---
+
+## What To Do
+
+When the user runs `/start-planning "Task Name"`:
+
+1. Run the init script:
+```bash
+bash "$(dirname "$(readlink -f "$0")")/../scripts/init-planning.sh" "Task Name"
+```
+
+If the script is not found at that path, try these fallbacks in order:
+```bash
+bash scripts/init-planning.sh "Task Name"
+bash ~/.claude/skills/persistent-planning/scripts/init-planning.sh "Task Name"
+```
+
+2. After the script completes, remind the user:
+   - Edit `.planning/[task-slug]/task_plan.md` to define phases
+   - Update the Status section as they work
+   - Save findings to `.planning/[task-slug]/notes.md`
+   - Re-read `task_plan.md` before major decisions
+
+---
+
+## What It Creates
+
+```
+.planning/
+└── [task-slug]/
+    ├── task_plan.md    # Track phases and progress
+    └── notes.md        # Store research and findings
+```
+
+## Task Slug Conversion
+
+Task names are converted to URL-friendly slugs:
+- "Refactor Authentication" -> `refactor-authentication`
+- "Build REST API" -> `build-rest-api`
+- "Fix Bug #123" -> `fix-bug-123`

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bash:*)",
+      "Bash(echo:*)",
+      "Bash(./install.sh:*)",
+      "Bash(/mnt/e/docker-containers/persistent-planning/uninstall.sh:*)",
+      "Bash(chmod:*)",
+      "Bash(node:*)",
+      "Bash(python3:*)"
+    ]
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "persistent-planning",
+  "version": "1.0.0",
+  "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
+  "author": {
+    "name": "TheGlitchKing"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/TheGlitchKing/persistent-planning",
+  "repository": "https://github.com/TheGlitchKing/persistent-planning.git",
+  "keywords": [
+    "planning",
+    "persistent",
+    "markdown",
+    "context-engineering",
+    "task-tracking",
+    "working-memory",
+    "goal-tracking",
+    "manus"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-02-12
+
+### Added
+- Core skill definition (`skills/SKILL.md`) with persistent markdown-based planning
+- `/start-planning` slash command for one-command setup
+- `init-planning.sh` script for automated `.planning/` directory creation
+- Task-specific subdirectories (`.planning/[task-slug]/`)
+- `task_plan.md` and `notes.md` templates
+- Multiple concurrent task support
+- Reference documentation on Manus context engineering principles
+- Worked examples for research, bug fix, and feature development workflows
+- `install.sh` installer with user/project scope support
+- `uninstall.sh` for clean removal
+- Plugin manifest files for marketplace compatibility
+
+### Based On
+- Context engineering principles from [Manus AI](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
+- Original [planning-with-files](https://github.com/OthmanAdi/planning-with-files) skill by Ahmad Othman Ammar Adi

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheGlitchKing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# 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.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://github.com/TheGlitchKing/persistent-planning)
+
+---
+
+## 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](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus): 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
+
+### Option 1: NPM (Recommended)
+
+```bash
+# Install globally
+npm install -g @theglitchking/persistent-planning
+persistent-planning install --scope user
+
+# Or via npx (no global install)
+npx @theglitchking/persistent-planning install --scope user
+```
+
+### Option 2: Installer Script
+
+```bash
+git clone https://github.com/TheGlitchKing/persistent-planning.git
+cd persistent-planning
+./install.sh --scope user       # Available in all projects
+# OR
+./install.sh --scope project    # Current project only
+```
+
+### Option 3: Claude Marketplace
+
+```
+/plugin install TheGlitchKing/persistent-planning
+```
+
+### Option 4: Manual Installation
+
+```bash
+mkdir -p ~/.claude/skills
+cp -r persistent-planning/skills/SKILL.md ~/.claude/skills/persistent-planning/SKILL.md
+cp -r persistent-planning/scripts ~/.claude/skills/persistent-planning/scripts
+cp -r persistent-planning/docs ~/.claude/skills/persistent-planning/docs
+cp persistent-planning/.claude/commands/start-planning.md ~/.claude/commands/start-planning.md
+```
+
+## 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
+├── .claude/
+│   └── commands/
+│       └── start-planning.md    # /start-planning command
+├── skills/
+│   └── SKILL.md             # Core skill definition
+├── scripts/
+│   └── init-planning.sh     # Automated setup script
+├── docs/
+│   ├── reference.md         # Manus context engineering principles
+│   └── examples.md          # Worked examples
+├── install.sh               # Plugin installer
+├── uninstall.sh             # Plugin uninstaller
+├── plugin.json              # Root plugin metadata
+├── README.md                # This file
+├── LICENSE                  # MIT license
+└── CHANGELOG.md             # Version history
+```
+
+## Cleanup
+
+```bash
+# Remove a single task's planning files
+rm -rf .planning/[task-name]/
+
+# Remove all planning files
+rm -rf .planning/
+```
+
+## Acknowledgments
+
+- **Manus AI** -- for pioneering context engineering patterns
+- **Ahmad Othman Ammar Adi** ([OthmanAdi](https://github.com/OthmanAdi)) -- for the original [planning-with-files](https://github.com/OthmanAdi/planning-with-files) skill
+- **Anthropic** -- for Claude Code and the skills framework
+
+## License
+
+MIT License -- see [LICENSE](./LICENSE)
+
+---
+
+**Author:** [TheGlitchKing](https://github.com/TheGlitchKing)

package/bin/persistent-planning.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const PLUGIN_ROOT = path.join(__dirname, '..');
+
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+};
+
+function showHelp() {
+  console.log(`
+${colors.blue}persistent-planning CLI${colors.reset}
+
+${colors.green}Usage:${colors.reset}
+  persistent-planning install [--scope user|project]
+  persistent-planning uninstall [--scope user|project]
+  persistent-planning status
+  persistent-planning help
+
+${colors.green}Commands:${colors.reset}
+  install     Install persistent-planning skill and /start-planning command
+  uninstall   Remove persistent-planning from Claude Code
+  status      Show installation status
+  help        Show this help message
+
+${colors.green}Install Options:${colors.reset}
+  --scope {user|project}    Install scope (default: user)
+                            user     - Install globally (~/.claude/)
+                            project  - Install in current project (.claude/)
+
+${colors.green}Examples:${colors.reset}
+  persistent-planning install --scope user
+  persistent-planning install --scope project
+  persistent-planning uninstall --scope user
+  persistent-planning status
+
+${colors.green}After Installation:${colors.reset}
+  Run this command in Claude Code:
+    /start-planning "Your task name"
+  `);
+}
+
+function copyRecursive(src, dest) {
+  const stats = fs.statSync(src);
+  if (stats.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach(file => {
+      copyRecursive(path.join(src, file), path.join(dest, file));
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function getInstallDir(scope) {
+  return scope === 'user'
+    ? path.join(process.env.HOME || process.env.USERPROFILE, '.claude')
+    : '.claude';
+}
+
+function checkInstallation(scope) {
+  const installDir = getInstallDir(scope);
+  const skillPath = path.join(installDir, 'skills', 'persistent-planning', 'SKILL.md');
+  const commandPath = path.join(installDir, 'commands', 'start-planning.md');
+  return {
+    skill: fs.existsSync(skillPath),
+    command: fs.existsSync(commandPath)
+  };
+}
+
+function showStatus() {
+  console.log(`\n${colors.blue}persistent-planning Installation Status${colors.reset}\n`);
+
+  const userInstall = checkInstallation('user');
+  const projectInstall = checkInstallation('project');
+
+  console.log(`User Scope (~/.claude/):`);
+  console.log(`  Skill:    ${userInstall.skill ? colors.green + 'Installed' : colors.yellow + 'Not installed'}${colors.reset}`);
+  console.log(`  Command:  ${userInstall.command ? colors.green + 'Installed' : colors.yellow + 'Not installed'}${colors.reset}`);
+
+  console.log(`\nProject Scope (./.claude/):`);
+  console.log(`  Skill:    ${projectInstall.skill ? colors.green + 'Installed' : colors.yellow + 'Not installed'}${colors.reset}`);
+  console.log(`  Command:  ${projectInstall.command ? colors.green + 'Installed' : colors.yellow + 'Not installed'}${colors.reset}`);
+
+  if (!userInstall.skill && !projectInstall.skill) {
+    console.log(`\n${colors.yellow}Run: persistent-planning install${colors.reset}`);
+  }
+  console.log();
+}
+
+function runInstall(args) {
+  const scope = args.includes('--scope') ? args[args.indexOf('--scope') + 1] : 'user';
+  const installDir = getInstallDir(scope);
+
+  console.log(`${colors.blue}Installing persistent-planning...${colors.reset}`);
+  console.log(`  Scope: ${scope} (${installDir})\n`);
+
+  try {
+    // Create directories
+    const skillDir = path.join(installDir, 'skills', 'persistent-planning');
+    const scriptsDir = path.join(skillDir, 'scripts');
+    const docsDir = path.join(skillDir, 'docs');
+    const commandsDir = path.join(installDir, 'commands');
+
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.mkdirSync(commandsDir, { recursive: true });
+
+    // Copy skill
+    fs.copyFileSync(
+      path.join(PLUGIN_ROOT, 'skills', 'SKILL.md'),
+      path.join(skillDir, 'SKILL.md')
+    );
+    console.log(`${colors.green}+${colors.reset} Installed SKILL.md`);
+
+    // Copy init script
+    const initScript = path.join(scriptsDir, 'init-planning.sh');
+    fs.copyFileSync(
+      path.join(PLUGIN_ROOT, 'scripts', 'init-planning.sh'),
+      initScript
+    );
+    fs.chmodSync(initScript, 0o755);
+    console.log(`${colors.green}+${colors.reset} Installed init-planning.sh`);
+
+    // Copy docs
+    fs.copyFileSync(
+      path.join(PLUGIN_ROOT, 'docs', 'reference.md'),
+      path.join(docsDir, 'reference.md')
+    );
+    fs.copyFileSync(
+      path.join(PLUGIN_ROOT, 'docs', 'examples.md'),
+      path.join(docsDir, 'examples.md')
+    );
+    console.log(`${colors.green}+${colors.reset} Installed reference docs`);
+
+    // Copy command
+    fs.copyFileSync(
+      path.join(PLUGIN_ROOT, '.claude', 'commands', 'start-planning.md'),
+      path.join(commandsDir, 'start-planning.md')
+    );
+    console.log(`${colors.green}+${colors.reset} Installed /start-planning command`);
+
+    // Update .gitignore if project scope
+    if (scope === 'project') {
+      const gitignorePath = '.gitignore';
+      if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, 'utf8');
+        if (!content.includes('.claude/')) {
+          fs.appendFileSync(gitignorePath, '\n.claude/\n');
+          console.log(`${colors.green}+${colors.reset} Updated .gitignore`);
+        }
+      } else {
+        fs.writeFileSync(gitignorePath, '.claude/\n');
+        console.log(`${colors.green}+${colors.reset} Created .gitignore`);
+      }
+    }
+
+    console.log(`\n${colors.green}Installation Complete!${colors.reset}\n`);
+    console.log(`${colors.yellow}Usage:${colors.reset}`);
+    console.log(`  In Claude Code, run: ${colors.cyan}/start-planning "Your task name"${colors.reset}\n`);
+    console.log(`${colors.yellow}Uninstall:${colors.reset}`);
+    console.log(`  ${colors.cyan}persistent-planning uninstall --scope ${scope}${colors.reset}\n`);
+
+  } catch (error) {
+    console.error(`${colors.red}Installation failed: ${error.message}${colors.reset}`);
+    process.exit(1);
+  }
+}
+
+function runUninstall(args) {
+  const scope = args.includes('--scope') ? args[args.indexOf('--scope') + 1] : 'user';
+  const installDir = getInstallDir(scope);
+
+  console.log(`${colors.blue}Uninstalling persistent-planning...${colors.reset}`);
+  console.log(`  Scope: ${scope} (${installDir})\n`);
+
+  let removed = 0;
+
+  try {
+    const skillDir = path.join(installDir, 'skills', 'persistent-planning');
+    if (fs.existsSync(skillDir)) {
+      fs.rmSync(skillDir, { recursive: true, force: true });
+      console.log(`${colors.green}+${colors.reset} Removed skill`);
+      removed++;
+    }
+
+    const commandFile = path.join(installDir, 'commands', 'start-planning.md');
+    if (fs.existsSync(commandFile)) {
+      fs.unlinkSync(commandFile);
+      console.log(`${colors.green}+${colors.reset} Removed /start-planning command`);
+      removed++;
+    }
+
+    if (removed === 0) {
+      console.log(`${colors.yellow}Nothing to remove. persistent-planning not found in ${installDir}/${colors.reset}`);
+    } else {
+      console.log(`\n${colors.green}Uninstall complete.${colors.reset}`);
+      console.log(`\nNote: .planning/ directories in your projects are not removed.`);
+      console.log(`To clean those up: rm -rf .planning/\n`);
+    }
+
+  } catch (error) {
+    console.error(`${colors.red}Uninstallation failed: ${error.message}${colors.reset}`);
+    process.exit(1);
+  }
+}
+
+// Main
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'install':
+    runInstall(args.slice(1));
+    break;
+  case 'uninstall':
+    runUninstall(args.slice(1));
+    break;
+  case 'status':
+    showStatus();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp();
+    break;
+  default:
+    console.error(`${colors.red}Unknown command: ${command}${colors.reset}`);
+    console.log(`Run 'persistent-planning help' for usage information`);
+    process.exit(1);
+}