pi-planning-with-files by othmanadi/planning-with-files
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 查看实际的代码更改templates/ 目录广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 位置 | 存放内容 |
|---|---|
| 技能目录 | 模板、脚本、参考文档 |
| 你的项目目录 | task_plan.md、findings.md、progress.md |
在进行任何复杂任务之前:
task_plan.md — 参考 templates/task_plan.mdfindings.md — 参考 templates/findings.mdprogress.md — 参考 templates/progress.md注意: 规划文件放在你的项目根目录,而不是技能安装文件夹。
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
| 文件 | 用途 | 何时更新 |
|---|---|---|
task_plan.md | 阶段、进度、决策 | 每个阶段后 |
findings.md | 研究、发现 | 任何发现后 |
progress.md | 会话日志、测试结果 | 整个会话期间 |
没有 task_plan.md 绝不开始复杂任务。没有商量余地。
“每进行 2 次查看/浏览/搜索操作后,立即将关键发现保存到文本文件。”
这可以防止视觉/多模态信息丢失。
在重大决策之前,阅读计划文件。这能使目标保持在你的注意力窗口中。
完成任何阶段后:
in_progress → complete每个错误都要记录在计划文件中。这有助于积累知识并避免重复。
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
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 |
适用于:
不适用于:
复制这些模板开始:
用于自动化的辅助脚本:
scripts/init-session.sh — 初始化所有规划文件scripts/check-complete.sh — 验证所有阶段是否完成scripts/session-catchup.py — 从之前的会话恢复上下文 (v2.2.0)| 不要 | 应该这样做 |
|---|---|
| 使用 TodoWrite 来持久化 | 创建 task_plan.md 文件 |
| 陈述一次目标就忘记 | 决策前重新阅读计划 |
| 隐藏错误并静默重试 | 将错误记录到计划文件 |
| 把所有东西塞进上下文 | 将大量内容存储在文件中 |
| 立即开始执行 | 首先创建计划文件 |
| 重复失败的操作 | 跟踪尝试,改变方法 |
| 在技能目录中创建文件 | 在你的项目中创建文件 |
每周安装量
3.0K
仓库
GitHub 星标
17.2K
首次出现
2026年2月4日
安全审计
安装于
opencode2.5K
gemini-cli2.4K
codex2.4K
github-copilot2.4K
kimi-cli2.3K
amp2.3K
Work like Manus: Use persistent markdown files as your "working memory on disk."
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:
git diff --stat to see actual code changestemplates/ inside this skill| Location | What Goes There |
|---|---|
| Skill directory | Templates, scripts, reference docs |
| Your project directory | task_plan.md, findings.md, progress.md |
Before ANY complex task:
task_plan.md — Use templates/task_plan.md as referencefindings.md — Use templates/findings.md as referenceprogress.md — Use templates/progress.md as referenceNote: Planning files go in your project root, not the skill installation folder.
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
| 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 |
Never start a complex task without task_plan.md. Non-negotiable.
"After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
Before major decisions, read the plan file. This keeps goals in your attention window.
After completing any phase:
in_progress → completeEvery 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 |
if action_failed:
next_action != same_action
Track what you tried. Mutate the approach.
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
| 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 |
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 |
Use for:
Skip for:
Copy these templates to start:
Helper scripts for automation:
scripts/init-session.sh — Initialize all planning filesscripts/check-complete.sh — Verify all phases completescripts/session-catchup.py — Recover context from previous session (v2.2.0)| 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
GitHub Stars
17.2K
First Seen
Feb 4, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykWarn
Installed on
opencode2.5K
gemini-cli2.4K
codex2.4K
github-copilot2.4K
kimi-cli2.3K
amp2.3K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装
AI智能体长期记忆系统 - 精英级架构,融合6种方法,永不丢失上下文
1,200 周安装
AI新闻播客制作技能:实时新闻转对话式播客脚本与音频生成
1,200 周安装
Word文档处理器:DOCX创建、编辑、分析与修订痕迹处理全指南 | 自动化办公解决方案
1,200 周安装
React Router 框架模式指南:全栈开发、文件路由、数据加载与渲染策略
1,200 周安装
Nano Banana AI 图像生成工具:使用 Gemini 3 Pro 生成与编辑高分辨率图像
1,200 周安装
SVG Logo Designer - AI 驱动的专业矢量标识设计工具,生成可缩放品牌标识
1,200 周安装