Planning With Files

File-based planning for complex tasks. Use persistent markdown files as working memory to survive context resets. Creates task_plan.md, findings.md, and progress.md. Use for any task requiring >5 tool calls, research projects, or multi-step implementations.

Security Scan

The skill's inputs, files, and scripts are consistent with its stated purpose of using on-disk markdown as persistent planning memory and do not request unrelated credentials or install remote code.

Purpose & Capability

Name/description match the behavior: the skill creates and manages three markdown files and provides helper scripts and templates to treat the filesystem as persistent memory. There are no unrelated environment variables, binaries, or config paths requested.

Instruction Scope

SKILL.md instructs the agent to create/read/write task_plan.md, findings.md, and progress.md, and to run simple local commands (ls, cat, git diff --stat). This is coherent with the planning purpose. Note: the skill intentionally instructs persistent file creation in the project root and to log errors and discoveries; users should be aware that anything written to these files will persist on disk (and in git history if committed).

Install Mechanism

Instruction-only skill with no install spec that downloads/executes remote archives. Helper scripts are included in the package; there is no installer that fetches arbitrary code from untrusted URLs.

Credentials

Skill requires no environment variables, credentials, or config paths. The files and scripts operate on local files only, which is proportionate to the stated functionality.

Persistence & Privilege

always:false and no elevated privileges requested. The skill writes files in the project directory and includes small helper scripts; this is consistent with its purpose and does not modify other skills or system-wide settings.

Assessment

This skill is internally coherent and appears to do what it says — create and maintain three markdown files as persistent planning memory. Before installing or running it, consider: 1) The planning files (task_plan.md, findings.md, progress.md) will be created in your project root and persist on disk (and in your git history if committed). Do not log secrets or sensitive data there. 2) Review the included scripts (init-session.sh, check-complete.sh) — they are simple shell scripts that create/check files, but you should inspect them and run in a safe folder first. 3) If you use version control, consider adding these files to .gitignore or keeping them in a sandbox workspace to avoid accidental leakage. 4) The package source/homepage is unknown; although there are no network endpoints or remote installs in the package itself, prefer installing from a trusted source or inspecting the files locally before adding to long-running agents. 5) The agent can invoke skills autonomously by default; if you plan to run this skill in an autonomous agent, be mindful that it will create/modify files without prompting. If you want further checks (e.g., to ensure it never writes outside a specific directory), provide that constraint and I can point out the exact lines to change.

Use persistent markdown files as your "working memory on disk." Based on context engineering principles from Manus.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install planning-with-files

WHAT This Skill Does

Treats the filesystem as persistent memory to overcome context window limitations. Three files track your state:

File	Purpose	Update Frequency
task_plan.md	Phases, progress, decisions	After each phase
findings.md	Research, discoveries, decisions	After ANY discovery
progress.md	Session log, test results, errors	Throughout session

WHEN to Use

Use for:

• Multi-step tasks (3+ steps)
• Research tasks requiring web search
• Building/creating projects from scratch
• Tasks spanning >5 tool calls
• Anything requiring organization across multiple files
• Tasks where losing context would cause rework

Skip for:

• Simple questions
• Single-file edits
• Quick lookups
• Tasks completable in 1-2 actions

Keywords: complex task, multi-step, research, build project, create application, plan, organize

The Core Pattern

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

→ Anything important gets written to disk.

Workflow

Phase 1: Create Planning Files

Before starting ANY complex task, create all three files in your project root:

1. Create task_plan.md — Copy from templates/task_plan.md
2. Create findings.md — Copy from templates/findings.md
3. Create progress.md — Copy from templates/progress.md

Phase 2: Execute with Discipline

Follow these rules during execution:

The 2-Action Rule:

After every 2 view/browser/search operations, IMMEDIATELY save findings to text files.

Visual/multimodal content doesn't persist — write it down before it's lost.

Read Before Decide: Before major decisions, read your plan file. This keeps goals in your attention window after many tool calls.

Update After Act: After completing any phase:

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

Log ALL Errors: Every error goes in the plan file. This prevents repetition.

Phase 3: Handle Errors Systematically

The 3-Strike 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

Critical: if action_failed: next_action != same_action

Phase 4: Verify Completion

Use the 5-Question Reboot Test. If you can answer these, your context is solid:

Question	Answer Source
Where am I?	Current phase in task_plan.md
Where am I going?	Remaining phases
What's the goal?	Goal statement in plan
What have I learned?	findings.md
What have I done?	progress.md

Quick Reference: Read vs Write

Situation	Action	Reason
Just wrote a file	DON'T read	Content still in context
Viewed image/PDF	Write findings NOW	Multimodal → text before lost
Browser returned data	Write to file	Screenshots don't persist
Starting new phase	Read plan/findings	Re-orient if context stale
Error occurred	Read relevant file	Need current state to fix
Resuming after gap	Read all planning files	Recover state

Session Recovery

When starting a new session, check for previous work:

# Check if planning files exist
ls task_plan.md findings.md progress.md 2>/dev/null

# If they exist, read them all before continuing
cat task_plan.md findings.md progress.md

If planning files exist from a previous session:

1. Read all three files to recover context
2. Run git diff --stat to see what changed
3. Update planning files with any missing context
4. Continue from where you left off

Templates

Copy these to start:

• templates/task_plan.md — Phase tracking
• templates/findings.md — Research storage
• templates/progress.md — Session logging

Scripts

Helper scripts for automation:

• scripts/init-session.sh — Initialize all planning files
• scripts/check-complete.sh — Verify all phases complete

References

• references/manus-principles.md — Context engineering principles from Manus

Anti-Patterns

Don't	Do Instead
Use TodoWrite for persistence	Create task_plan.md file
State goals once and forget	Re-read plan before decisions
Hide errors and retry silently	Log errors to plan file
Stuff everything in context	Store large content in files
Start executing immediately	Create plan file FIRST
Repeat failed actions	Track attempts, mutate approach
Create files in skill directory	Create files in your project

NEVER Do

1. NEVER start a complex task without task_plan.md — this is non-negotiable
2. NEVER repeat a failed action exactly — track what you tried, mutate the approach
3. NEVER ignore errors — log every error with resolution attempts
4. NEVER rely on memory after >10 tool calls — re-read your plan
5. NEVER skip the 2-Action Rule for visual content — multimodal data gets lost
6. NEVER proceed past 3 failures without escalating — ask the user for help
7. NEVER create planning files in the skill directory — they go in your project root