planning-with-files
Manus-style file-based planning for complex tasks. Use task_plan.md, findings.md, and progress.md to maintain persistent context. Use for multi-step tasks, research, or work spanning many tool calls.
How do I install this agent skill?
npx skills add https://github.com/oimiragieo/agent-studio --skill planning-with-filesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill implements a persistent file-based planning workflow. While functionally safe and containing no malicious code or external dependencies, it creates a vulnerability surface for indirect prompt injection. The workflow mandates that the agent save external research data into planning files and then use those files as authoritative guides for subsequent steps, without implementing sanitization or boundary markers. It also includes self-attested 'verified' status in its YAML metadata.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1/10 files flagged
What does this agent skill do?
Planning with Files - Manus-Style File-Based Planning
Work like Manus (the $2B AI agent Meta acquired): Use persistent markdown files as your "working memory on disk."
Core Principle
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
The 3-File Pattern
For every complex task, create THREE files in your project directory:
task_plan.md → Track phases and progress
findings.md → Store research and findings
progress.md → Session log and test results
Templates are available at: .claude/templates/planning/
When to Use This Pattern
Use 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
Critical Timing Rules
These rules simulate hooks to ensure proper workflow:
📌 At Task Start (SessionStart)
MUST create all three files FIRST before any other work:
- Create
task_plan.mdusing the template - Create
findings.mdusing the template - Create
progress.mdusing the template - Fill in the Goal section in task_plan.md
Why: Without planning files, you'll forget goals after 50+ tool calls.
📌 Before Major Decisions (PreToolUse)
MUST re-read task_plan.md before:
- Writing or editing files
- Executing commands
- Making architectural decisions
- Implementing features
How: Use the Read tool to refresh the plan in your context.
Why: This keeps goals fresh in your attention window (Manus's "attention manipulation").
📌 After File Operations (PostToolUse)
MUST update status immediately after:
- Writing files
- Editing files
- Completing a task phase
How: Edit task_plan.md to update phase status:
- **Status:** pending → in_progress → complete
Why: Tracks progress and prevents losing track of what's done.
📌 Before Task End (Stop)
MUST verify completion:
- Check all phases marked as
complete - Review deliverables section
- Ensure no errors left unresolved
Why: Prevents premature completion with missing work.
The 6 Critical Rules
1. Create Plan First
Never start a complex task without task_plan.md. Non-negotiable.
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress
2. The 2-Action Rule
"After every 2 view/browser/search operations, IMMEDIATELY save key findings to findings.md."
This prevents visual/multimodal information from being lost.
## Visual/Browser Findings
- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format
3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
# Before implementing a feature:
Read tool → task_plan.md
# Now proceed with implementation
4. Update After Act
After completing any phase:
- Mark phase status:
pending→in_progress→complete - Log any errors encountered
- Note files created/modified
## Errors Encountered
| Error | Attempt | Resolution |
| ----------------- | ------- | ---------------------- |
| FileNotFoundError | 1 | Created default config |
5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
6. Never Repeat Failures
if action_failed:
next_action != same_action
Track what you tried. Mutate the approach.
The 3-Strike Error 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
File Purposes
| 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 |
Read vs Write Decision Matrix
| 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 |
The 5-Question Reboot Test
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 |
Template Structure
task_plan.md Template
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
| Decision | Rationale |
| -------- | --------- |
| | |
## Errors Encountered
| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
| | 1 | |
findings.md Template
# Findings & Decisions
## Requirements
_Add requirements captured from user request here._
## Research Findings
_Document key discoveries during exploration here._
## Technical Decisions
_Record decisions made with rationale._
| Decision | Rationale |
| -------- | --------- |
| | |
## Issues Encountered
_Document errors and how they were resolved._
| Issue | Resolution |
| ----- | ---------- |
| | |
## Resources
_Add URLs, file paths, and API references here._
## Visual/Browser Findings
_CRITICAL: Update after every 2 view/browser operations._
progress.md Template
# Progress Log
## Session: [DATE]
### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
- Files created/modified:
## Test Results
| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
| | | | | |
## Error Log
| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
| | | 1 | |
## 5-Question Reboot Check
| Question | Answer |
| -------------------- | ---------------- |
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
Iron Laws
- ALWAYS create
task_plan.md,findings.md, andprogress.mdbefore starting any complex task — filesystem memory survives context resets, working memory does not. - ALWAYS re-read
task_plan.mdbefore making major decisions — context windows are volatile, files persist indefinitely. - NEVER retry a failed action with identical inputs — log the failure in the plan file, diagnose the root cause, and mutate the approach.
- ALWAYS write multimodal findings (screenshots, browser data) to
findings.mdimmediately after capture — visual context cannot be retrieved once it leaves the attention window. - NEVER mark a task complete without verifying all phases are
completeand all deliverables are present in the progress file.
Anti-Patterns
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Using session task tools for persistence | In-memory task tracking is volatile; lost on context reset | Create task_plan.md file on disk — survives resets |
| Stating goals once and forgetting them | Context fills; goals drift without anchoring | Re-read plan file before every major decision |
| Hiding errors and retrying silently | Silent retries repeat the same failure endlessly | Log every error to plan file with attempt count |
| Stuffing all research into context | Context window fills; earlier content gets lost | Store large content and discoveries in findings.md |
| Starting execution without a plan | Undefined scope leads to wasted work and missed steps | Create all three planning files FIRST before any action |
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 |
| Completion verification | Check all phases before stopping |
Remember: The more context you gather upfront and write to disk, the better your execution will be. Files are your persistent memory.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oimiragieo/agent-studio/planning-with-files">View planning-with-files on skillZs</a>