OthmanAdi/planning-with-filesPublic

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.

AI summary: Persistent file-based planning for AI coding agents to enable long-running tasks and session recovery.

Stars
28.1K
+64 today
Forks
2.3K
Watchers
113
Open issues
11
Open PRs
2
Contributors
~72
Commits
624
Branches
40

ShellMITCreated Jan 3, 2026Last push 9d agoLatest release v3.28.1+132 stars this week+634 this month

Quick answers

What is planning-with-files?
Persistent file-based planning for AI coding agents to enable long-running tasks and session recovery.
What does planning-with-files do?
Planning with Files is a system that introduces persistent, markdown-based planning for AI coding assistants. It solves the problem of "context rot" where agents forget their original plan during long conversations by constantly re-injecting the plan state. It forces the agent to document its steps, read the current state, and explicitly mark tasks as complete in physical files. This provides a deterministic completion gate and allows sessions to survive context clears or crashes. It is heavily inspired by Manus-style reasoning and supports multiple environments like Claude Code and Cursor.
Who is planning-with-files for?
This tool is for developers who heavily use AI coding agents for complex, multi-step tasks. It is especially useful for those frustrated by agents losing context or hallucinating during long conversations.
How do I get started with planning-with-files?
npx @othmanadi/planning-with-files init
How popular is planning-with-files on GitHub?
OthmanAdi/planning-with-files has 28,113 stars and 2,316 forks on GitHub, and gained 132 stars in the last 7 days.
What license does planning-with-files use?
OthmanAdi/planning-with-files is released under the MIT license.

Star history

since Jul 28, 2026
010K20KJul 2026Sep 2026Oct 2026Nov 2026
28.1K stars as of Nov 17, 2026. Measured daily since Jul 28, 2026; GitHub no longer exposes earlier star timestamps.

Update history

6 recorded
  • Nov 17, 2026New release v3.28.1 (previously v3.28.0).
  • Nov 6, 2026New release v3.28.0 (previously v3.25.2).
  • Oct 30, 2026Primary language changed from Python to Shell.
  • Oct 27, 2026New release v3.25.2 (previously v3.24.1).
  • Oct 16, 2026New release v3.24.1 (previously v3.22.0).
  • Oct 10, 2026Primary language changed from Shell to Python.

Contribution activity

commits per day, last 52 weeks
NovDecJanFebMarAprMayJunJulAugSepOctNovMonWedFri2025-11-23: 0 commits2025-11-24: 0 commits2025-11-25: 0 commits2025-11-26: 0 commits2025-11-27: 0 commits2025-11-28: 0 commits2025-11-29: 0 commits2025-11-30: 0 commits2025-12-01: 0 commits2025-12-02: 0 commits2025-12-03: 0 commits2025-12-04: 0 commits2025-12-05: 0 commits2025-12-06: 0 commits2025-12-07: 0 commits2025-12-08: 0 commits2025-12-09: 0 commits2025-12-10: 0 commits2025-12-11: 0 commits2025-12-12: 0 commits2025-12-13: 0 commits2025-12-14: 0 commits2025-12-15: 0 commits2025-12-16: 0 commits2025-12-17: 0 commits2025-12-18: 0 commits2025-12-19: 0 commits2025-12-20: 0 commits2025-12-21: 0 commits2025-12-22: 0 commits2025-12-23: 0 commits2025-12-24: 0 commits2025-12-25: 0 commits2025-12-26: 0 commits2025-12-27: 0 commits2025-12-28: 0 commits2025-12-29: 0 commits2025-12-30: 0 commits2025-12-31: 0 commits2026-01-01: 0 commits2026-01-02: 0 commits2026-01-03: 2 commits2026-01-04: 0 commits2026-01-05: 0 commits2026-01-06: 0 commits2026-01-07: 0 commits2026-01-08: 9 commits2026-01-09: 7 commits2026-01-10: 6 commits2026-01-11: 1 commit2026-01-12: 0 commits2026-01-13: 0 commits2026-01-14: 0 commits2026-01-15: 0 commits2026-01-16: 1 commit2026-01-17: 9 commits2026-01-18: 2 commits2026-01-19: 0 commits2026-01-20: 12 commits2026-01-21: 2 commits2026-01-22: 4 commits2026-01-23: 0 commits2026-01-24: 1 commit2026-01-25: 1 commit2026-01-26: 4 commits2026-01-27: 4 commits2026-01-28: 1 commit2026-01-29: 0 commits2026-01-30: 0 commits2026-01-31: 0 commits2026-02-01: 0 commits2026-02-02: 0 commits2026-02-03: 2 commits2026-02-04: 10 commits2026-02-05: 1 commit2026-02-06: 6 commits2026-02-07: 0 commits2026-02-08: 4 commits2026-02-09: 4 commits2026-02-10: 1 commit2026-02-11: 0 commits2026-02-12: 0 commits2026-02-13: 0 commits2026-02-14: 0 commits2026-02-15: 0 commits2026-02-16: 0 commits2026-02-17: 0 commits2026-02-18: 0 commits2026-02-19: 0 commits2026-02-20: 0 commits2026-02-21: 4 commits2026-02-22: 2 commits2026-02-23: 0 commits2026-02-24: 1 commit2026-02-25: 9 commits2026-02-26: 4 commits2026-02-27: 3 commits2026-02-28: 5 commits2026-03-01: 0 commits2026-03-02: 0 commits2026-03-03: 2 commits2026-03-04: 4 commits2026-03-05: 2 commits2026-03-06: 3 commits2026-03-07: 0 commits2026-03-08: 0 commits2026-03-09: 0 commits2026-03-10: 0 commits2026-03-11: 1 commit2026-03-12: 0 commits2026-03-13: 0 commits2026-03-14: 1 commit2026-03-15: 0 commits2026-03-16: 2 commits2026-03-17: 0 commits2026-03-18: 0 commits2026-03-19: 6 commits2026-03-20: 11 commits2026-03-21: 0 commits2026-03-22: 4 commits2026-03-23: 0 commits2026-03-24: 2 commits2026-03-25: 0 commits2026-03-26: 0 commits2026-03-27: 0 commits2026-03-28: 0 commits2026-03-29: 0 commits2026-03-30: 0 commits2026-03-31: 0 commits2026-04-01: 0 commits2026-04-02: 0 commits2026-04-03: 0 commits2026-04-04: 0 commits2026-04-05: 0 commits2026-04-06: 3 commits2026-04-07: 4 commits2026-04-08: 2 commits2026-04-09: 6 commits2026-04-10: 0 commits2026-04-11: 0 commits2026-04-12: 0 commits2026-04-13: 0 commits2026-04-14: 0 commits2026-04-15: 7 commits2026-04-16: 1 commit2026-04-17: 1 commit2026-04-18: 0 commits2026-04-19: 0 commits2026-04-20: 3 commits2026-04-21: 5 commits2026-04-22: 0 commits2026-04-23: 0 commits2026-04-24: 0 commits2026-04-25: 0 commits2026-04-26: 0 commits2026-04-27: 0 commits2026-04-28: 0 commits2026-04-29: 3 commits2026-04-30: 0 commits2026-05-01: 4 commits2026-05-02: 0 commits2026-05-03: 0 commits2026-05-04: 0 commits2026-05-05: 1 commit2026-05-06: 0 commits2026-05-07: 0 commits2026-05-08: 0 commits2026-05-09: 0 commits2026-05-10: 0 commits2026-05-11: 0 commits2026-05-12: 0 commits2026-05-13: 0 commits2026-05-14: 1 commit2026-05-15: 2 commits2026-05-16: 1 commit2026-05-17: 0 commits2026-05-18: 0 commits2026-05-19: 0 commits2026-05-20: 0 commits2026-05-21: 2 commits2026-05-22: 2 commits2026-05-23: 0 commits2026-05-24: 2 commits2026-05-25: 3 commits2026-05-26: 5 commits2026-05-27: 0 commits2026-05-28: 0 commits2026-05-29: 0 commits2026-05-30: 1 commit2026-05-31: 0 commits2026-06-01: 0 commits2026-06-02: 0 commits2026-06-03: 0 commits2026-06-04: 0 commits2026-06-05: 0 commits2026-06-06: 0 commits2026-06-07: 0 commits2026-06-08: 0 commits2026-06-09: 15 commits2026-06-10: 6 commits2026-06-11: 0 commits2026-06-12: 0 commits2026-06-13: 5 commits2026-06-14: 0 commits2026-06-15: 2 commits2026-06-16: 3 commits2026-06-17: 0 commits2026-06-18: 0 commits2026-06-19: 0 commits2026-06-20: 0 commits2026-06-21: 0 commits2026-06-22: 0 commits2026-06-23: 0 commits2026-06-24: 0 commits2026-06-25: 0 commits2026-06-26: 0 commits2026-06-27: 1 commit2026-06-28: 0 commits2026-06-29: 0 commits2026-06-30: 0 commits2026-07-01: 0 commits2026-07-02: 0 commits2026-07-03: 10 commits2026-07-04: 1 commit2026-07-05: 0 commits2026-07-06: 3 commits2026-07-07: 2 commits2026-07-08: 3 commits2026-07-09: 1 commit2026-07-10: 0 commits2026-07-11: 0 commits2026-07-12: 1 commit2026-07-13: 7 commits2026-07-14: 2 commits2026-07-15: 0 commits2026-07-16: 0 commits2026-07-17: 0 commits2026-07-18: 7 commits2026-07-19: 0 commits2026-07-20: 0 commits2026-07-21: 7 commits2026-07-22: 0 commits2026-07-23: 0 commits2026-07-24: 3 commits2026-07-25: 0 commits2026-07-26: 0 commits2026-07-27: 0 commits2026-07-28: 0 commits2026-07-29: 0 commits2026-07-30: 0 commits2026-07-31: 0 commits2026-08-01: 8 commits2026-08-02: 0 commits2026-08-03: 1 commit2026-08-04: 0 commits2026-08-05: 0 commits2026-08-06: 1 commit2026-08-07: 0 commits2026-08-08: 0 commits2026-08-09: 9 commits2026-08-10: 0 commits2026-08-11: 0 commits2026-08-12: 0 commits2026-08-13: 0 commits2026-08-14: 2 commits2026-08-15: 0 commits2026-08-16: 0 commits2026-08-17: 0 commits2026-08-18: 3 commits2026-08-19: 3 commits2026-08-20: 4 commits2026-08-21: 4 commits2026-08-22: 2 commits2026-08-23: 0 commits2026-08-24: 0 commits2026-08-25: 0 commits2026-08-26: 0 commits2026-08-27: 0 commits2026-08-28: 0 commits2026-08-29: 9 commits2026-08-30: 5 commits2026-08-31: 4 commits2026-09-01: 0 commits2026-09-02: 9 commits2026-09-03: 5 commits2026-09-04: 0 commits2026-09-05: 4 commits2026-09-06: 1 commit2026-09-07: 3 commits2026-09-08: 4 commits2026-09-09: 5 commits2026-09-10: 1 commit2026-09-11: 0 commits2026-09-12: 0 commits2026-09-13: 2 commits2026-09-14: 1 commit2026-09-15: 5 commits2026-09-16: 6 commits2026-09-17: 28 commits2026-09-18: 6 commits2026-09-19: 14 commits2026-09-20: 0 commits2026-09-21: 5 commits2026-09-22: 12 commits2026-09-23: 8 commits2026-09-24: 3 commits2026-09-25: 9 commits2026-09-26: 1 commit2026-09-27: 2 commits2026-09-28: 0 commits2026-09-29: 0 commits2026-09-30: 0 commits2026-10-01: 2 commits2026-10-02: 0 commits2026-10-03: 1 commit2026-10-04: 0 commits2026-10-05: 1 commit2026-10-06: 6 commits2026-10-07: 0 commits2026-10-08: 0 commits2026-10-09: 0 commits2026-10-10: 5 commits2026-10-11: 0 commits2026-10-12: 2 commits2026-10-13: 0 commits2026-10-14: 5 commits2026-10-15: 0 commits2026-10-16: 4 commits2026-10-17: 5 commits2026-10-18: 0 commits2026-10-19: 0 commits2026-10-20: 4 commits2026-10-21: 0 commits2026-10-22: 1 commit2026-10-23: 8 commits2026-10-24: 8 commits2026-10-25: 1 commit2026-10-26: 0 commits2026-10-27: 1 commit2026-10-28: 5 commits2026-10-29: 0 commits2026-10-30: 6 commits2026-10-31: 0 commits2026-11-01: 0 commits2026-11-02: 0 commits2026-11-03: 11 commits2026-11-04: 6 commits2026-11-05: 5 commits2026-11-06: 0 commits2026-11-07: 9 commits2026-11-08: 5 commits2026-11-09: 0 commits2026-11-10: 4 commits2026-11-11: 3 commits2026-11-12: 0 commits2026-11-13: 0 commits2026-11-14: 0 commits2026-11-15: 0 commits2026-11-16: 0 commits2026-11-17: 0 commits2026-11-18: 0 commits2026-11-19: 0 commits2026-11-20: 0 commits2026-11-21: 0 commits
595 commits in the last yearLessMore

