planning-with-files
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.
Features
Why choose it
Trade-offs
Maintenance check
- 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
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.
Compatibility
Quick start
Use cases
Alternatives
Comments
No comments yet. Be the first!