Planning-with-Files

What It Does

Planning-with-files is a skill that teaches AI agents to use persistent markdown files as external working memory. It implements a 3-file pattern: task_plan.md for phase tracking, findings.md for research storage, and progress.md for session logging. The skill ships lifecycle hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact) that automatically re-inject plan context before tool calls, remind the agent to update progress after writes, and verify completion before stopping. Version 3.0.0 adds two opt-in modes (autonomous and gated) with a structured JSONL ledger, nonce-based injection delimiters, and a completion gate that can block agent termination when phases remain unfinished. The skill targets developers who run complex multi-step tasks through AI coding agents and want crash-proof, resumable state on disk.

The Good

The core idea is correct and well-executed. Context windows are volatile. Agents lose goals after 50+ tool calls. Writing state to disk and re-reading it before decisions is the right fix. The 3-file pattern is minimal enough to adopt immediately and structured enough to matter. In testing, init-session.sh created all three files with sensible defaults in under a second. The check-complete.sh script accurately reported 0/5 phases complete and identified the in-progress phase by name.

155 of 157 unit tests pass. The test suite covers init-session slug mode, path resolution, attestation, ledger operations, gate behavior, hook resolver integration, script permissions, session catchup, version parity across IDE variants, and more. The two failures are a Python version issue (the repo uses X | None union syntax from Python 3.10+ but the test host runs 3.9), not a logic bug. This is one of the most thoroughly tested skills GearScope has reviewed.

Parallel plan isolation works cleanly. Running init-session.sh --autonomous "Long Research Run" created .planning/2026-06-10-long-research-run/ with isolated task_plan.md, findings.md, and progress.md. Running a second init with a different slug created a separate directory. set-active-plan.sh switched between them. resolve-plan-dir.sh correctly returned the active plan path. This is a real feature for developers juggling multiple tasks in the same repo.

Hash attestation catches tampering. After editing task_plan.md (via phase-status.sh), inject-plan.sh correctly reported [PLAN TAMPERED -- injection blocked] with both expected and actual SHA-256 hashes. Re-running attest-plan.sh restored injection. This is a meaningful security control for unattended agent loops where plan file integrity matters.

17+ platform adapters ship in-tree. Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Hermes, Kiro, Mastra, OpenCode, Pi, CodeBuddy, FactoryAI Droid, Continue, Antigravity, Kilocode, AdaL, and OpenClaw all have dedicated docs and adapter SKILL.md variants. The Hermes adapter at docs/hermes.md covers installation and plugin wiring. The repo also includes 5 language variants (English, Arabic, German, Spanish, Simplified Chinese, Traditional Chinese).

Security model is unusually thorough for a skill. Version 2.37 introduced SHA-256 attestation. Version 3 added nonce-based delimiters (per-session random strings wrapping plan data), attestation-default-on in autonomous/gated modes, user-private SHA cache (moved from /tmp to $XDG_CACHE_HOME), and realpath containment in the plan-dir resolver. The SKILL.md includes a detailed "Security Boundary" section with explicit rules about treating plan content as data, not instructions. This is more security thought than most skills ever receive.

The Bad

Hook commands in SKILL.md frontmatter are nearly unreadable. The PreToolUse hook command is a 400+ character single-line shell script that resolves paths, falls back to multiple locations, and conditionally executes. It works, but it is hostile to anyone trying to audit or modify the hooks. The Stop hook is even longer, branching into PowerShell and bash paths. Inline documentation or extracted functions would help. The repo does ship thin dispatchers (inject-plan.sh, gate-stop.sh) in the scripts directory, which partially addresses this, but the YAML still contains the full inline logic.

Python 3.10 syntax in two test files breaks on Python 3.9. The dict | None union type in test_codex_hooks.py and the Hermes plugin hooks causes collection errors on macOS, which ships Python 3.9.6. This is a minor portability gap. The fix is to use Optional[dict] from typing or add from __future__ import annotations. The actual skill scripts (all bash and PowerShell) have no Python version requirement.

The README leads with marketing, not substance. The first screen of the README is badges, a banner image, a pull-quote about Manus's $2 billion acquisition, and community fork tables. The Quick Install section does not appear until line 213. The core 3-file pattern explanation starts at line 301. For a skill this useful, the README could front-load the pattern and the install command, then add the ecosystem context below. The 509-line README is longer than some skills' entire codebase.

The gated mode completion gate only enforces on Tier 1 hosts. The docs honestly document this: Claude Code, Codex CLI, OpenAI Codex API, and Continue.dev get hard blocks (exit 2 or {"decision":"block"}), while Cursor, Pi, and Kiro get follow-up injection, and everything else gets a notification only. This is not a bug but it is a limitation worth knowing. If you run gated mode on Gemini CLI or OpenCode, the gate is advisory.

Smoke Test Results

Tested on macOS (host), aarch64. Cloned repo at v3.0.0 (commit from 2026-06-10).

