Persistent file-based planning harness for long-running coding agents

What they did

They installed the planning-with-files skill globally via the Agent Skills CLI and let its lifecycle hooks drive a three-file planning loop inside a repo. Instead of relying on a prompt the model might forget, the hook fires each turn and injects the current plan context, so the agent reads task_plan.md, appends discoveries to findings.md, and logs step status in progress.md. When the context window filled up or they ran /clear mid-task, the agent re-read the on-disk files and resumed where it left off rather than restarting. They also paired it with Anthropic Skills so the planning discipline and any domain-specific skill instructions loaded together, keeping the plan authoritative across a multi-hour refactor.

How it went

The plan survived /clear, compaction, and a crashed session; the agent picked up the same step list without re-deriving it. The repo advertises a 96.7% assertion pass rate and 3/3 blind A/B wins, and the workflow felt noticeably steadier on long tasks. Polish is high: native plugins for Claude Code, Codex CLI, and others, plus install across 60+ agents.

Worth knowing

Automatic recovery reads project files only; aggregating or replaying local agent session records needs an explicit catchup mode. Hooks must be installed per host, and stale plan files can mislead the agent if not pruned. The benchmark numbers come from the project's own evals, not an independent audit.

Wiring

Install the skill globally with the Agent Skills CLI, or use the native plugin for your host (Claude Code, Codex CLI, OpenCode, etc.). Enable the lifecycle hooks so they fire each turn and inject plan context. The skill maintains task_plan.md, findings.md, and progress.md at the project root; the agent reads them at session start and after any /clear or compaction, then writes updates as steps complete. Optionally load Anthropic Skills alongside so domain instructions and planning discipline coexist. Keep the three files in version control or gitignore them deliberately, and prune completed plans to avoid stale context.

Try it yourself

Install the planning-with-files skill for this repo (npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g), then start a multi-step task: audit the test suite, fix flaky tests, and update CI. Before touching code, create task_plan.md with numbered steps and acceptance criteria, findings.md for discoveries, and progress.md for status. After each step, update all three files. Then simulate a context reset by running /clear and confirm you can resume from the files alone without re-reading the whole repo.