Signals and awards

derived from tracked data
  • Widely adopted

    28,113 stars

  • Permissive license

    MIT

  • Continuous integration

    Automated checks passing

  • Repeat trending

    7 trending appearances

What planning-with-files does

Planning with Files is a system that introduces persistent, markdown-based planning for AI coding assistants. It solves the problem of "context rot" where agents forget their original plan during long conversations by constantly re-injecting the plan state. It forces the agent to document its steps, read the current state, and explicitly mark tasks as complete in physical files. This provides a deterministic completion gate and allows sessions to survive context clears or crashes. It is heavily inspired by Manus-style reasoning and supports multiple environments like Claude Code and Cursor.

This tool is for developers who heavily use AI coding agents for complex, multi-step tasks. It is especially useful for those frustrated by agents losing context or hallucinating during long conversations.

  • Persistent file storage: Saves execution plans directly to the filesystem as markdown files.
  • Context rot prevention: Constantly re-injects the current plan state to maintain agent focus.
  • Session recovery: Allows agents to resume long-running tasks exactly where they left off after a crash.
  • Deterministic completion: Requires agents to explicitly update physical files to progress through steps.
  • Multi-agent support: Works across 60+ agents including Claude Code, Cursor, and OpenCode.

Where teams use it

Managing complex refactors

Guide an AI agent through a multi-step codebase refactor without it losing track of the goal.

Recovering from token limits

Clear the conversation context and have the agent seamlessly resume from the persistent plan file.

Auditing agent decisions

Review the generated markdown files to understand exactly how the agent broke down a task.

Enforcing structured reasoning

Force the AI to outline its approach before writing code, reducing hallucinations and errors.

Getting started: npx @othmanadi/planning-with-files init

README

master branch
PWF: Every task. Every step. Three planning files on a brass-inlaid base beneath an engraved arch

Planning with Files   Trendshift: #1 Repository of the Day across all languages

The planning skill your agent cannot ignore.
Not a prompt it might follow. A hook that fires every turn, a plan on disk that survives /clear, and 3 out of 3 blind A/B wins to show it works.

Sponsors & supporters

Scrape.ly by evomi: get structured data from Google, LinkedIn, Instagram, TikTok, Reddit and 500+ more. Connect to your Agent now.
Your agent keeps the plan. Scrape.ly brings the web data.

Swiftproxy logo
Swiftproxy · Residential proxies for browser automation.

OSS code review support: CodeRabbit’s open-source program.


Your agent's context window dies. The plan does not.

Persistent file-based planning for AI coding agents and long-running agent tasks: the skill keeps task_plan.md, findings.md, and progress.md on disk. Activated lifecycle hooks inject selected project planning context, so the plan survives context loss, /clear, crashes, and compaction. Automatic recovery reads project files only. Reading same-project local agent session records for aggregate counts or bounded replay requires an explicit catchup mode. Installs across 60+ agents via the Agent Skills standard, with native plugins for Claude Code, Codex CLI, Qoder CLI, Pi, Hermes Agent, OpenCode and DeepSeek Harness.

Stars Latest release skills.sh installs Skills Playground installs Downloads Closed issues Closed PRs

Benchmark: 96.7 percent assertion pass rate with skill Blind A/B: 3 of 3 wins MIT license

See it survive /clear · Install · Long-running tasks · First-class hosts

Open the Commands, Multi-agent runs, Benchmarks & more section below for the reference · Full install guide

Contributors

Code, documentation, and issue contributors. Select a portrait to open a GitHub profile or archived credit. Full credits.

