@theglitchking/persistent-planning 1.0.0

package/docs/examples.md

@@ -0,0 +1,221 @@
+# Examples: Persistent Planning in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 0: Setup
+```bash
+/start-planning "Morning exercise benefits research"
+```
+
+### Loop 1: Create Plan
+```bash
+Write .planning/morning-exercise-benefits-research/task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read .planning/morning-exercise-benefits-research/task_plan.md  # Refresh goals
+WebSearch "morning exercise benefits"
+Write .planning/morning-exercise-benefits-research/notes.md     # Store findings
+Edit .planning/morning-exercise-benefits-research/task_plan.md  # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read .planning/morning-exercise-benefits-research/task_plan.md  # Refresh goals
+Read .planning/morning-exercise-benefits-research/notes.md      # Get findings
+Write morning_exercise_summary.md                                # Deliverable
+Edit .planning/morning-exercise-benefits-research/task_plan.md  # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read .planning/morning-exercise-benefits-research/task_plan.md  # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### .planning/fix-login-bug/task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report
+- [x] Phase 2: Locate relevant code
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  -> Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**.planning/add-dark-mode/task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system
+- [x] Phase 2: Design implementation approach
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**.planning/add-dark-mode/notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, don't hide it:
+
+### Wrong
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### Correct
+```
+Action: Read config.json
+Error: File not found
+
+# Update .planning/[task]/task_plan.md:
+## Errors Encountered
+- config.json not found -> Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+Always read your plan before major decisions:
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+-> Read .planning/[task]/task_plan.md   # Brings goals back into attention
+-> Now make the decision                 # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
+
+## Cleanup After Task Completion
+
+When your task is complete, clean up the planning files:
+
+```bash
+# Remove a single task
+rm -rf .planning/[task-name]/
+
+# Remove all planning files
+rm -rf .planning/
+```
+
+This removes planning files while keeping your deliverables in the project directory.

package/docs/reference.md

