planning-with-filesImplements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
Install via ClawdBot CLI:
clawdbot install OthmanAdi/planning-with-filesWork like Manus: Use persistent markdown files as your "working memory on disk."
Before starting work, check for unsynced context from a previous session:
# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
If catchup report shows unsynced context:
git diff --stat to see actual code changes${CLAUDE_PLUGIN_ROOT}/templates/| Location | What Goes There |
|----------|-----------------|
| Skill directory (${CLAUDE_PLUGIN_ROOT}/) | Templates, scripts, reference docs |
| Your project directory | task_plan.md, findings.md, progress.md |
Before ANY complex task:
task_plan.md ā Use templates/task_plan.md as referencefindings.md ā Use templates/findings.md as referenceprogress.md ā Use templates/progress.md as referenceNote: Planning files go in your project root, not the skill installation folder.
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
ā Anything important gets written to disk.
| File | Purpose | When to Update |
|------|---------|----------------|
| task_plan.md | Phases, progress, decisions | After each phase |
| findings.md | Research, discoveries | After ANY discovery |
| progress.md | Session log, test results | Throughout session |
Never start a complex task without task_plan.md. Non-negotiable.
"After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
Before major decisions, read the plan file. This keeps goals in your attention window.
After completing any phase:
in_progress ā completeEvery 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 |
if action_failed:
next_action != same_action
Track what you tried. Mutate the approach.
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
| 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 |
If you can answer these, your context management 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 |
Use for:
Skip for:
Copy these templates to start:
Helper scripts for automation:
scripts/init-session.sh ā Initialize all planning filesscripts/check-complete.sh ā Verify all phases completescripts/session-catchup.py ā Recover context from previous session (v2.2.0)| 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 |
Generated Feb 28, 2026
Managing a multi-phase software build with requirements gathering, coding, testing, and deployment. The skill helps create and update task_plan.md for phases like setup, feature implementation, and bug fixes, while findings.md logs research on libraries or APIs, and progress.md tracks test results and session logs.
Conducting literature review, data analysis, and drafting sections for a research paper. The skill ensures task_plan.md outlines phases like literature search, methodology design, and writing, with findings.md capturing key sources and insights, and progress.md documenting analysis steps and revisions.
Planning and executing a digital marketing campaign with phases such as audience research, content creation, and performance tracking. The skill uses task_plan.md to define milestones, findings.md to record competitor insights and data trends, and progress.md to log campaign metrics and adjustments.
Coordinating a product launch involving market research, development timelines, and launch activities. The skill helps structure task_plan.md with phases like market validation, prototype testing, and go-to-market, while findings.md stores user feedback and market data, and progress.md tracks preparation steps and issues.
Managing a complex migration of servers or applications to a new environment. The skill uses task_plan.md to plan phases like assessment, migration execution, and validation, with findings.md documenting technical specifications and risks, and progress.md logging migration steps and error resolutions.
Freelancers use the skill to manage client projects by creating detailed plans and tracking progress in files like task_plan.md. This improves efficiency, reduces errors, and allows for session recovery, leading to higher client satisfaction and repeat business.
SaaS companies integrate this skill into their platforms to help users plan and execute complex tasks within the software. It enhances user productivity by providing structured workflows, which can drive subscription renewals and upsells for premium features.
Enterprises adopt the skill for internal teams to standardize project management and knowledge retention. Training programs and support services are offered around its usage, generating revenue through consulting contracts and ongoing maintenance fees.
š¬ Integration Tip
Integrate this skill by setting up the planning files in your project directory first, and use hooks like PreToolUse to automatically review the task_plan.md before actions, ensuring consistency across sessions.
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Search and analyze your own session logs (older/parent conversations) using jq.
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.
Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vibe-coding ready.
Headless browser automation CLI optimized for AI agents with accessibility tree snapshots and ref-based element selection