Planning with Files — A Claude Code Skill Pattern

Summary

A Claude Code skill that creates three persistent markdown files at the start of execution: task_plan.md, findings.md, and progress.md. Claude reads and updates these files throughout the session, giving it constant reminders of the original plan, accumulated findings, and current progress. Unlike normal plan mode (which fades from context as the conversation grows), these files act as external memory anchors that survive the full session.

Mental model: plan mode is a sticky note on a whiteboard — it works until someone bumps the board. Planning-with-files is a binder on the desk that you physically open and check before every step. More overhead, but the plan never drifts.

Tradeoff: uses more tokens per session (repeated file reads), but reduces rework because Claude stays aligned with the original intent through the entire execution. Install via npx skills add https://github.com/othmanadi/planning-with-files.

Why This Was Bookmarked

Shared as a skill pattern to evaluate. The drift problem is real — long sessions where Claude gradually loses the thread of what it was supposed to be doing. This is a brute-force but effective mitigation.

Key Ideas

• Three-file system: task_plan.md (what to do), findings.md (what was learned), progress.md (what’s done)
• Persistence over memory: files outlast context window decay — Claude can re-read them at any point
• Token cost tradeoff: more reads per session, but fewer failed attempts and course corrections
• Skill distribution model: installable via npx skills add from a GitHub repo — lightweight sharing pattern

Connections

This is a concrete implementation of 06-reference/concepts/compounding-knowledge at the session level. The findings.md file captures learnings in real time rather than waiting for a post-mortem.

Fits our SOUL.md operating model principle of “skills first, then decide how to run them” — this is a skill that could wrap any other skill to add planning discipline.

Relates to 06-reference/2026-04-04-compound-engineering — the Plan > Work > Review > Compound loop. Planning-with-files operationalizes the “Plan” step by making it a living document rather than a one-shot prompt. The progress.md file is effectively a lightweight “Review” running continuously.

See 06-reference/concepts/skills-as-building-blocks — this is a meta-skill (a skill that enhances how other skills execute) rather than a domain-specific one. That’s a useful category to track.

The install pattern (npx skills add <repo>) connects to 06-reference/2026-04-04-superpowers-plugin-analysis — both are distribution mechanisms for Claude Code capabilities, but this is lighter weight (single skill vs. full plugin).

See also 06-reference/2026-04-04-karpathy-llm-wiki-idea-file — the idea file concept is structurally similar to findings.md. Both are append-only logs of things worth remembering.

Open Questions

• Should we adopt this pattern for our longer-running agent tasks (the 4am restart cycle, overnight builds)?
• Could we extend it to persist across sessions — e.g., findings.md lives in the vault and compounds over time?
• How does this interact with our existing CLAUDE.md instructions? Is there overlap or conflict?
• What’s the token overhead in practice? Worth benchmarking on a real task.
• Could we build our own variant that writes findings back to the vault as a compound step?