Planning Foundation

Work like Manus: Use persistent markdown files as your "working memory on disk."

Every workflow skill in superpower-planning inherits this foundation. .planning/ is the "RAM on disk" for the current work session.

Planning Directory Convention

.planning/                     # gitignored, ephemeral working state
├── findings.md                # aggregated findings
├── progress.md                # Task Status Dashboard + session log
└── agents/                    # created on demand by subagents
    ├── implementer/           # one dir per role, reused across tasks
    │   ├── findings.md        # this agent's discoveries (appended across tasks)
    │   └── progress.md        # this agent's action log (appended across tasks)
    ├── spec-reviewer/
    └── ...

Plans go in docs/plans/. .planning/ is ephemeral session state. The agents/ directory is NOT created at init — each subagent creates its own subdirectory when dispatched.

Quick Start

Before ANY complex task:

1. Create .planning/ directory with init script or manually
2. Create progress.md — Use templates/progress.md (includes Task Status Dashboard)
3. Create findings.md — Use templates/findings.md as reference
4. Re-read plan before decisions — Refreshes goals in attention window
5. Update after each phase — Mark complete, log errors

The Core Pattern

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

-> Anything important gets written to disk.

File Purposes

Critical Rules

1. Create Planning Dir First

Never start a complex task without .planning/. Plans always go in docs/plans/. Execution status is tracked via the Task Status Dashboard in progress.md.

2. The 2-Action Dispatch Rule

"After every 2 read/search/explore operations, IMMEDIATELY save to the appropriate file by content type."

Dispatch by content type:

This prevents both knowledge AND progress from being lost.

3. Read Before Decide

Before major decisions, read the plan file. This keeps goals in your attention window.

4. Update After Act

After completing any phase:

• Mark phase status: in_progress -> complete
• Log any errors encountered
• Note files created/modified

5. Log ALL Errors

Every error goes in the plan file. This builds knowledge and prevents repetition.

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

6. Never Repeat Failures

if action_failed:
    next_action != same_action

Track what you tried. Mutate the approach.

The 3-Strike Error Protocol

ATTEMPT 1: Diagnose & Fix
  -> Read error carefully
  -> Identify root cause
  -> Apply targeted fix

ATTEMPT 2: Alternative Approach
  -> Same error? Try different method
  -> Different tool? Different library?
  -> NEVER repeat exact same failing action

ATTEMPT 3: Broader Rethink
  -> Question assumptions
  -> Search for solutions
  -> Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  -> Explain what you tried
  -> Share the specific error
  -> Ask for guidance

Read vs Write Decision Matrix

The 5-Question Reboot Test

If you can answer these, your context management is solid:

When to Use This Pattern

Use for:

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating projects
• Tasks spanning many tool calls
• Subagent orchestration

Skip for:

• Simple questions
• Single-file edits
• Quick lookups

Per-Agent Planning Directories

When dispatching subagents, each gets its own planning dir:

.planning/agents/{role}/
├── findings.md    # agent's discoveries (appended across tasks)
└── progress.md    # agent's action log (appended across tasks)

Do NOT create per-task directories like implementer-task-1/. One directory per role, updated continuously.

The orchestrator aggregates agent findings into top-level .planning/findings.md and .planning/progress.md after each task completes.

Templates

• templates/findings.md — Research storage
• templates/progress.md — Session logging
• templates/agent-context.md — Planning rules to inject into subagent prompts

Scripts

• scripts/init-planning-dir.sh — Initialize .planning/ directory with all files
• scripts/check-complete.sh — Verify all phases complete
• scripts/session-catchup.py — Recover context from previous session

Anti-Patterns