Run A -- Fresh clone, no deps preinstalled

$ git clone --depth 1 https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files-review
✅ Cloned successfully

$ ls /tmp/planning-with-files-review/skills/planning-with-files/SKILL.md
✅ SKILL.md present (454 lines)

$ ls /tmp/planning-with-files-review/skills/planning-with-files/scripts/
✅ 18 scripts present (bash + PowerShell pairs)

$ ls /tmp/planning-with-files-review/skills/planning-with-files/templates/
✅ 4 templates present (task_plan, findings, progress, task_plan_autonomous)

Pass rate: 3 of 3. Basic structure verified.

Run B -- Unit test suite

$ python3 -m pytest tests/ --tb=short -q --ignore=tests/test_codex_hooks.py --ignore=tests/test_hermes_adapter.py
155 passed in 4.21s
✅ 155 tests pass

$ python3 -m pytest tests/test_codex_hooks.py tests/test_hermes_adapter.py --tb=short
2 errors (Python 3.9 union type syntax)
❌ 2 collection errors (Python 3.10+ syntax required)

Pass rate: 155 of 157. The 2 failures are a Python version compatibility issue in type annotations, not a logic bug in the skill itself.

Run C -- Functional verification (does it do what it claims?)

$ mkdir /tmp/test_pwf && cd /tmp/test_pwf
$ sh /tmp/planning-with-files-review/skills/planning-with-files/scripts/init-session.sh
Created task_plan.md, findings.md, progress.md
✅ Default init creates 3 files

$ sh .../init-session.sh --autonomous "Long Research Run"
Created .planning/2026-06-10-long-research-run/ with .mode, .nonce, .attestation, .stop_blocks
✅ Autonomous mode creates isolated plan with v3 metadata

$ sh .../init-session.sh --gated "Build Pipeline"
Created .planning/2026-06-10-build-pipeline/ with mode=autonomous gate
✅ Gated mode initializes correctly

$ sh .../set-active-plan.sh 2026-06-10-long-research-run
Active plan set to: 2026-06-10-long-research-run
✅ Plan switching works

$ sh .../resolve-plan-dir.sh
/tmp/test_pwf/.planning/2026-06-10-long-research-run
✅ Resolver returns correct plan directory

$ sh .../attest-plan.sh --show
SHA-256: 531c1cc07f11... Nonce: 1b0ecef6ff6d9317
✅ Attestation present from autonomous init

$ sh .../phase-status.sh 1 complete
Phase 1 -> complete in task_plan.md
$ sh .../inject-plan.sh --context=userprompt
[PLAN TAMPERED -- injection blocked]
expected=531c1cc... actual=3bd61c82...
✅ Tamper detection blocks injection after unattested edit

$ sh .../attest-plan.sh && sh .../inject-plan.sh --context=userprompt
===BEGIN-PLAN-DATA-1b0ecef6ff6d9317=== (full plan content follows)
✅ Re-attestation restores injection

$ sh .../ledger-append.sh progress "Test event" --agent "agent-1"
✅ Ledger append works
$ sh .../ledger-summary.sh
entries: 1, phases: 1/5 complete
✅ Ledger summary is correct

$ sh .../check-complete.sh
Task in progress (1/5 phases complete). 4 phase(s) pending.
✅ Completion check accurate

$ sh .../gate-stop.sh
Advisory message (not blocking in autonomous mode)
✅ Gate respects mode

Functional pass rate: 11 of 11. Every claimed feature tested works as documented.

What the runs tell you

The skill installs from a plain git clone with zero dependencies. All core scripts are POSIX shell with no external requirements. The v3 autonomous and gated modes create the correct metadata files, enforce attestation by default, and produce structured ledger output. The tamper detection catches real edits and blocks injection until re-attestation. Two unit test files fail on Python 3.9, which is the only portability gap found.

Setup Walkthrough

1. Install the skill: npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
2. In your project directory, start a planning session by telling your agent to use the skill, or run sh ~/.claude/skills/planning-with-files/scripts/init-session.sh directly.
3. The agent will create task_plan.md, findings.md, and progress.md in your project root.
4. For parallel tasks, use named sessions: sh .../init-session.sh "My Task Name"
5. For long autonomous runs, use sh .../init-session.sh --autonomous "Task Name" or --gated for completion gate enforcement.

Optional post-install: copy the loop.md template to ~/.claude/loop.md for planning-aware /loop behavior in Claude Code.

Alternatives

1. anthropics/skills skill-creator -- Anthropic's official skill creation framework. Focuses on authoring and evaluating skills rather than runtime planning. Pair with planning-with-files for best results.
2. microsoft/SkillOpt -- Text-space optimizer that trains reusable natural-language skills. More academic, less drop-in. Good for skill authoring research, not runtime planning.
3. TodoWrite (built into Claude Code) -- The volatile todo tool that planning-with-files explicitly replaces. Persists only within a single context window. Suitable for short tasks but loses state on /clear.