@@ -0,0 +1,110 @@
+# Reference: Manus Context Engineering Principles
+
+Based on the context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### 1. Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**Problem:** Context windows have limits. Stuffing everything in context degrades performance and increases costs.
+
+**Solution:** Treat the filesystem as unlimited memory:
+- Store large content in files
+- Keep only paths in context
+- Agent can "look up" information when needed
+- Compression must be reversible
+
+### 2. Attention Manipulation Through Repetition
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Keep a `task_plan.md` file that gets re-read throughout execution:
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION]
+```
+
+By reading the plan file before each decision, goals appear in the attention window.
+
+### 3. Keep Failure Traces
+
+> "Error recovery is one of the clearest signals of true agentic behavior."
+
+**Problem:** Instinct says hide errors, retry silently. This wastes tokens and loses learning.
+
+**Solution:** Keep failed actions in the plan file:
+```markdown
+## Errors Encountered
+- [2025-01-03] FileNotFoundError: config.json not found -> Created default config
+- [2025-01-03] API timeout -> Retried with exponential backoff, succeeded
+```
+
+The model updates its internal understanding when seeing failures.
+
+### 4. Avoid Few-Shot Overfitting
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+### 5. Stable Prefixes for Cache Optimization
+
+**Problem:** Agents are input-heavy (100:1 ratio). Every token costs money.
+
+**Solution:** Structure for cache hits:
+- Put static content first
+- Append-only context (never modify history)
+- Consistent serialization
+
+### 6. Append-Only Context
+
+**Problem:** Modifying previous messages invalidates KV-cache.
+
+**Solution:** Never modify previous messages. Always append new information.
+
+## The Agent Loop
+
+Manus operates in a continuous loop:
+
+```
+1. Analyze -> 2. Think -> 3. Select Tool -> 4. Execute -> 5. Observe -> 6. Iterate -> 7. Deliver
+```
+
+### File Operations in the Loop
+
+| Operation | When to Use |
+|-----------|-------------|
+| `write` | New files or complete rewrites |
+| `append` | Adding sections incrementally |
+| `edit` | Updating specific parts (checkboxes, status) |
+| `read` | Reviewing before decisions |
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+
+## Key Quotes
+
+> "If the model improvement is the rising tide, we want Manus to be the boat, not the piling stuck on the seafloor."
+
+> "For complex tasks, I save notes, code, and findings to files so I can reference them as I work."
+
+> "I used file.edit to update checkboxes in my plan as I progressed, rather than rewriting the whole file."
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@theglitchking/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",
+  "type": "commonjs",
+  "bin": {
+    "persistent-planning": "./bin/persistent-planning.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "scripts/",
+    "docs/",
+    ".claude/",
+    ".claude-plugin/",
+    "postinstall.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "planning",
+    "persistent",
+    "markdown",
+    "context-engineering",
+    "task-tracking",
+    "working-memory",
+    "goal-tracking",
+    "manus",
+    "plugin"
+  ],
+  "author": {
+    "name": "TheGlitchKing",
+    "email": "theglitchking@users.noreply.github.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheGlitchKing/persistent-planning.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TheGlitchKing/persistent-planning/issues"
+  },
+  "homepage": "https://github.com/TheGlitchKing/persistent-planning#readme"
+}

package/postinstall.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m'
+};
+
+console.log(`
+${colors.cyan}persistent-planning installed successfully!${colors.reset}
+
+${colors.green}+${colors.reset} Package installed: ${colors.blue}@theglitchking/persistent-planning${colors.reset}
+
+${colors.yellow}Next Steps:${colors.reset}
+
+  1. Run the installer to set up the plugin:
+     ${colors.cyan}persistent-planning install --scope user${colors.reset}
+
+     ${colors.blue}Scopes:${colors.reset}
+       user    - Install globally (~/.claude/) for all projects
+       project - Install locally (./.claude/) for this project only
+
+  2. Check installation status:
+     ${colors.cyan}persistent-planning status${colors.reset}
+
+  3. After installation, use this Claude Code command:
+     ${colors.cyan}/start-planning "Your task name"${colors.reset}
+
+${colors.yellow}Documentation:${colors.reset}
+  ${colors.blue}https://github.com/TheGlitchKing/persistent-planning${colors.reset}
+
+`);

package/scripts/init-planning.sh

@@ -0,0 +1,233 @@
+#!/bin/bash
+
+###############################################################################
+# init-planning.sh - Persistent Planning Directory Setup
+#
+# Part of the persistent-planning plugin by TheGlitchKing
+# https://github.com/TheGlitchKing/persistent-planning
+#
+# Usage:
+#   bash scripts/init-planning.sh [task-name]
+#   bash scripts/init-planning.sh "Refactor database layer"
+#
+# What it does:
+#   1. Creates .planning/[task-slug]/ directory (separate per task)
+#   2. Creates task_plan.md with templates
+#   3. Creates notes.md with templates
+#   4. Adds .planning/ to .gitignore (optional)
+#   5. Confirms creation and provides next steps
+#
+# Multiple tasks example:
+#   /start-planning "Refactor auth"      -> .planning/refactor-auth/
+#   /start-planning "Debug memory leak"  -> .planning/debug-memory-leak/
+#   Both plans coexist without conflicts!
+###############################################################################
+
+set -e
+
+# Validate that task name was provided
+if [ -z "$1" ]; then
+    echo "Error: Task name required"
+    echo ""
+    echo "Usage: bash scripts/init-planning.sh \"Your Task Name\""
+    echo ""
+    echo "Examples:"
+    echo "  bash scripts/init-planning.sh \"Refactor authentication\""
+    echo "  bash scripts/init-planning.sh \"Debug API performance\""
+    exit 1
+fi
+
+TASK_NAME="$1"
+
+# Convert task name to slug
+# "Refactor Authentication" -> "refactor-authentication"
+task_name_to_slug() {
+    local name="$1"
+    name=$(echo "$name" | tr '[:upper:]' '[:lower:]')
+    name=$(echo "$name" | sed 's/[[:space:]_]\+/-/g')
+    name=$(echo "$name" | sed 's/[^a-z0-9-]//g')
+    name=$(echo "$name" | sed 's/^-\+\|-\+$//g')
+    name=$(echo "$name" | sed 's/-\+/-/g')
+    echo "$name"
+}
+
+TASK_SLUG=$(task_name_to_slug "$TASK_NAME")
+
+# Validate slug
+if [ -z "$TASK_SLUG" ]; then
+    echo "Error: Task name must contain at least one alphanumeric character"
+    echo "Provided: $TASK_NAME"
+    exit 1
+fi
+
+# Determine project root
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLANNING_DIR="${PROJECT_ROOT}/.planning"
+TASK_DIR="${PLANNING_DIR}/${TASK_SLUG}"
+
+# Color codes
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${BLUE}Initializing Planning Structure${NC}"
+echo ""
+
+# Step 1: Create .planning directory
+if [ ! -d "$PLANNING_DIR" ]; then
+    mkdir -p "$PLANNING_DIR"
+    echo -e "${GREEN}+${NC} Created .planning/ directory"
+else
+    echo -e "${YELLOW}*${NC} .planning/ directory exists"
+fi
+
+# Step 2: Create task directory
+if [ ! -d "$TASK_DIR" ]; then
+    mkdir -p "$TASK_DIR"
+    echo -e "${GREEN}+${NC} Created task directory: ${CYAN}.planning/${TASK_SLUG}/${NC}"
+else
+    echo -e "${YELLOW}*${NC} Task directory already exists: ${CYAN}.planning/${TASK_SLUG}/${NC}"
+fi
+
+# Step 3: Create task_plan.md
+TASK_PLAN_FILE="${TASK_DIR}/task_plan.md"
+if [ ! -f "$TASK_PLAN_FILE" ]; then
+    cat > "$TASK_PLAN_FILE" << 'EOF'
+# Task Plan: TASK_NAME_PLACEHOLDER
+
+## Goal
+[One sentence describing the end state]
+
+## Phases
+- [ ] Phase 1: Plan and setup
+- [ ] Phase 2: Research/gather information
+- [ ] Phase 3: Execute/build
+- [ ] Phase 4: Review and deliver
+
+## Key Questions
+1. [Question to answer]
+2. [Question to answer]
+
+## Decisions Made
+- [Decision]: [Rationale]
+
+## Errors Encountered
+- [Error]: [Resolution]
+
+## Status
+**Currently in Phase 1** - Setting up planning structure
+
+---
+
+## Notes
+- This file persists across sessions
+- Update status after each phase
+- Mark completed phases with [x]
+- Save research to notes.md instead of stuffing context
+EOF
+
+    sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$TASK_PLAN_FILE"
+    echo -e "${GREEN}+${NC} Created task_plan.md"
+else
+    echo -e "${YELLOW}*${NC} task_plan.md already exists (not overwritten)"
+fi
+
+# Step 4: Create notes.md
+NOTES_FILE="${TASK_DIR}/notes.md"
+if [ ! -f "$NOTES_FILE" ]; then
+    cat > "$NOTES_FILE" << 'EOF'
+# Notes: TASK_NAME_PLACEHOLDER
+
+## Key Findings
+- [Finding 1]
+- [Finding 2]
+
+## Research Sources
+- [Source 1]: [URL or reference]
+- [Source 2]: [URL or reference]
+
+## Synthesized Findings
+
+### [Category/Topic 1]
+- [Finding]
+- [Finding]
+
+### [Category/Topic 2]
+- [Finding]
+- [Finding]
+
+## Decisions Made
+- [Decision]: [Rationale]
+- [Decision]: [Rationale]
+
+## Errors & Solutions
+- [Error]: [Resolution]
+- [Error]: [Resolution]
+
+---
+
+## Append-Only Log
+Store findings here as you discover them. This builds a searchable history.
+
+### [Date/Time]
+- [What I found/did]
+EOF
+
+    sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$NOTES_FILE"
+    echo -e "${GREEN}+${NC} Created notes.md"
+else
+    echo -e "${YELLOW}*${NC} notes.md already exists (not overwritten)"
+fi
+
+# Step 5: Update .gitignore
+if [ -f "${PROJECT_ROOT}/.gitignore" ]; then
+    if ! grep -q "^\.planning/" "${PROJECT_ROOT}/.gitignore"; then
+        echo ".planning/" >> "${PROJECT_ROOT}/.gitignore"
+        echo -e "${GREEN}+${NC} Added .planning/ to .gitignore"
+    else
+        echo -e "${YELLOW}*${NC} .planning/ already in .gitignore"
+    fi
+else
+    echo -e "${YELLOW}*${NC} No .gitignore found (not added)"
+fi
+
+# Step 6: List other active tasks
+OTHER_TASKS=$(find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" 2>/dev/null | wc -l)
+if [ "$OTHER_TASKS" -gt 0 ]; then
+    echo ""
+    echo -e "${CYAN}Other active tasks:${NC}"
+    find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" | sort | while read dir; do
+        task_slug=$(basename "$dir")
+        echo "   .planning/${task_slug}/"
+    done
+fi
+
+# Step 7: Confirmation
+echo ""
+echo -e "${GREEN}=====================================${NC}"
+echo -e "${GREEN}Task Plan Ready${NC}"
+echo -e "${GREEN}=====================================${NC}"
+echo ""
+
+echo -e "${BLUE}Task:${NC} ${TASK_NAME}"
+echo -e "${BLUE}Location:${NC} .planning/${TASK_SLUG}/"
+echo ""
+
+echo -e "${BLUE}Files:${NC}"
+echo "  task_plan.md   (your task plan)"
+echo "  notes.md       (research & findings)"
+echo ""
+
+echo -e "${BLUE}Next steps:${NC}"
+echo "  1. Edit .planning/${TASK_SLUG}/task_plan.md to define your phases"
+echo "  2. As you work, update the Status section"
+echo "  3. Save findings to .planning/${TASK_SLUG}/notes.md"
+echo "  4. Re-read task_plan.md before major decisions"
+echo ""
+
+echo -e "${BLUE}Cleanup:${NC}"
+echo "  rm -rf .planning/${TASK_SLUG}/  # Remove this task"
+echo "  rm -rf .planning/               # Remove all tasks"
+echo ""