persistent-planning

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:

Read .planning/[task-name]/task_plan.md  # Refresh goals in attention window

After each phase:

Edit .planning/[task-name]/task_plan.md  # Mark [x], update status

When storing information:

Write .planning/[task-name]/notes.md     # Don't stuff context, store in file

Managing Multiple Tasks

Task 1:

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):

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:

# 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:

# 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:

rm -rf .planning/[task-name]/

Or clean up everything:

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 for:

• Attention manipulation techniques
• Error recovery patterns
• Context optimization principles

See examples.md for:

• Real task examples
• Complex workflow patterns