← Back to Skills Marketplace
Planning with files
by
Ahmad Othman Ammar Adi.
· GitHub ↗
· v3.25.0
· MIT-0
45460
Downloads
62
Stars
0
Active Installs
29
Versions
Install in OpenClaw
/install planning-with-files
Description
Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.
Usage Guidance
Prefer a release that isolates Python initialization and validates PowerShell write destinations. Until fixed, avoid initialization in untrusted projects and avoid the PowerShell phase/ledger writers. Back up existing loop.md before copying the template, and enable session replay or continued execution only when intended.
Capability Assessment
Credentials
init-session.sh imports uuid through Python -c without isolation, allowing a project-local uuid.py to execute during nonce generation. Conversely, the flagged subprocess calls use argument lists and bundled helpers; their ledger directory comes from a private temporary snapshot, not stdin. The timestamp/PID nonce fallback is predictable, although documentation acknowledges that framing is not an access-control boundary.
Install Mechanism
User-wide loop installation is explicitly documented, although the copy commands overwrite existing configuration without backup. Hook lookup checks fixed locations for this same skill, rather than enumerating peer skills. The unpinned npx command is an installation example, not automatic runtime execution.
Instruction Scope
The PowerShell phase and ledger writers implement their own resolution instead of using the validated resolver. They accept traversal paths from PLAN_ID or .active_plan, allowing writes outside the intended project, and do not honor PWF_PLAN_ROOT.
Persistence & Privilege
Hooks and planning state are disclosed; gated continuation has a default 20-block cap, stall detection, and an opt-out. The separate Python dispatcher has unchecked turn-marker creation and a shared temporary-directory fallback; the standalone shell hook uses different, guarded cache handling.
Purpose & Capability
Planning files, context recovery, and optional continuation fit the stated purpose. Automatic catchup exits before accessing session stores; explicit history modes are disclosed. No network upload operation was found.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install planning-with-files - After installation, invoke the skill by name or use
/planning-with-files - Provide required inputs per the skill's parameter spec and get structured output
Version History
v3.25.0
Synchronize the canonical skill bundle with GitHub release v3.25.0 (de837a9). Includes all 32 tracked SKILL.md, script, template, and reference files. Hermes users can install adapter 0.3.0 separately for per-conversation plan binding: https://github.com/OthmanAdi/planning-with-files/blob/v3.25.0/docs/hermes.md. This upload is the canonical skill bundle; the native Hermes adapter is a separate install.
v3.24.0
- Removed the skill-card.md file.
- No other feature changes or fixes in this version.
v3.23.0
Resolver-based manual workflows and accurate Codex opt-out documentation. Public recovery fixture remains available in the GitHub examples directory; historical measurements remain labeled.
v3.22.0
- Removed the redundant skill-card.md file.
- No user-facing feature or behavior changes; all functionality remains the same.
- Version bump to 3.22.0.
v3.20.7
- Removed sample skill-card.md file from the project.
- No functional or user-facing changes.
- Internal documentation cleanup only.
v3.20.6
- Removed the file skill-card.md.
- No functional changes to the skill's logic or documentation.
v3.20.5
- Removed the file skill-card.md from the project.
- No other changes or new features in this release.
v3.18.0
- Added new script: scripts/inject-plan.py
- Removed: skill-card.md
- Internal documentation updated to version 3.18.0
- No functional changes to hooks, behavior, or planning flow
v3.16.1
- Hooks now use a unified scripts/skill-hook.sh, replacing various script calls and event flags for simpler lifecycle handling.
- Added templates/loop.md as a new planning template.
- Removed the legacy skill-card.md file.
- Updated documentation: task planning files are now resolved per selected task directory (with PLAN_ID) instead of always defaulting to project root.
- Clarified setup and initialization steps for parallel or isolated task directories.
v3.16.0
- PostToolUse progress reminder now reaches the model instead of the user,
fires once per turn instead of once per tool call, and no longer triggers
on read-only shell commands (issue #239).
- An explicit PLAN_ID is now a binding: it resolves or nothing is injected,
never a different plan (issue #237).
- A project's root .mode is a floor a plan cannot start below, so creating a
plan can no longer drop a committed attestation requirement (issue #238).
- plan-doctor classifies injection output on the data framing, so a plan
quoting a control phrase no longer reports a false tamper warning and a
dark-hooks state no longer reports PASS (issue #236).
- Version metadata updated to 3.16.0.
v3.12.0
- Session recovery now reads only project planning files by default; local agent session history is accessed only via explicit user request with session-catchup.py.
- Added support for session-catchup.py metadata mode (counts only, never emits transcript or commands) and bounded replay mode (non-default, opt-in).
- Hooks and documentation updated to clarify there is no network upload path and that replayed excerpts are always untrusted.
- Lifecycle hooks now check for CLAUDE_PLUGIN_ROOT and exit early if set.
- Removed the sample skill-card.md file.
v3.11.2
- Removed the redundant skill-card.md file.
- No changes to functionality or documentation; disk usage slightly reduced.
v3.10.2
- Improved script and docs placement: added standalone examples.md, reference.md, and moved templates to a top-level /templates folder.
- Added new analytics-specific templates: analytics_findings.md and analytics_task_plan.md.
- Updated PowerShell and shell command logic to handle cross-platform stop hooks more robustly.
- Clarified session restoration instructions in documentation.
- Removed legacy/duplicative files from the references and root directory for cleaner structure.
v2.9.0
- Expanded Windows and Linux compatibility for the "Stop" hook with improved script selection logic.
- Environment variable now auto-detects the correct skill directory for session recovery, supporting both plugin and default install paths.
- Documentation streamlined and clarified, with updated setup and context restoration instructions.
- Added scripts/__pycache__/session-catchup.cpython-314.pyc for internal use; removed the obsolete skill-card.md file.
v3.0.0
Major update in v3.0.0: hooks migrated to external reusable shell scripts, improving modularity and maintainability.
- All bash logic for hooks moved from SKILL.md into standalone scripts in the scripts directory.
- Added new scripts: inject-plan.sh, gate-stop.sh, ledger-append.sh/ps1, ledger-summary.sh/ps1, phase-status.sh/ps1.
- PostToolUse and Stop steps now call reusable scripts instead of embedding commands.
- Obsolete/inlined content (skill-card.md) removed; new task_plan_autonomous.md template added.
- Greatly clarifies the distinction between skill assets and user project files.
vv2.42.0
No user-facing changes in this version.
- No changes to files or behavior detected.
v2.41.0
No user-facing changes in this version.
- No file changes detected.
- Functionality and interface remain the same as the previous release.
v2.40.2
No user-facing changes in this release.
- No file changes were detected between versions.
- Functionality and behavior remain unchanged.
v2.40.1
- Improved plan file resolution: now supports resolving and loading plans from .planning subdirectories with more robust logic.
- Enhanced attestation (tamper detection): SHA256 caching is used for faster plan integrity checks.
- Progress and attestation checks now work with named/scoped plans as well as root plans.
- PreToolUse and UserPromptSubmit hooks updated to always find the correct plan, even if not in root.
- No changes to external interface or required user actions.
v2.38.1
- Minor internal update: output markers in hooks changed from "---BEGIN PLAN DATA---" to "===BEGIN PLAN DATA===" for consistency.
- No changes to user workflow or visible features.
- Version bump to 2.38.1, no file changes detected.
Metadata
Frequently Asked Questions
What is Planning with files?
Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls. It is an AI Agent Skill for Claude Code / OpenClaw, with 45460 downloads so far.
How do I install Planning with files?
Run "/install planning-with-files" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Planning with files free?
Yes, Planning with files is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does Planning with files support?
Planning with files is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Planning with files?
It is built and maintained by Ahmad Othman Ammar Adi. (@othmanadi); the current version is v3.25.0.
More Skills