@MannXo @winxtxrgit @EmadMokhtar @MbappeWU @Vyzygota @littleblacklb @Amiirhosseini @AvitalAviv @DorianZheng @dubes394 @dylanpulver @Enard52 @JianweiWangs @lazyst @loarland @luyanfeng @marcmuon @mfehlhaber @mixian939 @msuadOf @mtuwei @nazeshinjite @sean3808 @shouldnotappearcalm @st01cs @tingles2233 @Whxuan0701 @wqh17101 @kaichen @fuahyo @lasmarois @aimasteracc @SaladDay @murphyXu @ZWkang @EListenX @lincolnwan @ciberponk @ttttmr @mvanhorn @ebrevdo @bailob @as992949791 @shuoxuekeji @Jinzy @SomSamantray @mmychu @ericshunhinglee-cloud @ShaunLinTW @TayfurYldz @kuei51307-hub @Dphoshoba @sunznx @hzura @wangxiaodong1021 @sortakool @lowmiaq-gmail @webwww123 @killianMei @GlitterKill @seathatflowsinourveins @fd44fdg @jschmied @yolo0731 @ziyu4huang @kcinzgg @mahdiit @Dikshj @2023Anita @GongYuanCaiJi @Fat-Jan @shunfeng8421 @Skulli485 @carterusedulm2-maker @gauravvojha @CleanDev-Fix @bmyury @oaabahussain @gavinlinasd @xiaolai @githubYiheng @09ashishkapoor @shawnli1874 @Leon-Algo @YSAA1 @kevinaimonster @wd041216-bit @popey @jonthebeef @codelyc @Guozihong @fahmyelraie @olgasafonova @AZLabsAI @raykuo998 @gydx6 @waynelee2048 @tobrun @markocupic024 @tt-a1i @Emin017 @TomXPRIME @DLI1996 @Stephen-abc @igorcosta @Yigtwxx @RioTheGreat-ai @kmichels @voidborne-d @Kiddo4993

🌍 Built with Planning with Files

Forks & Extensions

Fork Author What They Built
devis @st01cs Interview-first workflow, /devis:intv and /devis:impl commands, guaranteed activation
multi-manus-planning @kmichels Multi-project support, SessionStart git sync
plan-cascade @Taoidle Multi-level task orchestration, parallel execution, multi-agent collaboration
agentfund-skill @RioTheGreat-ai Crowdfunding for AI agents with milestone-based escrow on Base
openclaw-github-repo-commander @wd041216-bit 7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw
planning-with-sysspec @tianshan Spec-first extension adding structured module specifications, spec deltas and validation matrices (source)

Used in the Wild

Project What It Is
lincolnwan/Planning-with-files-copilot-agent Entire Copilot agent repo built around the planning-with-files skill
cooragent/ClarityFinance AI finance agent framework, Planning-with-Files approach directly credited
oeftimie/vv-claude-harness Claude Code harness built on Manus-style persistent markdown planning
jessepwj/CCteam-creator Multi-agent team orchestration skill using file-based planning
smallnest/langgraphgo: Manus Agent Go implementation of the planning-with-files pattern with persistent task plans, research notes and output files (source)
a5c-ai/babysitter SDK planning, execution, session-recovery and verification processes adapted from planning-with-files (source)

Skill Registries & Hubs

Registry What It Is
buzhangsan/skill-manager Bilingual (EN/中文) Claude Code skill hub; planning-with-files installable one-click

Bundled snapshots & adaptations

Project Verified relationship
benchflow-ai/skillsbench Bundles planning-with-files v2.1.2 in its organize-messy-files benchmark task (snapshot)
sickn33/agentic-awesome-skills Cross-agent skill collection shipping an adapted planning-with-files copy, originally imported at v2.1.2 (import)

Built something? Open an issue to get listed!

Full list of everyone who made this project better: CONTRIBUTORS.md.

Quick Install

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

All install methods: docs/installation.md.


Before and after /clear

Every coding agent loses its working memory when the context window resets. The plan does not have to die with it.

Illustrated workflow: planning files preserve the task state through a context reset

Built for long-running agent tasks

Important

Most harnesses ship a to-do list that lives inside the context window. planning-with-files ships a plan that lives on disk, is re-injected every turn, is hash-attested, and can hold the agent's stop until the plan reports complete.

That is the difference between an agent that forgets after /clear, compaction or a crash and one that resumes at the current phase. In the project's own measurements the plan on disk turned a 13.3-turn re-orientation into 5.0 turns, and the skill won 3 of 3 blind A/B comparisons (numbers and limits). Every mechanism below is a file on disk plus a hook, so it works the same on hour ten as on turn one.

The 3-file pattern

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

→ Anything important gets written to disk.

The skill keeps your plan, findings, and progress in your project:

your-project/
├── task_plan.md   ← phases + checkboxes; the resume point after /clear
├── findings.md    ← research notes and decisions, appended as you go
└── progress.md    ← session log and test results

Parallel tasks get isolated directories instead: .planning/YYYY-MM-DD-slug/ with the same three files, selected via .active_plan (v2.36.0+). Plain markdown, gitignored by default, no runtime state anywhere else.

The pattern is the one Manus described before Meta acquired it for $2 billion on December 29, 2025, eight months and $100M+ of revenue after launch:

"Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables." — Manus AI

First-class hosts: native plugins

Tip

Native integrations load planning context, provide progress reminders and support a completion gate. Commands and model-callable tools depend on the host; Qoder CLI loads the skill and lifecycle hooks without the Claude-specific command prompts. The platform setup guides describe each integration and the standard Agent Skills routes.

🌐 Available in 5 other languages

🇸🇦 العربية / Arabic

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

🇩🇪 Deutsch / German

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

🇪🇸 Español / Spanish

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g

🇨🇳 中文版 / Chinese (Simplified)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

🇹🇼 正體中文版 / Chinese (Traditional)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

These are real translations, not an English body with a translated description: the SKILL.md prose, the templates, and the user-facing output of check-complete, init-session and session-catchup are all localized. The status tokens stay literal English (**Status:** complete) on purpose, because check-complete.sh matches them with grep -F, so translating them would disable the completion gate.

Since v3.10.0 the variants also ship the full script surface: attestation, the Stop gate, the ledger, phase status and plan-doctor used to be canonical-only, which quietly made every non-English install a subset install. Full details, including what changed on the plugin route in v3.11.0, are in docs/languages.md.

