Planning with Files

Manus-style persistent markdown planning. Filesystem = long-term memory. Context window = working RAM.

Core Principle

Context Window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)
→ Anything important MUST be written to disk.

When to Use

Multi-step tasks (3+ phases or 5+ tool calls)
Research + implementation tasks
Tasks that span multiple sessions
Any task where goal-drift is a risk

Skip for: single-file edits, quick lookups, simple questions.

Session Start Protocol

ALWAYS do this first — no exceptions:

Run the init script to create the three planning files: exec: bash {baseDir}/scripts/init-session.sh "<task description>"
Fill in the ## Goal section in task_plan.md with the full task description.
Break the task into 3–7 phases and add them under ## Phases.
Confirm files exist before proceeding.

If exec is not available, create the three files manually using the templates in {baseDir}/templates/.

The Three Files

task_plan.md — Goal tracker (MOST IMPORTANT)

Created at session start, never deleted
Re-read before every major decision
Update when: phase completes, decision made, error encountered

findings.md — Knowledge store

Research results, discoveries, technical decisions
2-Action Rule: after every 2 view/search/fetch operations → update findings.md immediately

progress.md — Session log

Actions taken, test results, errors encountered
Append-only; never rewrite history

Work Loop

BEFORE every major action:
  → Re-read task_plan.md (keeps goal in attention)

EVERY 2 view/search/fetch operations:
  → Save key findings to findings.md NOW

AFTER completing a phase:
  → Update phase status in task_plan.md to "complete"
  → Append phase summary to progress.md

WHEN an error occurs:
  → Log it in task_plan.md under ## Errors table
  → Never repeat the same failing action

BEFORE stopping:
  → Run: exec bash {baseDir}/scripts/check-complete.sh
  → Only stop if all phases show "complete"

File Update Rules

Trigger	File to update	Section
Start task	task_plan.md	Goal + Phases
2nd research op	findings.md	Key Findings
Make decision	findings.md	Technical Decisions
Phase done	task_plan.md	Phase status → complete
Phase done	progress.md	Phase summary
Error	task_plan.md	Errors table
Test result	progress.md	Test Results

Error Recovery Protocol

ATTEMPT 1: Diagnose & Fix
  → Read error carefully → identify root cause → targeted fix

ATTEMPT 2: Alternative Approach
  → Same error? Try different tool/library/method
  → NEVER repeat the exact same failing action

ATTEMPT 3: Broader Rethink
  → Question assumptions → search for solutions → update plan

AFTER 3 FAILURES:
  → Escalate to user: explain what was tried, share the error, ask for guidance

Completion Verification

Before telling the user the task is done: 1. Run exec bash {baseDir}/scripts/check-complete.sh 2. If any phase is NOT "complete" → continue working 3. Only deliver result when all phases are checked off

Session Recovery

If context was cleared (e.g., /clear), resume by: 1. Reading task_plan.md to restore goal and phase status 2. Reading progress.md to see what was done 3. Reading findings.md to restore research context 4. Continuing from the first incomplete phase

Key Principles

Plan is Required: Never start a complex task without task_plan.md
Files are Memory: Context is volatile. Filesystem is permanent. Write important things down.
Never Repeat Failures: Track what was tried. Mutate the approach.
Error Recovery = Agentic Behavior: How you handle failures defines task quality.
Re-read Before Deciding: Attention manipulation — keep the goal visible.

planning-with-files-from-github

Installation