planning-with-files

This skill should be used when the user asks to start a complex task, research project, multi-step implementation, or any task expected to require more than...

Security Scan

The skill's requests and behavior are coherent with its stated purpose (persistent, file-based planning); it writes and reads local markdown files and runs simple local scripts, and does not request credentials or remote installs.

Purpose & Capability

Name/description match the actual behavior: the skill implements a filesystem-backed planning workflow, provides templates, and includes simple init/check scripts. Requiring filesystem access and the ability to exec local scripts is appropriate for this purpose.

Instruction Scope

SKILL.md is prescriptive: it requires running scripts (init-session.sh, check-complete.sh), creating/updating task_plan.md, findings.md, and progress.md, and following the '2-Action Rule' to persist fetched information. This stays within the planning scope, but it does mandate persisting fetched/viewed data to disk (which may include sensitive content) and implicitly relies on an OPENCLAW_WORKDIR environment variable inside the scripts (the SKILL.md does not mention this env var).

Install Mechanism

No install spec or remote downloads. The skill is instruction-first and ships small local shell scripts and templates — low-risk from an install perspective. Scripts are simple, readable, and create files from local templates; nothing is fetched from external URLs.

Credentials

The skill declares no required env vars or credentials, which is consistent with its purpose. However, the scripts optionally read OPENCLAW_WORKDIR (falling back to pwd) but that variable is not declared in SKILL.md. The skill requires permission to run the exec tool and write to the filesystem — reasonable but should be consciously granted.

Persistence & Privilege

always:false (no forced global presence). The skill writes files in the working directory and will stop the agent from finishing until check-complete.sh returns success, which is expected behaviour for a planning workflow. It does not modify other skills or system-wide settings.

Assessment

This skill appears to be what it says: a filesystem-based planning helper that creates and updates three markdown files and runs two small shell scripts. Before installing or enabling it, review and confirm these points: - Permission scope: the skill requires the agent to be allowed to run 'exec' and write files (group:runtime, group:fs). Only grant those if you trust the agent and workspace. - Persistence/privacy: the workflow intentionally writes fetched/search results and notes to disk (findings.md). Do not use this skill in directories that may contain sensitive files or credentials. Consider using a dedicated project workspace or setting OPENCLAW_WORKDIR to a safe path. - Implicit env var: the scripts honor OPENCLAW_WORKDIR (defaulting to pwd) though it isn't declared in SKILL.md — be aware where files will be created. - Inspect scripts/templates: the bundled scripts are short and local; if you have concerns, review them before use and restrict the skill to workspace-level installation (README shows how). - Autonomy: the agent may invoke the skill for eligible complex tasks; if you prefer manual control, adjust skill availability or agent permissions. If you want a higher level of assurance, run the scripts in a disposable workspace to observe behavior, or ask the author for clarification on OPENCLAW_WORKDIR and any intended defaults.

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:

1. Run the init script to create the three planning files:

   exec: bash {baseDir}/scripts/init-session.sh "<task description>"
   

2. Fill in the ## Goal section in task_plan.md with the full task description.
3. Break the task into 3–7 phases and add them under ## Phases.
4. 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.