文件规划技能：使用Markdown文件作为持久化工作记忆，提升开发效率与项目管理

pi-planning-with-files by othmanadi/planning-with-files

3,000 周安装量

17,200 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/othmanadi/planning-with-files --skill pi-planning-with-files

开发生产力

🇨🇳中文介绍

文件规划

像 Manus 一样工作：使用持久的 Markdown 文件作为你的“磁盘工作记忆”。

第一步：检查之前的会话

开始工作之前，检查是否有来自之前会话的未同步上下文：

注意： scripts/ 目录位于此技能的安装文件夹内。

# Linux/macOS
python scripts/session-catchup.py "$(pwd)"



# Windows PowerShell
python scripts\session-catchup.py" (Get-Location)

如果找不到脚本： 请让 Pi 帮你定位：Run the session-catchup.py script from the planning-with-files skill

如果同步报告显示有未同步的上下文：

运行 git diff --stat 查看实际的代码更改
阅读当前的规划文件
根据同步报告和 git diff 更新规划文件
然后继续执行任务

重要：文件存放位置

模板位于此技能内的 templates/ 目录

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

位置	存放内容
技能目录	模板、脚本、参考文档
你的项目目录	`task_plan.md`、`findings.md`、`progress.md`

文件	用途	何时更新
`task_plan.md`	阶段、进度、决策	每个阶段后
`findings.md`	研究、发现	任何发现后
`progress.md`	会话日志、测试结果	整个会话期间

3. 决策前先阅读

在重大决策之前，阅读计划文件。这能使目标保持在你的注意力窗口中。

完成任何阶段后：

标记阶段状态：in_progress → complete
记录遇到的任何错误
注明创建/修改的文件

5. 记录所有错误

每个错误都要记录在计划文件中。这有助于积累知识并避免重复。

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

6. 绝不重复失败

if action_failed:
    next_action != same_action

跟踪你尝试过的内容。改变方法。

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

读取与写入决策矩阵

情况	操作	原因
刚写完文件	不要读取	内容仍在上下文中
查看了图像/PDF	立即写入发现	多模态 → 在丢失前转为文本
浏览器返回数据	写入文件	截图无法持久保存
开始新阶段	阅读计划/发现	如果上下文陈旧则重新定位
发生错误	阅读相关文件	需要当前状态来修复
中断后恢复	阅读所有规划文件	恢复状态

如果你能回答这些问题，说明你的上下文管理很扎实：

问题	答案来源
我在哪里？	task_plan.md 中的当前阶段
我要去哪里？	剩余阶段
目标是什么？	计划中的目标声明
我学到了什么？	findings.md
我做了什么？	progress.md

何时使用此模式

多步骤任务（3 步以上）
研究任务
构建/创建项目
涉及多次工具调用的任务
任何需要组织的任务

简单问题
单文件编辑
快速查找

复制这些模板开始：

templates/task_plan.md — 阶段跟踪
templates/findings.md — 研究存储
templates/progress.md — 会话日志记录

用于自动化的辅助脚本：

scripts/init-session.sh — 初始化所有规划文件
scripts/check-complete.sh — 验证所有阶段是否完成
scripts/session-catchup.py — 从之前的会话恢复上下文 (v2.2.0)

Manus 原则： 参见 reference.md
真实示例： 参见 examples.md

不要	应该这样做
使用 TodoWrite 来持久化	创建 task_plan.md 文件
陈述一次目标就忘记	决策前重新阅读计划
隐藏错误并静默重试	将错误记录到计划文件
把所有东西塞进上下文	将大量内容存储在文件中
立即开始执行	首先创建计划文件
重复失败的操作	跟踪尝试，改变方法
在技能目录中创建文件	在你的项目中创建文件

🇺🇸English

Planning with Files

Work like Manus: Use persistent markdown files as your "working memory on disk."

FIRST: Check for Previous Session

Before starting work , check for unsynced context from a previous session:

Note: The scripts/ directory is inside this skill's installation folder.

# Linux/macOS
python scripts/session-catchup.py "$(pwd)"



# Windows PowerShell
python scripts\session-catchup.py" (Get-Location)

If you cannot find the script: Ask Pi to locate it for you: Run the session-catchup.py script from the planning-with-files skill

If catchup report shows unsynced context:

Run git diff --stat to see actual code changes
Read current planning files
Update planning files based on catchup + git diff
Then proceed with task

Important: Where Files Go

Templates are in templates/ inside this skill
Your planning files go in your project directory

Location	What Goes There
Skill directory	Templates, scripts, reference docs
Your project directory	`task_plan.md`, `findings.md`, `progress.md`

Quick Start

Before ANY complex task:

Createtask_plan.md — Use templates/task_plan.md as reference
Createfindings.md — Use templates/findings.md as reference
Createprogress.md — Use templates/progress.md as reference
Re-read plan before decisions — Refreshes goals in attention window
Update after each phase — Mark complete, log errors

Note: Planning files go in your project root, not the skill installation folder.

The Core Pattern

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

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

Critical Rules

1. Create Plan First

Never start a complex task without task_plan.md. Non-negotiable.

2. The 2-Action Rule

"After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."

This prevents visual/multimodal information from being lost.

3. Read Before Decide

Before major decisions, read the plan file. This keeps goals in your attention window.

4. Update After Act

After completing any phase:

Mark phase status: in_progress → complete
Log any errors encountered
Note files created/modified

5. Log ALL Errors

Every 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 |

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

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

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

Templates

Copy these templates to start:

templates/task_plan.md — Phase tracking
templates/findings.md — Research storage
templates/progress.md — Session logging

Scripts

Helper scripts for automation:

scripts/init-session.sh — Initialize all planning files
scripts/check-complete.sh — Verify all phases complete
scripts/session-catchup.py — Recover context from previous session (v2.2.0)

Advanced Topics

Manus Principles: See reference.md
Real Examples: See examples.md

Anti-Patterns

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

Weekly Installs

3.0K

Repository

othmanadi/plann…th-files

GitHub Stars

17.2K

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

Installed on

opencode2.5K

gemini-cli2.4K

codex2.4K

github-copilot2.4K

kimi-cli2.3K

amp2.3K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装