planning-with-files

Q: How do I install planning-with-files?

Run npx skills add https://github.com/oimiragieo/agent-studio --skill planning-with-files in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/planning-with-files/ (personal) or .claude/skills/planning-with-files/ (project).

by oimiragieoCode Quality & Workflow

Manus-style file-based planning for complex tasks. Use taskplan.md, findings.md, and progress.md to maintain persistent context. Use for multi-step tasks, research, or work spanning many tool calls.

Installs: 76
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/oimiragieo/agent-studio --skill planning-with-files

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads planning-with-files automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.md using the template
Create findings.md using the template
Create progress.md using 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, and progress.md before starting any complex task — filesystem memory survives context resets, working memory does not.
ALWAYS re-read task_plan.md before 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.md immediately after capture — visual context cannot be retrieved once it leaves the attention window.
NEVER mark a task complete without verifying all phases are complete and 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.

FAQ

What does the planning-with-files skill do?

Manus-style file-based planning for complex tasks. Use taskplan.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 planning-with-files?

Run npx skills add https://github.com/oimiragieo/agent-studio --skill planning-with-files in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/planning-with-files/ (personal) or .claude/skills/planning-with-files/ (project).

Which AI agents can use planning-with-files?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is planning-with-files safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains planning-with-files?

It is published by oimiragieo in oimiragieo/agent-studio. It has 76 recorded installs.

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

planning-with-files

Install

Install

Describe the task

Review the result

SKILL.md

Planning with Files - Manus-Style File-Based Planning

Core Principle

The 3-File Pattern

When to Use This Pattern

Critical Timing Rules

📌 At Task Start (SessionStart)

📌 Before Major Decisions (PreToolUse)

📌 After File Operations (PostToolUse)

📌 Before Task End (Stop)

The 6 Critical Rules

1. Create Plan First

2. The 2-Action Rule

3. Read Before Decide

4. Update After Act

5. Log ALL Errors

6. Never Repeat Failures

The 3-Strike Error Protocol

File Purposes

Read vs Write Decision Matrix

The 5-Question Reboot Test

Template Structure

task_plan.md Template

findings.md Template

progress.md Template

Iron Laws

Anti-Patterns

The Manus Principles

FAQ

More from oimiragieo/agent-studio

Popular code quality & workflow skills