AgentIndex icon
AgentIndex
ToolsMCP ServersHOTCategoriesTrendingNewBest ListsCompareGuides
Submit Tool
ToolsMCP ServersHOTCategoriesTrendingNewBest ListsCompareGuides
Home/
Memory & Context/
planning-with-files
planning-with-files logo

planning-with-files

Active·★ 28.1k·MIT·Updated 2026-11-11
★ Most Popular

Planning with Files (PWF) by Othman Adi is an open-source, battle-tested agent orchestration harness designed around a simple yet profound premise: 'Your agent's context window dies. The plan does not.' It provides an unshakeable, file-backed planning discipline that prevents autonomous coding agents from straying off-course during complex multi-step workflows.

Rather than trusting fragile prompt instructions that evaporate when context limits are reached or when a user types `/clear`, PWF enforces file-based state persistence through three dedicated disk artifacts: `task_plan.md` (hierarchical roadmap and active tasks), `findings.md` (architectural context, API quirks, and discovery notes), and `progress.md` (completed milestones and verification evidence). Lifecycle hooks trigger automatically every turn to re-anchor the model's focus to current disk realities.

Demonstrating consistent wins in blind A/B evaluations on complex coding tasks, PWF installs across 60+ agent harnesses adhering to the Agent Skills standard, with native integrations for Claude Code, Codex, Pi, OpenCode, and DeepSeek Harness. Teams should note that it generates planning files directly within the repository root (requiring git hygiene), and reading/updating files adds slight I/O overhead on multi-step reasoning loops.

This write-up is based on the project's README and public repository data. We have not hand-tested the tool. Data as of 2026-11-12.

License
MIT
Latest release
v3.28.1 · 2026-11-07
Last commit
2026-11-11
Contributors
72
Forks
2,311
Open issues and PRs
12
First published
2026-01-03

Source: GitHub, npm and PyPI public APIs.

#agent-skills#autonomous-agents#claude#claude-code#claude-code-skills#claude-skills#codex#coding-agent
$ Install
$ npx skills add OthmanAdi/planning-with-files --skill planning-with-files
↗ Visit site★ GitHub
01

Features

01Maintains task_plan.md, findings.md and progress.md.
02Lifecycle hooks inject selected project planning context.
03Offers Agent Skills and several host-specific plugin routes.
02

Why choose it

+Indestructible planning state: plans survive context window compaction, `/clear` resets, and terminal crashes.
+Structured 3-file system (task_plan, findings, progress) maintains clear separation between roadmaps, insights, and evidence.
+Automated lifecycle hooks fire on every turn, systematically preventing goal drift and hallucinated progress.
+Vast cross-agent compatibility covering 60+ harnesses including Claude Code, Codex, Pi, and DeepSeek Harness.
03

Trade-offs

!Generates planning files directly inside the repository working directory, requiring project `.gitignore` or git commits.
!Frequent filesystem read and write cycles add minor latency to each multi-step agent reasoning iteration.
!Manual code edits made by the developer outside the agent CLI require the agent to catch up on file states.
!May feel overly ceremonial for rapid, single-file bugfixes or trivial one-shot coding queries.
04

Maintenance check

ActiveChecked: 2026-11-12
Last commit
2026-11-11
Commits, last 90 days
100+
Releases, last 90 days
30
Latest release
v3.28.1 (2026-11-07)
Open issues
12
Recent issues with at least one comment
18/24
Commits per week, last 12 weeks
Commits per week, last 12 weeks: 9, 27, 14, 62, 38, 5, 12, 16, 21, 13, 31, 12

Oldest week on the left; the latest four weeks are orange. Source: GitHub commit activity.

Status rule: archived on GitHub = Archived; last commit within 90 days = Active; 91 to 365 days = Slowing; older = Stale. All figures come from the GitHub API on the date shown.

Most discussed open issues

  • #19 For multi-step / complex tasks, how should this skill be used properly?29 comments · 2026-01-12
  • #230 Invitation: get planning-with-files verified on Sigistry (free, open source)5 comments · 2026-08-28
  • #326 Consider opt-in checkbox-only re-attestation for routine progress updates4 comments · 2026-10-17
  • #196 Add an optional hosted quick-try link for planning-with-files4 comments · 2026-07-08
  • #380 SKILL.md is about 10k tokens: Claude Code keeps the first 5,000 after compaction, and three documented mechanisms no longer exist0 comments · 2026-11-10

