← all repositories
OthmanAdi/planning-with-files

A $2B workflow pattern, now a bash script you can install

Claude Code skill that makes the agent write its plans to markdown files and actually stick to them.

22.8k stars Python Coding AssistantsAgents
planning-with-files
Velocity · 7d
+146
★ / day
Trend
steady
star history

What it does This is a Claude Code “skill” — essentially a bundle of markdown instructions and shell hooks — that forces the agent to maintain persistent planning documents (task_plan.md, progress.md, handoffs/<topic>.md) across sessions. The agent initializes a plan, attests it with a SHA-256 hash to detect tampering, and checks completion against the written goals. It also ships adapters for Pi, Codex, Cursor, Gemini, Kiro, and other runtimes.

The interesting bit The whole thing is glorified file I/O dressed up as a methodology. The clever part is the attestation hook: the agent hashes its own plan and later refuses to proceed if the file changed unexpectedly, which closes the “I forgot what I was doing” failure mode. There’s also slug-mode plan isolation so you can run parallel sessions without cross-contamination.

Key highlights

  • SHA-256 plan attestation with atomic temp-rename writes and optional flock locking
  • 130 tests, though 2 pre-existing Windows exec-bit failures are still skipped
  • Slash commands /plan-goal, /plan-loop, /plan-attest, /plan-status compose with Claude Code’s native primitives
  • Community forks for multi-agent orchestration, interview workflows, even milestone-based crowdfunding
  • Version parity bumper script to stop the recurring “forgot to sync the .pi adapter” regression class

Caveats

  • The README is heavy on badges and light on architecture; you piece together how it works from release notes
  • Several IDE variants lagged behind by 9–11 versions before the v2.43.0 catch-up sync
  • Windows users hit POSIX portability edge cases (shebangs, executable bits, mtime resolution fallbacks)

Verdict Grab this if you run long-running Claude Code sessions and keep finding the agent lost in the weeds. Skip it if you expected a standalone agent — it’s scaffolding, not the building.

heatdrop uses Google Analytics to see which pages get read — nothing else. Your call. How we handle data.