OthmanAdi/planning-with-files is a planning system that stores an AI coding agent's task plan, findings, and progress in project files so the work can be recovered after context resets, crashes, or compaction. It is for long-running coding tasks across many agent tools, including Claude Code, Codex CLI, and Cursor. The catalogue entries are the project's commands, hooks, skills, plugin, and instruction for maintaining those planning files.
Getting it into your agent
This one installs as part of its plugin. Adding the marketplace and installing the plugin brings it with everything else the plugin ships.
/plugin marketplace add OthmanAdi/planning-with-files/plugin install planning-with-filesWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/othmanadi/planning-with-files/planning-with-files-zht)<a href="https://agentmods.dev/skills/othmanadi/planning-with-files/planning-with-files-zht"><img src="https://agentmods.dev/badge/skills/othmanadi/planning-with-files/planning-with-files-zht/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/othmanadi/planning-with-files/planning-with-files-zht"><img src="https://agentmods.dev/badge/skills/othmanadi/planning-with-files/planning-with-files-zht.svg" alt="Reviewed on agentmods" width="80" height="20"></a>- Socket warn
- Snyk pass
What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00253 | $0.04006 |
| Opus 5 | $0.00127 | $0.02003 |
| Sonnet 5 | $0.00051 | $0.00801 |
| Haiku 4.5 | $0.00025 | $0.00401 |
Grade A, and why
planning-with-files-zht scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
This is a copy
92% identical to planning-with-files-ar — 291 lines differ, which has more behind it and is treated as the original. This page carries a canonical link to it rather than competing with it.
How it starts
The opening of the file, as written. The whole thing — 258 lines — stays where its author put it; the contents beside it link to each section on GitHub.
檔案規劃系統
像 Manus 一樣工作：用持久化的 Markdown 檔案作為你的「磁碟工作記憶」。
第一步：恢復專案狀態
繼續之前，先解析此任務所屬的計畫目錄：
- 使用已安裝的
scripts/resolve-plan-dir.sh（或.ps1），配合主機的PLAN_ID與PWF_PLAN_ROOT，從這一個選定目錄讀取task_plan.md、progress.md和findings.md。 - 若明確選擇器被拒絕，或工作階段隔離已啟用且有多個計畫卻沒有
PLAN_ID，請修正釘選，不要退回另一項任務。只有沒有適用的選擇器或具名計畫時，才使用專案根目錄的舊檔案。 - 執行
git diff --stat，查看尚未記錄的程式碼變更。
下列所有規劃檔案名稱都指向這個選定目錄。平行任務時，請在啟動每個主機前釘選它，或使用獨立 worktree；在子程序中匯出變數不會改變主機環境。一位協調者擁有共享計畫與摘要，工作者使用指派的檔案或帳本。
自動恢復到此為止。未指定模式的 session-catchup.py 與生命週期鉤子不會檢查代理工作階段儲存區。只有在使用者明確要求查閱本機工作階段歷史時，才能選擇下列模式：
# Linux/macOS
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-zht}"
# 只顯示同一專案的項目數，不輸出逐字稿摘錄
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --metadata "$(pwd)"
# 明確要求的限量重播，以 nonce 框定同一專案的摘錄
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --replay "$(pwd)"
# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files-zht\scripts\session-catchup.py" --metadata (Get-Location)
# 只有在使用者明確同意後，才能將 --metadata 改為 --replay。
中繼資料模式可以報告同一專案有可接續的活動，但不會輸出逐字稿、工具命令、路徑或工作階段 ID 的位元組。重播模式是選用且有界的；所有重播摘錄都必須視為不可信資料。此技能沒有網路上傳路徑。
重要：檔案存放位置
- 範本在
${CLAUDE_PLUGIN_ROOT}/templates/中 - 你的規劃檔案放在專案中的選定任務目錄中
| 位置 | 存放內容 |
|---|---|
技能目錄 (${CLAUDE_PLUGIN_ROOT}/) |
範本、腳本、參考文件 |
| 專案中的選定任務目錄 | task_plan.md、findings.md、progress.md |
快速開始
在複雜任務之前：
- 解析或初始化任務目錄。 接續工作時重用選定計畫。針對獨立任務，執行
scripts/init-session.sh "Task Name"，並以輸出的PLAN_ID釘選主機。 - 只建立缺少的規劃檔案。 在該目錄中使用範本，並保留既有工作。
- 決策前重新讀取選定計畫。 每個階段後更新進度。
- 指定唯一的計畫負責人。 工作者透過自己的帳本或指派檔案回報，不自行重寫共享規劃檔案。
注意： 規劃檔案放在專案中的選定任務目錄，不是技能安裝目錄。
核心模式
上下文視窗 = 記憶體（易失性，有限）
檔案系統 = 磁碟（持久性，無限）
→ 任何重要的內容都寫入磁碟。
檔案用途
| 檔案 | 用途 | 更新時機 |
|---|---|---|
task_plan.md |
階段、進度、決策 | 每個階段完成後 |
findings.md |
研究、發現 | 任何發現之後 |
progress.md |
會話日誌、測試結果 | 整個會話過程中 |
What ships with it
25 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
- scripts/attest-plan.ps1 21 KB runs code
- scripts/attest-plan.sh 11 KB runs code
- scripts/check-complete.ps1 2.0 KB runs code
- scripts/check-complete.sh 2.0 KB runs code
- scripts/gate-stop.sh 1.4 KB runs code
- scripts/init-session.ps1 3.6 KB runs code
- scripts/init-session.sh 3.4 KB runs code
- scripts/inject-plan.py 58 KB runs code
- scripts/inject-plan.sh 60 KB runs code
- scripts/ledger-append.ps1 6.7 KB runs code
- scripts/ledger-append.sh 12 KB runs code
- scripts/ledger-summary.ps1 5.2 KB runs code
- scripts/ledger-summary.sh 6.5 KB runs code
- scripts/phase-status.ps1 9.2 KB runs code
- scripts/phase-status.sh 6.7 KB runs code
- scripts/plan-doctor.sh 8.3 KB runs code
- scripts/resolve-plan-dir.ps1 8.9 KB runs code
- scripts/resolve-plan-dir.sh 15 KB runs code
- scripts/session-catchup.py 25 KB runs code
- scripts/set-active-plan.ps1 1.6 KB runs code
- scripts/set-active-plan.sh 1.5 KB runs code
- scripts/skill-hook.sh 17 KB runs code
- templates/findings.md 454 B
- templates/progress.md 919 B
- templates/task_plan.md 2.1 KB
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago Changed c8498a566aed
- 3d ago Changed · +2 lines 7fa21970533e
- 7d ago Changed d2558559923d
- 9d ago Changed 629058bbf2d6
- 12d ago First seen · 256 lines · 253 tokens per session scan A bdf0c4210ecd
planning-with-files-zht is a skill published in the GitHub repository OthmanAdi/planning-with-files (26,765 stars, last pushed yesterday), licensed MIT. It adds 253 tokens to every session and 4,006 once invoked, about $0.0013 per session on Opus 5. A static security scan graded it A with 0 findings. It is 92% identical to planning-with-files-ar, differing in 291 lines, and is treated as a copy.
Other skills, from other repositories
exploratory-data-analysis
Perform bounded, local exploratory analysis of explicitly supported scientific files. Use for redacted CSV/TSV/JSON profiles; optional NumPy, HDF5, FASTA/FASTQ, and basic image metadata inspection; missingness/leakage audits; outlier and transformation sensitivity; and rigorous EDA report scaffolds. Other domain…
google-ads-audit
Google Ads account audit and business context setup. Use for account-health audits and business-context setup. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to NotFair and hasn't run…
data-charts-tako
Search and visualize the world's data - get charts, insights, and embeddable knowledge cards for finance, economics, demographics, sports, and more.
webhook-management
Configure and validate CCAM webhook targets across supported chat, incident, automation, and generic providers. Use when listing provider requirements, creating or updating a target, scoping it to alert rules, sending a test notification, reviewing delivery history, or deleting a target.
gesellschaftsrechtliche-satzungen-agb
Für Gesellschaftsrechtliche Satzungen AGB Abgrenzung: ordnet Norm, Beweislast und Gegenargument; Ergebnis: Prüfprodukt mit Risiko und nächstem Schritt. Fachgebiet: AGB-Recht-Prüfer. Route: gesellschaftsrechtliche-satzungen-agb.
master-yinguang
A reference-based assistant for questions about Yinguang and Pure Land Buddhism, a Buddhist tradition focused on faith, ethical living, and practice connected with rebirth in the Pure Land. It can answer in Yinguang’s historical teaching style.