Issue titles are quoted from GitHub. Open the link to check whether a problem still applies to the version you use.

05

Compatibility

agent-skills
Requires a compatible Agent Skills host
Verified via docs
06

Quick start

1
$ npx skills add OthmanAdi/planning-with-files --skill planning-with-files
07

Use cases

↳Track a long-running coding task on disk.
↳Resume a plan after compaction or clearing context.
↳Keep research findings separate from progress updates.
08

Alternatives

⚡Top VS:
VSnuwa-skill★38.5k→VSawesome-agent-skills★37.3k→VShuashu-design★29.7k→VSobsidian-wiki★3.8k→
nuwa-skill logo
nuwa-skill★ 38.5k
你想蒸馏的下一个员工,何必是同事。蒸馏任何人的思维方式——心智模型、决策启发式、表达DNA。Distill how anyone thinks.
VSCompare→
awesome-agent-skills logo
awesome-agent-skills★ 37.3k
A curated collection of 1000+ agent skills from official dev teams and the community, compatible with Claude Code, Codex, Gemini CLI, Cursor, and more.
VSCompare→
huashu-design logo
huashu-design★ 29.7k
Huashu Design 3.0 · 在 agent 里打一句话,拿回能交付的设计:网页 / App 原型 / 可编辑 PPTX / 动画 / 信息图 · 六个候选挑三个方向 · 84 种带样张的风格库 · 越用越懂你的外观账本与设计体检 · HTML-native design skill for Claude Code, Codex, Cursor & any agent
VSCompare→
video-shotcraft logo
video-shotcraft★ 21.0k
AI video skill for Claude Code & Codex — cinematic, editable product promos with Remotion: 124 shot recipe cards, 150 motion previews, beat sync, sound design, Motion Workbench & JianYing (CapCut CN) export.
obsidian-wiki logo
obsidian-wiki★ 3.8k
Framework for AI agents to build and maintain a digital brain through Obsidian wiki | Memory System for Agents
VSCompare→
darwin-skill logo
darwin-skill★ 7.0k
达尔文.skill —— 一个让你的Skill无限进化的系统:评估→改进→测试→保留或回滚 | Autoresearch-inspired autonomous skill optimization for Claude Code. Evaluate, improve, test, keep or revert.
VSCompare→
drama-skills logo
drama-skills★ 4.4k
AI 短剧与漫剧制作 skill 合集:小说改剧本、角色设定三视图、分镜脚本、生图/生视频提示词与成片审片,适配 Claude Code / Codex 等 | Open-source agent skills for AI short dramas & motion comics
VSCompare→
huashu-motion logo
huashu-motion★ 2.9k
让你的agent一键直出商业级产品宣传片:会作曲,能指着画面改。Commercial-grade launch films by your coding agent — point at the frame to change it.
VSCompare→
See all alternatives →

Comments

Log in to leave a comment

No comments yet. Be the first!

On this page
01Features02Why choose it03Trade-offs04Maintenance check05Compatibility06Quick start07Use cases08Alternatives
OthmanAdi /
planning-with-files
↗

File-based persistent planning harness that keeps task roadmaps, findings, and progress intact across context resets

28.1k2.3kMIT
Last commit1w ago
StatusActive
CategoryMemory & Context
Contributors72
Latest releasev3.28.1
Links
Documentation↗Discussion↗Issues↗Releases↗
Cloud Infrastructure
Ad

Deploy on DigitalOcean

Host your MCP servers, Docker containers, and AI agents with $200 free credit over 60 days.

Claim $200 Free Credit
© 2026 AgentIndex.app|Built by a 10-year iOS Developer.
Best by use caseAboutContactAdvertisePrivacy PolicyTerms of UseQYSGitHubBuy me a coffee ☕

Browse by Category

MCP ServersCode AssistantWorkflow AutomationRAG / Knowledge BaseMulti-AgentBrowser AutomationLLM InfraDev ToolingObservability

Not affiliated with Anthropic, OpenAI or Microsoft.