OthmanAdi
b49ea488fb
The Stop scalar never dispatched on macOS or Linux (the PowerShell branch was always selected because check-complete.ps1 ships on every platform) and was a silent no-op anywhere CLAUDE_SKILL_DIR was unset (the :- install path fallback can never substitute because the probed variable is always a non-empty string). Both the legacy completion advisory and the v3 completion gate were dead in those environments. The scalar now selects targets by file existence and dispatches by platform, PowerShell only under MINGW/MSYS/CYGWIN, sh elsewhere. Windows output is unchanged. Patched in all 14 SKILL.md variants that carry the scalar. session-catchup probed a ~/.claude/projects name that Claude Code never writes for POSIX paths (leading dash stripped) or paths containing an underscore (replaced with a dash), so recovery after /clear silently found nothing there. The mapper now probes the exact spelling first, keeps both legacy spellings for stores created by older versions, and settles ambiguity via the cwd recorded in the newest session file. Propagated to every shipped copy including the older-generation root, .hermes, and .mastracode scripts. Also: the attestation SHA cache is keyed on the absolute plan path so two projects can no longer share a slot and report a false PLAN TAMPERED; resolve-plan-dir.ps1 reaches parity with the sh resolver (slug filter, task_plan.md requirement in the newest-dir scan, fail-closed containment); ledger-append.sh no longer truncates summaries mid-codepoint (UTF-8-safe trim via iconv with a pure-sh fallback). New long-run features, all opt-in or additive: structure-aware injection (PWF_INJECT=smart or an inject-smart .mode token) keeps the active phase, phase counts, and the last three decisions in the window late in long plans; a Next Step section in both plan templates plus a sixth reboot question; session-catchup annotates tool results (ok or FAILED with the first error line) instead of only listing attempts. Infrastructure: macos-latest joins the CI matrix, a BSD-userland simulation harness runs the script fleet without realpath, readlink, flock, or sha256sum on the Linux leg, and .gitattributes pins LF for scripts. SEO surfaces: llms.txt rewritten as a Q&A page, three problem-query docs pages, plugin.json and CITATION.cff keyword hygiene. Suite grows from 217 to 301 passed, 11 skipped, on Windows and both existing CI legs; default hook output stays byte-identical to v2.43 (legacy invariant proven by the existing invariant tests).
4.6 KiB
My coding agent forgets the plan after /clear: the file-based fix
/clear empties the context window. Everything the agent knew only from the conversation is gone: the goal, the current phase, the errors it already hit. The next thing you see is the agent asking you to restate the task, then re-reading the repo to rediscover work it already finished. The fix is not a bigger window. The fix is keeping the plan somewhere /clear cannot reach: the filesystem.
This page describes the pattern planning-with-files implements. Overview: README.
Why does my agent lose the plan after /clear?
Because in-context state is volatile by design. In-context todo lists disappear on context reset, goals stated once get crowded out after 50+ tool calls, and failures that are not written down get repeated. /clear, crashes, and compaction all destroy the same thing: state that was never persisted.
Context window = RAM, filesystem = disk
The core principle, from the context-engineering pattern described in the Manus blog:
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
Applied concretely, exactly three files land in your project root:
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
Plain markdown, gitignored by default, no runtime state anywhere else. Parallel tasks get isolated directories under .planning/YYYY-MM-DD-slug/ instead.
The re-injection loop
Files on disk only help if the model actually reads them, so that step is mechanical rather than left to model discipline. A UserPromptSubmit hook re-injects the active plan from disk at the start of every turn, wrapped in ===BEGIN PLAN DATA=== and ===END PLAN DATA=== markers. Companion hooks remind the agent to update progress.md after writes and check phase completion before stopping. On Claude Code that is 5 lifecycle hooks; Codex runs 7 and Pi runs 8.
The loop means the plan is in front of the model by construction, not by hoping the model remembers to re-read it.
What recovery looks like after /clear
- The skill checks the active IDE's session store for the previous session (
~/.claude/projects/for Claude Code,~/.codex/sessions/for Codex). - It finds when the planning files were last updated.
- It extracts the conversation that happened after that point, the potentially lost context.
- It shows a catchup report; the agent then reads the three files, runs
git diff --stat, and resumes at the current phase.
A resumed session can answer the reboot questions from the files alone: where am I (current phase in task_plan.md), what is the goal (goal statement in the plan), what have I learned (findings.md), what have I done (progress.md). In the project's internal recovery benchmark (v1, author-run), a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent; method and limits in docs/evals.md.
Does this work outside Claude Code?
Yes. The skill installs across 60+ agents via the Agent Skills standard; the npx skills installer alone targets 71. Lifecycle hooks run on Claude Code, Codex, Cursor, GitHub Copilot, Kiro, and other platforms listed in the README platform table, and since v3.7.0 the repo also ships the .agents/skills/ standard layout in-tree, so tools that read that path (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the skill from a plain git clone.
For runs that go beyond a single session, see long-running agent tasks: autonomous mode, the completion gate, and the run ledger build on the same three files.
Related pages
- Claude Code lost context after compaction: how to recover and prevent it
- Long-running agent tasks: keeping a coding agent on track for hours
Install
Claude Code, plugin route (ships the skill, hooks, and slash commands):
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Every other agent, one line via the Agent Skills standard:
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
Full route matrix and verification: README and docs/installation.md.