$ show OthmanAdi/planning-with-files
planning-with-files is a persistent, file-based task-planning system for AI coding agents. It maintains task_plan.md, findings.md, and progress.md on disk and wires into agent lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) across Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Pi, Hermes, and a dozen other assistants, re-injecting plan context into the model's context window on every turn. Plans survive context loss, /clear, compaction, and crashes; a session-catchup mechanism recovers prior transcripts. A v3 gated mode can block the agent from stopping until plan phases complete, backed by an append-only JSONL run ledger, stall detection, and SHA-256 plan attestation that makes hooks refuse to inject tampered content. Architecturally it is a distribution hub rather than a single application: a canonical skill under skills/planning-with-files is mirrored byte-identical into 15+ IDE-specific directories, with native TypeScript plugins (OpenCode, Pi, DSH), a Python plugin (Hermes), and shell/PowerShell hook dispatchers. Plan resolution is a fail-closed chain (PLAN_ID env → .active_plan pointer → newest plan dir → legacy root) guarded by slug validation, containment checks, symlink/junction rejection, and strict PWF_PLAN_ROOT pinning. The engineering is unusually rigorous for an agent-skill repo: 400+ pytest tests, byte-parity tests between shell/PowerShell/Python/TypeScript twins, a PATH-stub BSD userland simulation to catch GNU-only flags that silently fail on macOS, and heavy Windows PowerShell 5.1 / Git Bash portability hardening. Non-obvious patterns include KV-cache-stable injection output (no timestamps or free text in summaries, wall-clock normalization to T00:00:00Z) and an mtime-keyed attestation cache for performance. The repository is a developer tool, not a data/research project; although it ships benchmark and eval documentation (assertion pass rates, recovery-turn comparisons), those are verification evidence for the skill, not analysis artifacts. It is actively maintained at v3.24.0 with recent commits, 4 open issues, and 100+ releases; technical drift is low, with the main maintainability risk being deliberate duplication across 20+ canonical mirrors, mitigated by sync-ide-folders.py and parity tests but still a possible source of silent drift.
The LLM identified 5 files worth highlighting for reuse:
Nonce-delimited, SHA-256-verified framing of untrusted file content for injection into LLM context. Refuses symlinks/junctions/reparse points, detects TOCTOU swap-after-check via lstat/inode identity, verifies regular-file reads, truncates oversized content with a truncation flag, and hashes post-normalization bytes so hosts that rewrite line endings don't break attestation. Self-contained and directly extractable for any agent tooling that must safely inject file contents into a prompt.
Deterministic plan-directory resolution chain (PLAN_ID env → .active_plan pointer → newest plan dir by mtime → legacy root) with strict slug validation, canonical containment checks under the project root, symlink/junction refusal, and fail-closed empty stdout so set -e callers never crash on ambiguity. Pure POSIX sh with trusted-Python fallbacks; tested for byte-parity against PowerShell and Python twins.
Synthesizes a deterministic, timestamp-free run summary from an append-only JSONL event ledger, designed to be KV-cache-stable: no free text, no timestamps, fixed width, phase counts only. Demonstrates the non-obvious pattern of making LLM-injected context byte-identical across repeated hook fires so prompt caches hit. Reusable for any agent system that logs events and needs a compact, cache-friendly state summary.
Novel testing pattern that replaces PATH entirely with a fake BSD userland (no realpath/readlink/flock/sha256sum; stat accepts only BSD -f '%m' forms) to catch GNU-only flags on Linux CI that would silently fail on macOS. Includes an anti-vacuity self-check asserting the stub environment is actually in effect, so the test cannot pass vacuously. Directly reusable for any shell codebase claiming macOS portability.
Performance-critical Python twin of inject-plan.sh producing byte-identical output to the shell route while cutting hook latency via an mtime-keyed SHA-cache that avoids rehashing unchanged files (~120ms vs ~800ms per fire on Windows Git Bash). Enforces deterministic output ordering and normalization for KV-cache stability. The shell/Python twin-with-parity-tests pattern is a reusable approach for cross-runtime tooling.