@theglitchking/persistent-planning 1.0.0

package/skills/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: persistent-planning
+description: Transforms workflow to use persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.
+---
+
+# Persistent Planning
+
+Use persistent markdown files as your "working memory on disk" -- the context engineering pattern pioneered by Manus AI.
+
+---
+
+## Quick Start
+
+### Automatic Setup (Recommended)
+
+Start planning in one command:
+
+```
+/start-planning "Your task name here"
+```
+
+This automatically:
+- Creates `.planning/` directory
+- Creates `.planning/[task-slug]/task_plan.md` with templates
+- Creates `.planning/[task-slug]/notes.md` with templates
+- Files persist across ALL future sessions
+
+**Example:**
+```
+/start-planning "Refactor authentication system"
+```
+
+### Manual Setup
+
+If `/start-planning` isn't available:
+
+1. Create `.planning/[task-slug]/` directory
+2. Create `task_plan.md` with goal and phases
+3. Define phases with checkboxes
+4. Update after each phase -- mark `[x]` and change status
+5. Read before deciding -- refresh goals in attention window
+
+---
+
+## Persistence and Concurrent Tasks
+
+Unlike in-memory task tracking (which disappears between sessions), your plans **stay on disk** and **support multiple concurrent tasks**.
+
+### Persistence Across Sessions
+
+**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/
+
+Both plans coexist without overwriting each other.
+```
+
+Each task gets its own directory. No conflicts, no overwrites.
+
+## The 3-File Pattern (Per Task)
+
+For every task, files are created in a **task-specific directory**:
+
+| Location | Purpose | When to Update |
+|----------|---------|----------------|
+| `.planning/[task-name]/task_plan.md` | Track phases and progress | After each phase |
+| `.planning/[task-name]/notes.md` | Store findings and research | During research |
+| `[deliverable].md` | Final output (root directory) | At completion |
+
+**Example structure:**
+```
+.planning/
+├── refactor-auth/
+│   ├── task_plan.md
+│   └── notes.md
+├── fix-memory-leak/
+│   ├── task_plan.md
+│   └── notes.md
+└── performance-optimization/
+    ├── task_plan.md
+    └── notes.md
+```
+
+## Core Workflow
+
+```
+Loop 0: Run /start-planning "Task name" (creates task directory automatically)
+Loop 1: Define phases in .planning/[task-name]/task_plan.md
+Loop 2: Research -> save to .planning/[task-name]/notes.md -> update plan
+Loop 3: Read notes -> create deliverable -> update plan
+Loop 4: Deliver final output
+Loop 5: Next task? Run /start-planning again (no conflicts)
+```
+
+### The Loop in Detail
+
+**Before each major action:**
+```bash
+Read .planning/[task-name]/task_plan.md  # Refresh goals in attention window
+```
+
+**After each phase:**
+```bash
+Edit .planning/[task-name]/task_plan.md  # Mark [x], update status
+```
+
+**When storing information:**
+```bash
+Write .planning/[task-name]/notes.md     # Don't stuff context, store in file
+```
+
+### Managing Multiple Tasks
+
+**Task 1:**
+```bash
+Read .planning/refactor-auth/task_plan.md
+Edit .planning/refactor-auth/notes.md
+Edit .planning/refactor-auth/task_plan.md
+```
+
+**Task 2 (same session, no conflicts):**
+```bash
+Read .planning/fix-memory-leak/task_plan.md
+Edit .planning/fix-memory-leak/notes.md
+Edit .planning/fix-memory-leak/task_plan.md
+```
+
+Both tasks coexist independently. Switch between them as needed.
+
+## task_plan.md Template
+
+Create this file FIRST for any complex task:
+
+```markdown
+# Task Plan: [Brief Description]
+
+## 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 X** - [What I'm doing now]
+```
+
+## notes.md Template
+
+For research and findings:
+
+```markdown
+# Notes: [Topic]
+
+## Sources
+
+### Source 1: [Name]
+- URL: [link]
+- Key points:
+  - [Finding]
+  - [Finding]
+
+## Synthesized Findings
+
+### [Category]
+- [Finding]
+- [Finding]
+```
+
+## Critical Rules
+
+### 1. Always Create .planning/ Directory First
+Create the `.planning/` directory before starting any complex task. Then create `task_plan.md`. This is non-negotiable.
+
+### 2. Read Before Decide
+Before any major decision, read the plan file. This keeps goals in your attention window.
+
+### 3. Update After Act
+After completing any phase, immediately update the plan file:
+- Mark completed phases with `[x]`
+- Update the Status section
+- Log any errors encountered
+
+### 4. Store, Don't Stuff
+Large outputs go to files, not context. Keep only paths in working memory.
+
+### 5. Log All Errors
+Every error goes in the "Errors Encountered" section. This builds knowledge for future tasks.
+
+### 6. Easy Cleanup
+When a task is complete, delete the task directory:
+```bash
+rm -rf .planning/[task-name]/
+```
+
+Or clean up everything:
+```bash
+rm -rf .planning/
+```
+
+## When to Use This Pattern
+
+**Use 3-file pattern for:**
+- Multi-step tasks (3+ steps)
+- Research tasks
+- Building/creating something
+- Tasks spanning multiple tool calls
+- Anything requiring organization
+
+**Skip for:**
+- Simple questions
+- Single-file edits
+- Quick lookups
+
+## Anti-Patterns to Avoid
+
+| Don't | Do Instead |
+|-------|------------|
+| Use volatile task tracking for persistence | Use `/start-planning` for on-disk persistence |
+| Put planning files in root | Use `.planning/[task-name]/` subdirectories |
+| State goals once and forget | Re-read plan before each decision |
+| Hide errors and retry | Log errors to plan file |
+| Stuff everything in context | Store large content in files |
+| Overwrite previous plans | Use `/start-planning` (auto-creates unique task dir) |
+| Start executing immediately | Run `/start-planning "task name"` FIRST |
+| Switch tasks without saving | Update task_plan.md before switching |
+
+## Advanced Patterns
+
+See [reference.md](../docs/reference.md) for:
+- Attention manipulation techniques
+- Error recovery patterns
+- Context optimization principles
+
+See [examples.md](../docs/examples.md) for:
+- Real task examples
+- Complex workflow patterns