Planning With Files
Keep goals, research, and progress in persistent markdown files so long agent sessions do not lose context after resets.
Overview
planning-with-files is a journey-wide agent skill that uses a 3-file markdown workflow (plan, notes, deliverable) so solo builders keep goals and progress durable across long agent sessions.
Install
npx skills add https://github.com/charon-fan/agent-playbook --skill planning-with-filesWhat is this skill?
- 3-file pattern: task_plan.md, notes.md, and a final deliverable markdown file
- Targets volatile memory, goal drift, untracked errors, and context stuffing
- Manus-style loop: plan phases, research into notes, update plan until deliverable is done
- Filesystem persistence survives TodoWrite-style ephemeral task lists
- Explicitly not for PRD work—use prd-planner when the artifact is a PRD
- 3-file pattern: task_plan.md, notes.md, and deliverable markdown
Adoption & trust: 976 installs on skills.sh; 58 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent forgets the original goal, repeats mistakes, and loses todos whenever context resets or tool calls pile up.
Who is it for?
Multi-step agent projects, research spikes, and builds where you want Manus-style file-backed planning without invoking PRD-specific skills.
Skip if: PRD authoring (use prd-planner), one-shot edits, or tasks that fit entirely in a single short prompt with no lasting artifact.
When should I use this skill?
Multi-step tasks, research projects, or general organization without mentioning PRD—for PRD-specific work use prd-planner instead.
What do I get? / Deliverables
You end with tracked phases in task_plan.md, captured research in notes.md, and a finished deliverable file instead of a single bloated chat transcript.
- task_plan.md with goals and phases
- notes.md with research and error log
- Final [deliverable].md output file
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Track competitor research phases in task_plan.md while storing sources and takeaways in notes.md before committing to a build.
Split an integration into phases on disk so API exploration in notes.md does not overwrite the original migration goal.
Log review findings and fix waves in notes.md while task_plan.md stays the checklist for launch readiness.
Run a multi-article content sprint with one deliverable file per piece and shared research in notes.md.
Document incident hypotheses and retries in notes.md with operate phases in task_plan.md across sessions.
How it compares
Persistent markdown planning workflow, not ephemeral in-chat todo lists or PRD template skills.
Common Questions / FAQ
Who is planning-with-files for?
Solo and indie builders who run long Claude Code or Cursor sessions and need goals and findings to survive context limits.
When should I use planning-with-files?
Use it journey-wide: during Validate for research organization, Build for implementation phases, Ship for review prep, Grow for content pipelines, and Operate when iterating on incidents—whenever the task has multiple steps and you are not writing a PRD.
Is planning-with-files safe to install?
Check the Security Audits panel on this page; the skill is allowed to read, write, edit, grep, glob, and run bash on your project files, so use it only in repos you trust.
SKILL.md
READMESKILL.md - Planning With Files
# Planning with Files > "Work like Manus" — Uses persistent markdown files for planning, progress tracking, and knowledge storage. ## Description A Claude Code skill that transforms your workflow to use persistent markdown files for planning and progress tracking — the pattern that made Manus AI worth billions. ## The Problem Claude Code (and most AI agents) suffer from: - **Volatile memory** — TodoWrite tool disappears on context reset - **Goal drift** — Original goals get forgotten after many tool calls - **Hidden errors** — Failures aren't tracked, mistakes repeat - **Context stuffing** — Everything crammed into context instead of stored ## The Solution: 3-File Pattern For every complex task, create THREE files: ```text task_plan.md → Track phases and progress notes.md → Store research and findings [deliverable].md → Final output ``` ### The Workflow Loop ```text 1. Create task_plan.md with goal and phases 2. Research → save to notes.md → update task_plan.md 3. Read notes.md → create deliverable → update task_plan.md 4. Deliver final output ``` ## When to Use **Use this pattern for:** - Multi-step tasks (3+ steps) - Research tasks - Building/creating projects - Tasks spanning many tool calls - Anything requiring organization **Skip for:** - Simple questions - Single-file edits - Quick lookups ## Installation This skill is typically installed globally at `~/.claude/skills/planning-with-files/`. From this repository: ```bash ln -s /path/to/agent-playbook/skills/planning-with-files ~/.claude/skills/planning-with-files ``` If you prefer the standalone workflow, see the upstream repository in the Links section. ## The Manus Principles | Principle | Implementation | |-----------|----------------| | Filesystem as memory | Store in files, not context | | Attention manipulation | Re-read plan before decisions | | Error persistence | Log failures in plan file | | Goal tracking | Checkboxes show progress | | Append-only context | Never modify history | ## Example **You:** "Research the benefits of TypeScript and write a summary" **Claude creates:** ```markdown # Task Plan: TypeScript Benefits Research ## Goal Create a research summary on TypeScript benefits. ## Phases - [x] Phase 1: Create plan ✓ - [ ] Phase 2: Research and gather sources (CURRENT) - [ ] Phase 3: Synthesize findings - [ ] Phase 4: Deliver summary ## Status **Currently in Phase 2** - Searching for sources ``` ## Links - [GitHub Repository](https://github.com/OthmanAdi/planning-with-files) - [Context Engineering for AI Agents](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) # Planning With Files > A Claude Code skill for file-based planning and progress tracking. ## Installation This skill is part of the [agent-playbook](../../README.md) collection. ## Usage ``` You: Plan a multi-step migration and track progress in files You: Create a research plan and save notes and deliverables You: Organize this project with persistent task files ``` ## Core Pattern ``` /task_plan.md -> Phases and progress /notes.md -> Research and findings /output.md -> Final deliverable ``` ## Notes If you prefer the original standalone workflow, see the upstream project linked in the skill documentation.