planning-with-files
charon-fan/agent-playbook
Use persistent markdown files for planning, progress tracking, and knowledge storage across multi-step tasks.
What is planning-with-files?
A skill that implements the Manus-style workflow using persistent markdown files to overcome volatile memory and goal drift in AI agents. Use this for multi-step tasks, research projects, and complex workflows that span many tool calls—skip it for simple questions or single-file edits.
- Create and maintain a 3-file pattern (task_plan.md, notes.md, deliverable.md) for organized task tracking
- Track progress with phases and checkboxes to prevent goal drift and context loss
- Store research findings and intermediate results in persistent files instead of relying on volatile context
- Log failures and errors in the plan file to avoid repeating mistakes
- Re-read the plan before decisions to maintain focus and attention
How to install planning-with-files
npx skills add https://github.com/charon-fan/agent-playbook --skill planning-with-filesHow to use planning-with-files
- 1.Create task_plan.md with your goal and list the phases needed to complete it
- 2.Create notes.md for storing research findings and intermediate results
- 3.Before each major step, re-read task_plan.md to confirm your current phase and goals
- 4.After research or work, update notes.md with findings and update task_plan.md with progress
- 5.Create your final deliverable file and update task_plan.md when complete
Use cases
- Research projects where findings need to be stored and referenced across multiple steps
- Multi-phase development or writing tasks that span many tool calls
- Building projects with complex requirements that need phase-based progress tracking
- Organizing knowledge and findings for later synthesis into a final deliverable
- Long-running tasks where context reset would otherwise lose progress
- Developers working on multi-step coding projects
- Researchers conducting literature reviews or data gathering
- Project managers tracking complex task workflows
- Anyone building or creating deliverables that require organization and planning
planning-with-files FAQ
Use it for multi-step tasks (3+ steps), research projects, or anything spanning many tool calls. Skip it for simple questions or single-file edits.
This skill is for general planning and organization. Use prd-planner instead if you're working on PRD-specific tasks.
By storing information in persistent markdown files on disk instead of relying on volatile context, your progress survives context resets and tool call limits.
The core pattern (task_plan.md, notes.md, deliverable.md) is designed for consistency, but you can adapt it to your specific needs.
The skill requires Read, Write, Edit, Bash, Grep, and Glob tools to manage files and track progress.
Full instructions (SKILL.md)
Source of truth, from charon-fan/agent-playbook.
name: planning-with-files description: Uses persistent markdown files for general planning, progress tracking, and knowledge storage (Manus-style workflow). Use for multi-step tasks, research projects, or general organization WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead. allowed-tools: Read, Write, Edit, Bash, Grep, Glob metadata: hooks: after_complete: - trigger: session-logger mode: auto reason: "Log planning activity"
Planning with Files
"Work like Manus" — Uses persistent markdown files for planning, progress tracking, and knowledge storage.
Description
A skill that transforms your workflow to use persistent markdown files for planning and progress tracking.
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:
task_plan.md → Track phases and progress
notes.md → Store research and findings
[deliverable].md → Final output
The Workflow Loop
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:
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:
# 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
Related skills
More from charon-fan/agent-playbook and the wider catalog.
prd-implementation-precheck
Implement PRDs/specs with a mandatory precheck review before coding. Use when a user asks to implement a PRD/feature spec/requirements doc or says "implement PRD/spec". Perform a preflight review, raise questions on scope/consistency/risks, then implement after confirmation.
prd-planner
Creates PRDs using persistent file-based planning. Use when user explicitly says "PRD", "product requirements document", or "产品需求文档". Combines PRD methodology with planning-with-files to avoid context switching.
qa-expert
Quality assurance expert for testing strategies and quality gates. Use when planning test coverage, setting up QA processes, or improving quality standards.
refactoring-specialist
Code refactoring expert for improving code structure, readability, and maintainability. Use when user asks to refactor, clean up, or improve code quality.
security-auditor
Security vulnerability expert covering OWASP Top 10 and common security issues. Use when conducting security audits or reviewing code for vulnerabilities.
self-improving-agent
Universal self-improving agent that learns from all skill experiences using multi-memory architecture.