They live under skills/i18n/, one directory deeper than the canonical skill. The install commands above are unchanged, because npx skills add resolves --skill by skill name across the whole repository. The Claude Code plugin scan reads skills/*/SKILL.md without recursing, so the plugin route registers the canonical skill alone and no longer carries five extra descriptions in every session's system prompt. On that route the /plan-ar, /plan-de, /plan-es, /plan-zh and /plan-zht commands read the translated skill from disk instead of invoking it by name.

Enhanced Support: per-IDE setup guides
IDE Installation Guide Integration
Claude Code Installation Plugin + SKILL.md + Hooks
Cursor Cursor Setup Skills + hooks.json
GitHub Copilot Copilot Setup Hooks (incl. errorOccurred)
Mastra Code Mastra Setup Skills + Hooks
Gemini CLI Gemini Setup Skills + Hooks
Kiro Kiro Setup Agent Skills
Codex Codex Setup Skills + Hooks
Qoder CLI Installation Skill + seven lifecycle hooks; Bash and Python 3.10+ required
Hermes Agent Hermes Setup Skill + native plugin (tools, /pwf, pre_llm_call, post_tool_call, pre_verify gate), CLI and Desktop
CodeBuddy CodeBuddy Setup Skills + Hooks
FactoryAI Droid Factory Setup Skills + Hooks
OpenCode OpenCode Setup Native plugin opencode-planning-with-files (chat.message injection, write reminders, compaction flush, session.idle gate, pwf_* tools, /pwf commands) + skill
DeepSeek Harness DeepSeek Harness Setup Native plugin dsh-planning-with-files (agent/pre-step injection, write reminders, post-compaction restore, agent/turn-stopping gate, pwf_* tools, /pwf commands) + skill
Standard Agent Skills: discovery paths
IDE Installation Guide Skill Discovery Path
Continue Continue Setup .continue/skills/ + .prompt files
Pi Agent Pi Agent Setup .pi/skills/ (npm package)
OpenClaw OpenClaw Setup .openclaw/skills/ (docs)
Autohand Code Autohand Code Setup ~/.autohand/skills/ or .autohand/skills/
Antigravity Antigravity Setup .agent/skills/ (docs)
Kilocode Kilocode Setup .kilocode/skills/ (docs)
AdaL CLI (Sylph AI) AdaL Setup .adal/skills/ (docs)

Note: If your IDE uses the legacy Rules system instead of Skills, see the legacy-rules-support branch.

Sandbox runtimes
Runtime Status Guide Notes
BoxLite ✅ Documented BoxLite Setup Run Claude Code + planning-with-files inside hardware-isolated micro-VMs

BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox, BoxLite's official Claude Code integration layer.

❓ FAQ

How do I stop my coding agent from losing its plan after /clear or a crash?

The plan lives on disk in task_plan.md, findings.md, and progress.md, not only in the context window. At the start of each turn the UserPromptSubmit hook re-injects selected active-plan context, and after a /clear or a new session the skill re-reads project files from disk. This automatic path does not inspect agent transcript stores.

What is the difference between planning-with-files and an agent memory tool?

Agent memory tools (vector stores, knowledge graphs) help an agent recall facts from past sessions. planning-with-files manages active execution state: the phases, status, dependencies, and completion check for the task the agent is working on right now. The problem it solves is planning continuity, not retrieval, and the two are complementary.

How does this prevent context rot?

Context rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected at the start of each turn from disk, the goals and phase status stay in the model's attention window as the conversation grows. This is an implementation of what Anthropic calls structured note-taking: write durable state to files outside the window, then read it back in when needed.

Which coding agents does this work with?

Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent, CodeBuddy, Factory, Mastra, and 70+ others via the SKILL.md open standard (the npx skills installer alone targets 71 agents). Since v3.7.0 the repo also ships the cross-tool .agents/skills/planning-with-files/ layout in-tree, so tools that read the Agent Skills standard path natively (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the current skill from a plain git clone with no per-tool setup. Installation is one command; see Quick Install above.

How does this work with Claude Code's plan mode?

They are complementary stages, not alternatives. Plan mode is where you design and approve the approach before execution. planning-with-files persists the live execution state (phase status, findings, errors, progress) on disk while the work runs and re-injects it every turn. The handoff is one step: after accepting a plan-mode plan, tell the agent to write it into task_plan.md as phases (or invoke /plan and let the skill create the files from it), then execute in normal mode. From that point the hooks keep the phases in the attention window, and the files survive /clear, compaction, and session death.

What happens to the plan files after a task is complete?

They are working memory, not a tracked deliverable. task_plan.md, findings.md, progress.md, and the .planning/ directory are gitignored by default and are not archived automatically: the next task overwrites the root plan, and a slug directory stays in .planning/. Anything worth keeping should be promoted into code, a commit, or a doc. To set a finished named plan aside, set-active-plan.sh --archive <slug> previews the move to .planning/.archive/<slug>/ and --yes applies it; --restore <slug> previews the move back and --yes applies it the same way. With one named plan left, hooks select it automatically again. See After Completion: What Happens to the Plan Files for the full lifecycle and how to retain a completed plan.

How fast are the hooks?

One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from 2.0 to 2.4 seconds before it, and the injected plan block is KV-cache stable by construction. The plan stays in the attention window every turn, and /clear stops being fatal.

📦 Releases
Version Highlights
v3.28.2 Completes shell and native PowerShell help handling; adds recovery grader and npm README checks to pytest; documents native PowerShell fixture use and preserves trial receipts; clarifies compaction and recovery behavior (PRs #365, #366, #368, #373, #374, #375).
v3.28.1 attest-plan reports one refusal that names its cause on both routes and adds -Target on PowerShell; echoed selectors cannot forge output; init-session refuses mistyped switches; localized /plan commands follow plan selection; faster JSON listing on Git Bash (PR #353, #360, #362, #363, #364)
v3.28.0 Adds opt-in archive and restore for finished named plans (--archive / --restore, preview first, nothing deleted), so hooks select the remaining plan again; the multiple-plans notice names the command; fixes inventory timestamps, locked files, long paths, hidden folders and PowerShell output on Windows (#355).
v3.27.0 Adds optional agent-readable plan inventory (--list --json / -List -Json) with paths, phase metadata, selection uncertainty and bounded paging; aligns Claude plugin commands with selected-plan and initializer contracts (#349, #350, PR #351).
v3.26.0 Adds opt-in Claude Code subagent tool-hook isolation (PWF_SKIP_SUBAGENTS=1); fixes Codex setup, Copilot PreToolUse output and Gemini lifecycle opt-out (PRs #345, #346, #347; #348).
v3.25.2 Plan creation through the initializer and explicit format validation; Copilot context schema and Cursor selection/install fixes; optional skill-lens resume evaluation (PRs #338, #340, #341, #342).
v3.25.1 OpenCode reports current attestation validity; DSH preserves the PLAN_ID selection notice. Adds an optional skill-lens evaluation with documented limits and contributor-reported measurements (PRs #331, #333, #334).
v3.25.0 Hermes adapter 0.3.0 binds named plans per conversation, with explicit selection, successful init/file-operation binding, persistent session records and concurrent-session isolation. Existing ambiguity, admission and attestation checks remain active (#328).
v3.24.3 Pi verifies the exact plan snapshot used for context and phase counts; selected-attestation read failures stay blocking. The guide clarifies explicit re-attestation after progress edits (#326).
v3.24.2 Pi parity mode suppresses unchanged pre-tool plan views after confirmed context insertion, with visible-edit refresh, session isolation and recovery invalidation. Approval and attestation remain checked; PWF_PRETOOL=always restores prior Pi per-leaf reminders (#323, PR #324).
v3.24.1 Validate hidden adapter frontmatter, repair KiloCode resource links, and document the prerequisites and commands for all six CI suites (#314, #315, #316).
v3.24.0 Native Qoder CLI plugin with isolated hook execution and the CLI completion gate (PR #313). Claude Code refreshes PreToolUse context only when the selected view changes, with session isolation, recovery resets and an always-inject opt-out (#312).
v3.23.0 Public file-only recovery fixture with separate trial arms (#303). DSH V4 message-source compatibility (#306), resolver-based manual workflows (#300), and accurate Codex opt-out documentation (#302).
v3.22.0 OpenCode 2 support with native plugin registration, context injection, planning tools and the completion gate. OpenCode 1 remains supported; moved v2 sessions follow their current project (#298).
v3.21.0 Explicit root and named attestation targets preserve active selection and project containment (#296). PowerShell initialization retries the concurrent pointer pre-check race with bounded, validated attempts (#294).
v3.20.8 Claude Code sessions without a plan no longer end every reply with a Stop notice (#288). Cursor hooks move to the current schema with sessionStart injection (#262), Gemini CLI hooks inject through BeforeAgent and AfterTool hookSpecificOutput (#292), and both adapters' hook scripts are now executable on macOS and Linux; the Cursor stop hook stays silent once every phase is complete. PowerShell pointer replacement recovers or removes only its own ReplaceFile backup (#254).
v3.20.7 Fixes npm capability disclosure metadata and three unavailable contributor portrait endpoints. The npm package continues to ship the canonical skill and full repository README.
v3.20.6 Phase-status writers claim one lock owner even with Windows-native mkdir (#282). OpenCode, DSH and Hermes safely replace linked active pointers (#283, #284). PowerShell named plans reject read-only pointers before creation (#285), work under bracketed paths (#286), and retry transient concurrent pointer writes and inspection races (#287). The remaining ReplaceFile artifact case stays open in #254.
v3.20.5 OpenCode replay tolerates malformed parts (#273). Initialization reports attestation failures accurately (#277), analytics plans include Next Step (#279), and PowerShell denied writes fail without activating an incomplete named plan (#280).
v3.20.4 PowerShell route on OneDrive: an .active_plan pointer carrying the OneDrive Files On-Demand reparse attribute no longer counts as unsafe, so the Cursor hooks, the resolver and set-active-plan.ps1 work in projects under OneDrive (#275). The session-catchup copy guard checks tracked copies only (#274).
v3.20.3 A symlinked or junctioned directory under .planning/ is never a plan on any route: the shell counters skip it (PR #271 by @ShaunLinTW, #270), and the selection paths of the shell family plus the Codex, OpenCode and DSH counters refuse it too, so one real plan next to a linked one no longer becomes an mtime guess.
v3.20.2 Hermes plugin: Hermes 0.21.3 re-homes TERMINAL_CWD to the home directory on the first CLI turn, so the plan in the launch directory was skipped silently. The first turn now says why nothing was injected and names the PWF_PLAN_ROOT pin, /pwf-status and /pwf print the same diagnostic, and the slash commands honor the pin (#272, reported by @ericshunhinglee-cloud).
v3.20.1 Fixes four maintainer-filed issues from the v3.19.0 and v3.20.0 cycles: newline-safe shell slugs (#257, PR #266 by @TayfurYldz), attestation bound to the current project when PWF_PLAN_ROOT is inherited (#261, PR #265 by @TayfurYldz), malformed OpenCode part rows skipped by session catchup (#258, PR #263 by @ShaunLinTW), and the several-plans rule in the Hermes plugin (#264, PR #267 by @kuei51307-hub).
v3.20.0 DeepSeek Harness becomes a first-class host (closes #252, reported by @loarland): the native Cordis plugin dsh-planning-with-files injects the plan on every prompt and after compaction, reminds after writes, holds the turn boundary in gated mode, and registers /pwf, /pwf-status and the pwf_* tools; dsh plugin --profile web add dsh-planning-with-files. Cursor's native PowerShell hooks resolve named plans (PR #251 by @kuei51307-hub, item 9 of #250); the PowerShell resolver and attester run on Windows PowerShell 5.1 with a pin and in bracketed project paths; the OpenCode and DSH plugins require PLAN_ID for several named plans (the #240 rule); the README is shorter (one 3-file pattern block, a first-class hosts table, one commands collapsible).
v3.19.0 Adds PowerShell named-plan slug mode (#247), anchors session catchup only on exact planning filenames across every shipped copy (#248), and replaces active-plan pointers through the selectors with planning-root containment in both initializers (#249).
v3.18.3 Silences completed-plan notices in shared Stop gates and Codex while preserving explicit reports and gate safeguards.
v3.18.2 Isolates Python in Codex, Gemini, and Copilot shell adapters and makes IDE sync verification fail on missing canonical sources (#244, #245).
v3.18.1 Fixes active-plan display and listing for UTF-8 BOM-prefixed pointers from Windows editors and PowerShell workflows across the canonical shell helpers (#243).
v3.18.0 Lists saved plans and phase counts with --list or PowerShell -List (#242). Supports the shipped translated templates, checks project containment, and delivers the canonical helpers across IDE bundles.
v3.17.2 Fixes #241: the native Codex manifest disables legacy command migration, removing 13 redundant source-command-* skills from plugin installs. The canonical planning skill, Codex hooks, and Claude commands remain available.
v3.17.1 Fixes #240: two named plans in the same project now require PLAN_ID, even without .planning/sessions/. A shared pointer or newest-plan guess cannot redirect a Codex session across compaction. Ambiguous hooks inject no plan and Stop does not gate against a guessed plan.
v3.17.0 Every Claude Code hook fire forked about 130 processes, and under Git Bash on Windows that took 7 to 12 seconds against the 10 second hook timeout. Claude Code discarded the plan context ("UserPromptSubmit hook timed out after 10s") and every Bash, Read, Grep and Edit call waited 5 more seconds in PreToolUse before it ran. Linux and macOS never showed it because a fork costs milliseconds there. The events now run in one Python process, scripts/inject-plan.py, a byte-identical twin of the shell chain proven by a parity suite on all three CI legs, with the shell chain kept as the reference and as the fallback for hosts without Python: 0.3 s per prompt and per tool call on the reporting machine. Hook interpreters now start in isolated mode, so a repository's own secrets.py or hashlib.py is never imported by a hook. PWF_FAST_PATH=0 forces the shell chain.
v3.16.1 Attached Codex, Hermes and Pi sessions require an explicit plan when several tasks share an armed project. Standalone hooks deliver model context through the proper event fields, preserve native session identity and throttle progress reminders. Packages include the loop template and Stop dependencies; recovery and security guidance state the selected-plan and trust boundaries.
v3.16.0 The PostToolUse progress reminder was shown to you and never to Claude (closes #239, reported by @sortakool). It was emitted as systemMessage, which Claude Code delivers to the user, so a sentence addressed to the model reached the person instead, after every Write, Edit and Bash call for a whole session. Both the plugin dispatcher and the Codex adapter now emit hookSpecificOutput.additionalContext, the shape the session-start path in the same file already used. The reminder is also throttled to once per turn instead of once per tool call, and Bash is off the PostToolUse matchers so ls and git status stop tripping a "record what you changed" nudge. PreToolUse keeps Bash. Fixing this surfaced one more copy of the #237 fallback in the plugin dispatcher, now closed.
v3.15.0 A mistyped PLAN_ID used to attest and inject a different plan, and a slug plan could switch off the project's own policy (closes #237 and #238, both reported by @sortakool). An explicit PLAN_ID is now a binding in every resolver, shell, PowerShell, Hermes, OpenCode and Pi: it resolves or it stops, and every consumer that reads or writes the selected plan says which selector refused instead of quietly using the root plan. A project's root .mode is now a floor rather than a default that slug scope replaces, so creating a plan can no longer drop a committed attestation requirement or completion gate; a slug may raise strictness, never lower it. Also fixes plan-doctor.sh reporting PASS injection: emits plan context on a state where nothing was injected at all (closes #236): classification branches on the ===BEGIN-PWF-DATA framing rather than substring-matching control strings against the plan body, so a plan quoting one of them no longer trips a false tamper warning and a reworded banner degrades to a warning instead of a silent PASS. 30 new tests, each with its own control arm.
v3.14.0 OpenCode becomes a first-class host through its own plugin system (closes #235, reported by @luyanfeng). New npm plugin opencode-planning-with-files: chat.message injects the framed plan on every turn, tool.execute.after reminds after writes, experimental.session.compacting keeps the plan pointer and attestation in the summary, and session.idle runs the completion gate in gated mode by re-prompting the session (Tier 2). Tools pwf_init, pwf_status, pwf_check; commands /pwf, /pwf-status. Same resolver, ambiguity rule, gate table and frame format as the shell route, 22 Vitest tests, verified live in OpenCode 1.18.21. docs/opencode.md now names the real install path (npx skills add -g lands in ~/.agents/skills/, which OpenCode reads) and the tier tables stop crediting OpenCode with hooks it never ran.
v3.13.0 Hermes Agent becomes a first-class host, CLI and Desktop. The native plugin now resolves .planning/<slug>/ plans (the old adapter only saw a root task_plan.md), honours PLAN_ID, PWF_PLAN_ROOT and PLANNING_DISABLED, registers /pwf, /pwf-status and /plan-status (the shipped Markdown command files were never loaded by Hermes), bundles the skill, creates gated and autonomous plans with attestation from /pwf --gated <name>, and answers Hermes' pre_verify hook with the completion gate. Verified in a live Hermes 0.19.1 plugin manager; the Hermes skills-guard scanner rates the bundle SAFE. Native Windows path fix (%LOCALAPPDATA%\hermes). README reorganized: install and platforms first, proof and reference at the bottom, nothing removed.
v3.12.1 Attestation now stays in slug mode when the helper runs inside .planning/<slug>/ (fixes #234, reported by @sortakool). The shell and PowerShell helpers update the slug's .attestation instead of creating a legacy .plan-attestation, and invalid explicit selectors stop without falling back to another local plan. PowerShell regression coverage exercises attest, show, and clear from the nested directory. The release also restores macOS system-alias handling for the Codex and Hermes context readers and keeps unsafe active-plan pointers from falling back to an unrelated legacy plan.
v3.12.0 Session recovery is now consent-bound and the published planning surface is fully auditable. Automatic hooks read project planning files only. Same-project session metadata and bounded replay require explicit CLI modes, cross-project records remain quarantined, and phase-status writers fail closed when their shared lock is unavailable. Hidden template instructions were replaced with visible guidance, capability descriptions now disclose actual context and gate behavior, and the complete 29-file ClawHub stage is rebuilt and verified from canonical tracked source.
v3.11.2 Skills-only manual installs now copy one skill at the documented depth (PR #229 by @dylanpulver). The Unix and PowerShell commands name skills/planning-with-files instead of copying skills/*, so the skills/i18n/ subtree no longer lands below the loader path. Both instructions create ~/.claude/skills first, which keeps a fresh install from placing SKILL.md directly under skills/. A tracked-Markdown test rejects the old whole-directory copy shape and locks the destination-creation step.
v3.11.1 The Copilot error hook could not be parsed by a POSIX shell (PR #228 by @dylanpulver). error-occurred.sh fed its two Python helpers with <<<, a bash here-string that dash does not implement, and the suite invokes the shell hooks as sh script, so the #!/bin/bash shebang never applied. On ubuntu runners the file died at line 32 with Syntax error: redirection unexpected, and master CI had failed on that leg for five consecutive runs. Both call sites now pipe with printf '%s\n'. The sibling echo form was deliberately not copied: dash expands backslash escapes, which would have traded a loud syntax error for silent JSON corruption. No user was affected, because Copilot invokes the hook under a bash key that bypasses the shebang.
v3.11.0 The plugin registers one skill instead of six (closes #130, reported by @sean3808; implemented by @dylanpulver in PR #226). The five language variants moved from skills/planning-with-files-<lang>/ to skills/i18n/planning-with-files-<lang>/. Nothing deleted, nothing renamed, every npx skills add --skill command unchanged: Claude Code scans skills/*/SKILL.md one level without recursing, while the skills CLI resolves --skill by name across a recursive scan. Measured against the real loader, not inferred: 6 registered skills to 1, 19 components to 14, always-on cost roughly 2,254 to 1,042 tokens per session, with all thirteen slash commands intact. /plan-de and its four siblings read their translated skill from disk and state that the status tokens stay literal English, because check-complete.sh matches them with grep -F. Also fixes seven shell hooks that could emit JSON with a raw control character when run under a POSIX-mode shell on macOS.
v3.10.2 PLANNING_DISABLED=1 had never reached the GitHub Copilot or Cursor hooks (PRs #223, #222 and #224, by @Whxuan0701). Both routes read task_plan.md directly instead of dispatching to the script that carries the #195 guard, so eighteen hook entry points ignored the opt-out entirely: a one-shot task sharing a working directory with an unrelated plan had no way to detach from it. Auditing the merge found three more: the disabled PreToolUse branch answered permissionDecision: allow, so turning the skill off widened Copilot's permissions instead of staying neutral; .cursor/hooks/stop.ps1 was the last copy the #191 zero-phase guard never reached, still auto-continuing on 0/0 phases done; and error-occurred.ps1 had never logged an error on Windows because it read stdin into $input, PowerShell's automatic pipeline variable, which does not hold the assignment under -File. The opt-out tests now run every hook with the variable unset as well as set, because the disabled-only versions stayed green against a fleet gutted to emit {}. Suite 424 to 430.
v3.10.1 Codex context hooks now emit valid event JSON on Linux and macOS (fixes #220, reported by @mfehlhaber). SessionStart, UserPromptSubmit, and PreCompact use the same adapter as Windows, so planning output beginning with [ is no longer misread as malformed JSON. This release also aligns the tracked npm payload with the published 20-script package, corrects the release reference, and makes the version bumper safe to run without the gitignored ClawHub stage in a fresh clone.
v3.10.0 Two sessions sharing one plan directory could silently destroy each other's work (closes #217, reported by @dubes394). Both read task_plan.md, both write it back, and the later write discards the earlier one's phases while injection, plan-doctor and the Stop gate all read the result as an ordinary edit. Attestation could not cover it: it compares against a baseline a human approved once, not against what the hooks last observed, and it is a read side gate that cannot stop the stale write. The guard compares progress rather than hashes, because a hash comparison flags a single agent's own edit on its very next fire; checked items and completed phases only go up during normal work, so a decrease means work is gone. Verifying #130 alongside it exposed that every non-English install was a subset install, missing attestation, the Stop gate, the ledger, phase status and plan-doctor entirely, plus a Windows UTF-8 crash fix that never left the canonical skill. Closed additively, 60 files created and 0 overwritten, with the translator-owned scripts pinned so no future sync can English them. Also fixes a README top that showed five labels and no numbers on a phone. Suite 411 to 417.
v3.9.0 A Codex thread whose cwd was a shared parent injected an unrelated project's plan on every hook fire (closes #212, reported by @webwww123). Resolution was cwd relative with no notion of a thread, so the shared parent's pointer was the only one the hook could see. Adds PWF_PLAN_ROOT for an absolute plan root binding, which a cwd relative PLAN_ID slug structurally could not express, and refuses to inject when the cwd is ambiguous rather than guessing. Verifying the report exposed that PLANNING_DISABLED=1 was inoperative on eleven of thirteen install routes, that the Stop hook could never find its script on six hosts, and that eight shipped PowerShell scripts could not be parsed by Windows PowerShell 5.1 at all, leaving Cursor injection and both Chinese variants' init-session dead on Windows. Also closes #211 (a provider error queued another request into the same failing provider, and the Pi status bar stopped tracking the plan after approval) and #210 (injection determinism now asserted, five routes normalized). Suite 311 to 411.
v3.8.2 Session recovery silently found nothing for any project path containing a dot, a space, or any other non-alphanumeric character (closes #209, reported by @seathatflowsinourveins). Three copies of session-catchup.py still folded only /, \ and :, and one of them is the copy every /plugin install runs on Linux, macOS and Git Bash. Against a real store holding 89 sessions the shipped resolver produced 0 bytes where the fix produces 11336 and recovers 166 messages. Folding now counts UTF-16 code units, so emoji folder names resolve too, and a per-session cwd filter stops two projects that fold to one directory name from reading each other's transcripts. One vector table now runs across every copy, so this drift cannot come back. Suite at 311.
v3.8.1 Pi extension: plan resolution no longer depends on the live shell cwd (closes #208, reported by @fd44fdg). An agent that cd'd into a subdirectory lost the plan, recitation went dark, and the "No task_plan.md found" warning fired on every write. Resolution now anchors on the nearest ancestor with planning state, bounded by the .git repository boundary, with slug-validation and containment parity with the sh resolver; every injection states which plan it resolved (plan: <id>), making slug-over-root shadowing visible. Also: init-session heredocs never carried the v3.8.0 Next Step section; all copies fixed with an output-level regression test. Gated by an Opus adversarial pass plus a five-lens Sonnet reliability fleet.
v3.8.0 The Stop hook never fired on macOS or Linux (a dead install-path fallback stacked on PowerShell-first dispatch), and session recovery searched a project directory that does not exist for POSIX or underscore project paths; both fixed with tests that execute the hooks end to end. Opt-in structure-aware injection (PWF_INJECT=smart) keeps the active phase and decision journal in the window late in long plans. Next Step pointer in the templates, tool-result outcomes in session catchup, macOS CI leg plus a BSD-userland simulation harness, resolve-plan-dir.ps1 parity with fail-closed containment, UTF-8-safe ledger truncation, pinned line endings, and a rebuilt README with honest benchmark charts. Suite at 301.
v3.7.0 Agent Skills standard layout ships in-tree: .agents/skills/planning-with-files/ carries the full canonical surface, so tools that read the standard path natively (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the current skill from a plain git clone. Locked into the 18-entry parity set; plan-doctor.sh now ships in every synced IDE folder.
v3.6.0<

(README truncated)

View on GitHub

Recent activity

commits and pull requests

Releases and announcements

127 total
  1. `attest-plan` now reports one refusal that names its cause on both the shell and PowerShell routes, and selectors echoed in a refusal cannot forge output. ### Security - Control characters in an echoed `PLAN_ID`, `PWF_PLAN_ROOT` or target print as `?` on both routes, so a newline or escape sequence cannot print a fake status line (PR #362, #358). ### Fixed - `attest-plan` reports the multiple-plans refusal once, exits 1 and attests nothing, without the extra `No task_plan.md found` line (PR #362, #358). - `attest-plan.ps1` gains `-Target root|<plan-id>` and one-line refusals that name a rejected `PLAN_ID`, `PWF_PLAN_ROOT` or `-Target`. A nonexistent, relative or UNC pin reaches that refusal instead of throwing (PR #362, #358). - `attest-plan.sh` no longer stores a hash prefixed with a backslash when `PWF_PLAN_ROOT` is a native Windows path, which made the hook report the plan as tampered (PR #362). - `init-session` refuses unknown dash-prefixed arguments on both routes and creates nothing. `init-session.ps1` gains `-Help` and `-h`. `-?` under a native Windows PowerShell 5.1 `-File` call still prints no help, which #357 tracks (PR #360). - The localized `/plan` commands restore th

  2. ## Added - Opt-in archive and restore for named plans. `set-active-plan.sh --archive <id>` (PowerShell: `-Archive <id>`) previews the move to `.planning/.archive/<id>/`, `--yes` (`-Yes`) applies it, and `--restore <id>` moves a plan back the same way. The directory moves with its sidecars in a single rename. Nothing is deleted and nothing is archived automatically. The shared `.active_plan` pointer is cleared only when it names the archived plan, and an ID must match the directory name exactly, including case. `--list --archived` lists archived plans, and the JSON inventory reports `archived_count` (#355). - When a project holds several named plans and no `PLAN_ID` is set, hooks inject nothing. The multiple-plans notice now names the archive command. Once one named plan remains, hooks select it again without `PLAN_ID`. ## Fixed - PowerShell inventory `modified_at` values no longer shift by the local UTC offset. - The shell inventory reports a plan file held open by another process as unreadable instead of emitting invalid JSON. - PowerShell 7 lists and resolves plans whose paths reach 260 characters. - `set-active-plan.ps1 -List -Json` works inside a PowerShell session and throu

  3. Planning agents can request a bounded JSON inventory from the existing listing helpers with `--list --json` or PowerShell `-List -Json`. It includes root and named planning-file paths, availability, phase metadata, shared defaults and explicit selection uncertainty. Inventory remains read-only and runs only when requested. Claude plugin commands now follow the selected-plan and initializer contracts. The updates preserve valid pinned legacy roots, initialize from the validated project root, keep status reads compact and delegate attestation to the shipped helpers. The schema/reference is included across supported installs. Human listing, ordinary activation, hooks and model settings keep their existing behavior. This release adds no dependency or automatic cleanup. The README now opens with contributor portraits and a centered, collapsed community showcase. Five additions link to primary sources for extensions, ports, SDK adaptations and older bundled snapshots. The canonical [[email protected] npm package](https://www.npmjs.com/package/planning-with-files/v/3.27.0) is published. Its registry archive matches the audited Git-source package byte for byte. ### Thanks -

  4. ## Added Claude Code can suppress plan context and progress reminders for subagent tool calls with `PWF_SKIP_SUBAGENTS=1`. The default is unchanged. The opt-in also fails closed when the hook cannot classify its input (#348). ## Fixed - Preserve existing Codex hook registrations during setup and avoid nested hook directories (PR #345, #343). - Keep Copilot PreToolUse output neutral while using supported context events (PR #346, #344). - Honor `PLANNING_DISABLED=1` across Gemini lifecycle hooks, including SessionEnd (PR #347, #329). ## Thanks - Parman Mohammadalizadeh (@MannXo), for the Codex setup and hook-merge guidance. - WU Leizhi (@MbappeWU), for the Copilot contract correction and Gemini opt-out guards. - @mfehlhaber, for reporting the subagent context issue and requesting an opt-in setting.

  5. Plan creation now requires the bundled initializer and explicit native format validation. `check-complete.sh --validate` and PowerShell `-Validate` reject plans with no recognized phases or missing/ambiguous native phase statuses. `plan-doctor.sh` reports these problems. Validation reads the plan without rewriting it or changing attestation; ordinary advisory and gated stop behavior is preserved. The two saved blind cases that previously produced zero recognized phases were rerun with the updated skill. Both invoked the initializer, passed functional checks, and finished with five recognized, completed phases. Only these two behavioral cases were rerun. Copilot startup and post-tool context now uses the current harness's top-level `additionalContext` output. The guide explains the legacy VS Code Local migration boundary. Cursor bash hooks consistently select named plans and refuse ambiguous or invalid selection without falling back to an unrelated root plan. Cursor installation documentation preserves existing registrations and avoids nested adapter directories (PRs #340, #341, #342). The optional skill-lens evaluation now uses 0.25.0 and includes a two-session resume case. A ma

Code frequency

additions and deletions
+31.2K-31.2KWeek of 2025-12-28: +688 linesWeek of 2025-12-28: -0 linesWeek of 2026-01-04: +6,281 linesWeek of 2026-01-04: -2,347 linesWeek of 2026-01-11: +4,571 linesWeek of 2026-01-11: -190 linesWeek of 2026-01-18: +10,222 linesWeek of 2026-01-18: -3,824 linesWeek of 2026-01-25: +7,460 linesWeek of 2026-01-25: -1,608 linesWeek of 2026-02-01: +6,115 linesWeek of 2026-02-01: -2,770 linesWeek of 2026-02-08: +756 linesWeek of 2026-02-08: -10 linesWeek of 2026-02-15: +101 linesWeek of 2026-02-15: -86 linesWeek of 2026-02-22: +2,921 linesWeek of 2026-02-22: -627 linesWeek of 2026-03-01: +609 linesWeek of 2026-03-01: -121 linesWeek of 2026-03-08: +37 linesWeek of 2026-03-08: -4 linesWeek of 2026-03-15: +4,373 linesWeek of 2026-03-15: -6,558 linesWeek of 2026-03-22: +1,493 linesWeek of 2026-03-22: -223 linesWeek of 2026-03-29: +0 linesWeek of 2026-03-29: -0 linesWeek of 2026-04-05: +7,174 linesWeek of 2026-04-05: -1,087 linesWeek of 2026-04-12: +803 linesWeek of 2026-04-12: -135 linesWeek of 2026-04-19: +2,907 linesWeek of 2026-04-19: -33 linesWeek of 2026-04-26: +5,060 linesWeek of 2026-04-26: -445 linesWeek of 2026-05-03: +2,378 linesWeek of 2026-05-03: -62 linesWeek of 2026-05-10: +2,748 linesWeek of 2026-05-10: -182 linesWeek of 2026-05-17: +3,620 linesWeek of 2026-05-17: -361 linesWeek of 2026-05-24: +1,442 linesWeek of 2026-05-24: -151 linesWeek of 2026-05-31: +0 linesWeek of 2026-05-31: -0 linesWeek of 2026-06-07: +10,368 linesWeek of 2026-06-07: -809 linesWeek of 2026-06-14: +275 linesWeek of 2026-06-14: -86 linesWeek of 2026-06-21: +53 linesWeek of 2026-06-21: -21 linesWeek of 2026-06-28: +2,249 linesWeek of 2026-06-28: -116 linesWeek of 2026-07-05: +4,390 linesWeek of 2026-07-05: -125 linesWeek of 2026-07-12: +8,938 linesWeek of 2026-07-12: -387 linesWeek of 2026-07-19: +8,327 linesWeek of 2026-07-19: -1,012 linesWeek of 2026-07-26: +17,399 linesWeek of 2026-07-26: -272 linesWeek of 2026-08-02: +36 linesWeek of 2026-08-02: -20 linesWeek of 2026-08-09: +12,522 linesWeek of 2026-08-09: -152 linesWeek of 2026-08-16: +22,210 linesWeek of 2026-08-16: -21,437 linesWeek of 2026-08-23: +23,434 linesWeek of 2026-08-23: -2,835 linesWeek of 2026-08-30: +30,672 linesWeek of 2026-08-30: -8,729 linesWeek of 2026-09-06: +31,239 linesWeek of 2026-09-06: -2,224 linesWeek of 2026-09-13: +25,718 linesWeek of 2026-09-13: -4,294 linesWeek of 2026-09-20: +8,391 linesWeek of 2026-09-20: -1,762 linesWeek of 2026-09-27: +5,588 linesWeek of 2026-09-27: -1,064 linesWeek of 2026-10-04: +6,180 linesWeek of 2026-10-04: -804 linesWeek of 2026-10-11: +1,358 linesWeek of 2026-10-11: -449 linesWeek of 2026-10-18: +5,111 linesWeek of 2026-10-18: -642 linesWeek of 2026-10-25: +9,579 linesWeek of 2026-10-25: -523 linesWeek of 2026-11-01: +19,864 linesWeek of 2026-11-01: -4,569 linesWeek of 2026-11-08: +886 linesWeek of 2026-11-08: -369 linesWeek of 2026-11-15: +0 linesWeek of 2026-11-15: -0 linesDec 28, 2025Nov 15, 2026
+326.5K lines added, -73.5K removed over the last year.

Commits per week

last 52 weeks
620Week of 2025-11-23: 0 commitsWeek of 2025-11-30: 0 commitsWeek of 2025-12-07: 0 commitsWeek of 2025-12-14: 0 commitsWeek of 2025-12-21: 0 commitsWeek of 2025-12-28: 2 commitsWeek of 2026-01-04: 22 commitsWeek of 2026-01-11: 11 commitsWeek of 2026-01-18: 21 commitsWeek of 2026-01-25: 10 commitsWeek of 2026-02-01: 19 commitsWeek of 2026-02-08: 9 commitsWeek of 2026-02-15: 4 commitsWeek of 2026-02-22: 24 commitsWeek of 2026-03-01: 11 commitsWeek of 2026-03-08: 2 commitsWeek of 2026-03-15: 19 commitsWeek of 2026-03-22: 6 commitsWeek of 2026-03-29: 0 commitsWeek of 2026-04-05: 15 commitsWeek of 2026-04-12: 9 commitsWeek of 2026-04-19: 8 commitsWeek of 2026-04-26: 7 commitsWeek of 2026-05-03: 1 commitsWeek of 2026-05-10: 4 commitsWeek of 2026-05-17: 4 commitsWeek of 2026-05-24: 11 commitsWeek of 2026-05-31: 0 commitsWeek of 2026-06-07: 26 commitsWeek of 2026-06-14: 5 commitsWeek of 2026-06-21: 1 commitsWeek of 2026-06-28: 11 commitsWeek of 2026-07-05: 9 commitsWeek of 2026-07-12: 17 commitsWeek of 2026-07-19: 10 commitsWeek of 2026-07-26: 8 commitsWeek of 2026-08-02: 2 commitsWeek of 2026-08-09: 11 commitsWeek of 2026-08-16: 16 commitsWeek of 2026-08-23: 9 commitsWeek of 2026-08-30: 27 commitsWeek of 2026-09-06: 14 commitsWeek of 2026-09-13: 62 commitsWeek of 2026-09-20: 38 commitsWeek of 2026-09-27: 5 commitsWeek of 2026-10-04: 12 commitsWeek of 2026-10-11: 16 commitsWeek of 2026-10-18: 21 commitsWeek of 2026-10-25: 13 commitsWeek of 2026-11-01: 31 commitsWeek of 2026-11-08: 12 commitsWeek of 2026-11-15: 0 commitsNov 23, 2025Nov 15, 2026
595 commits in the last 52 weeks.

When work happens

weekday and hour
SunMonTueWedThuFriSat036912151821Sun 0:00 — 1 commitsSun 1:00 — 1 commitsSun 2:00 — 0 commitsSun 3:00 — 0 commitsSun 4:00 — 2 commitsSun 5:00 — 0 commitsSun 6:00 — 0 commitsSun 7:00 — 1 commitsSun 8:00 — 3 commitsSun 9:00 — 10 commitsSun 10:00 — 6 commitsSun 11:00 — 1 commitsSun 12:00 — 0 commitsSun 13:00 — 4 commitsSun 14:00 — 0 commitsSun 15:00 — 2 commitsSun 16:00 — 3 commitsSun 17:00 — 2 commitsSun 18:00 — 1 commitsSun 19:00 — 0 commitsSun 20:00 — 0 commitsSun 21:00 — 3 commitsSun 22:00 — 0 commitsSun 23:00 — 3 commitsMon 0:00 — 2 commitsMon 1:00 — 5 commitsMon 2:00 — 0 commitsMon 3:00 — 1 commitsMon 4:00 — 2 commitsMon 5:00 — 1 commitsMon 6:00 — 1 commitsMon 7:00 — 2 commitsMon 8:00 — 7 commitsMon 9:00 — 3 commitsMon 10:00 — 5 commitsMon 11:00 — 3 commitsMon 12:00 — 1 commitsMon 13:00 — 3 commitsMon 14:00 — 0 commitsMon 15:00 — 0 commitsMon 16:00 — 0 commitsMon 17:00 — 2 commitsMon 18:00 — 1 commitsMon 19:00 — 0 commitsMon 20:00 — 4 commitsMon 21:00 — 1 commitsMon 22:00 — 4 commitsMon 23:00 — 0 commitsTue 0:00 — 4 commitsTue 1:00 — 3 commitsTue 2:00 — 1 commitsTue 3:00 — 2 commitsTue 4:00 — 0 commitsTue 5:00 — 1 commitsTue 6:00 — 2 commitsTue 7:00 — 2 commitsTue 8:00 — 0 commitsTue 9:00 — 1 commitsTue 10:00 — 7 commitsTue 11:00 — 7 commitsTue 12:00 — 8 commitsTue 13:00 — 0 commitsTue 14:00 — 7 commitsTue 15:00 — 4 commitsTue 16:00 — 5 commitsTue 17:00 — 9 commitsTue 18:00 — 7 commitsTue 19:00 — 6 commitsTue 20:00 — 2 commitsTue 21:00 — 24 commitsTue 22:00 — 7 commitsTue 23:00 — 9 commitsWed 0:00 — 2 commitsWed 1:00 — 3 commitsWed 2:00 — 4 commitsWed 3:00 — 0 commitsWed 4:00 — 1 commitsWed 5:00 — 0 commitsWed 6:00 — 1 commitsWed 7:00 — 4 commitsWed 8:00 — 5 commitsWed 9:00 — 1 commitsWed 10:00 — 4 commitsWed 11:00 — 2 commitsWed 12:00 — 1 commitsWed 13:00 — 4 commitsWed 14:00 — 5 commitsWed 15:00 — 3 commitsWed 16:00 — 1 commitsWed 17:00 — 4 commitsWed 18:00 — 4 commitsWed 19:00 — 7 commitsWed 20:00 — 10 commitsWed 21:00 — 18 commitsWed 22:00 — 7 commitsWed 23:00 — 7 commitsThu 0:00 — 9 commitsThu 1:00 — 4 commitsThu 2:00 — 3 commitsThu 3:00 — 1 commitsThu 4:00 — 0 commitsThu 5:00 — 0 commitsThu 6:00 — 0 commitsThu 7:00 — 2 commitsThu 8:00 — 5 commitsThu 9:00 — 2 commitsThu 10:00 — 1 commitsThu 11:00 — 0 commitsThu 12:00 — 0 commitsThu 13:00 — 3 commitsThu 14:00 — 5 commitsThu 15:00 — 0 commitsThu 16:00 — 0 commitsThu 17:00 — 2 commitsThu 18:00 — 5 commitsThu 19:00 — 3 commitsThu 20:00 — 2 commitsThu 21:00 — 18 commitsThu 22:00 — 16 commitsThu 23:00 — 6 commitsFri 0:00 — 5 commitsFri 1:00 — 2 commitsFri 2:00 — 0 commitsFri 3:00 — 0 commitsFri 4:00 — 1 commitsFri 5:00 — 2 commitsFri 6:00 — 1 commitsFri 7:00 — 1 commitsFri 8:00 — 0 commitsFri 9:00 — 4 commitsFri 10:00 — 1 commitsFri 11:00 — 2 commitsFri 12:00 — 3 commitsFri 13:00 — 5 commitsFri 14:00 — 7 commitsFri 15:00 — 9 commitsFri 16:00 — 15 commitsFri 17:00 — 9 commitsFri 18:00 — 2 commitsFri 19:00 — 3 commitsFri 20:00 — 7 commitsFri 21:00 — 9 commitsFri 22:00 — 3 commitsFri 23:00 — 1 commitsSat 0:00 — 2 commitsSat 1:00 — 6 commitsSat 2:00 — 0 commitsSat 3:00 — 0 commitsSat 4:00 — 1 commitsSat 5:00 — 0 commitsSat 6:00 — 1 commitsSat 7:00 — 1 commitsSat 8:00 — 4 commitsSat 9:00 — 3 commitsSat 10:00 — 9 commitsSat 11:00 — 15 commitsSat 12:00 — 5 commitsSat 13:00 — 5 commitsSat 14:00 — 2 commitsSat 15:00 — 3 commitsSat 16:00 — 0 commitsSat 17:00 — 3 commitsSat 18:00 — 10 commitsSat 19:00 — 2 commitsSat 20:00 — 13 commitsSat 21:00 — 2 commitsSat 22:00 — 17 commitsSat 23:00 — 6 commits
Commit volume by weekday and hour (UTC). Larger dots mean more commits.

Who is committing

last 52 weeks
Maintainer commits454 (73%)
Community commits170 (27%)

624 commits in total over the last year.

DateListRankStars gained
Feb 3, 2026daily#24+113
Jan 15, 2026daily#21+142
Jan 14, 2026daily#15+178
Jan 13, 2026daily#11+228
Jan 12, 2026daily#18+189
Jan 11, 2026daily#25+178
Jan 9, 2026daily#7+137
  • morluto/rea

    Reverse engineer anything with agents, from app behavior down to native binaries.

    471.6K stars · TypeScript

  • mattpocock/skills

    Skills for Real Engineers. Straight from my .agents directory.

    329K stars · Shell

  • obra/superpowers

    An agentic skills framework & software development methodology that works.

    322.9K stars · Shell

  • affaan-m/ECC

    The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

    307.9K stars · JavaScript

  • NousResearch/hermes-agent

    The agent that grows with you

    265K stars · Python

  • anthropics/skills

    Public repository for Agent Skills

    198.1K stars · Python