planning-with-files

🇸🇦 العربية / Arabic

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

🇩🇪 Deutsch / German

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

🇪🇸 Español / Spanish

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g

🇨🇳 中文版 / Chinese (Simplified)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

🇹🇼 正體中文版 / Chinese (Traditional)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

These are real translations, not an English body with a translated description: the SKILL.md prose, the templates, and the user-facing output of check-complete, init-session and session-catchup are all localized. The status tokens stay literal English (**Status:** complete) on purpose, because check-complete.sh matches them with grep -F, so translating them would disable the completion gate.

Since v3.10.0 the variants also ship the full script surface: attestation, the Stop gate, the ledger, phase status and plan-doctor used to be canonical-only, which quietly made every non-English install a subset install. Full details, including what changed on the plugin route in v3.11.0, are in docs/languages.md.

They live under skills/i18n/, one directory deeper than the canonical skill. The install commands above are unchanged, because npx skills add resolves --skill by skill name across the whole repository. The Claude Code plugin scan reads skills/*/SKILL.md without recursing, so the plugin route registers the canonical skill alone and no longer carries five extra descriptions in every session's system prompt. On that route the /plan-ar, /plan-de, /plan-es, /plan-zh and /plan-zht commands read the translated skill from disk instead of invoking it by name.

Note: If your IDE uses the legacy Rules system instead of Skills, see the legacy-rules-support branch.

BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox, BoxLite's official Claude Code integration layer.

The plan lives on disk in task_plan.md, findings.md, and progress.md, not only in the context window. At the start of each turn the UserPromptSubmit hook re-injects selected active-plan context, and after a /clear or a new session the skill re-reads project files from disk. This automatic path does not inspect agent transcript stores.

Agent memory tools (vector stores, knowledge graphs) help an agent recall facts from past sessions. planning-with-files manages active execution state: the phases, status, dependencies, and completion check for the task the agent is working on right now. The problem it solves is planning continuity, not retrieval, and the two are complementary.

Context rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected at the start of each turn from disk, the goals and phase status stay in the model's attention window as the conversation grows. This is an implementation of what Anthropic calls structured note-taking: write durable state to files outside the window, then read it back in when needed.

Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent, CodeBuddy, Factory, Mastra, and 70+ others via the SKILL.md open standard (the npx skills installer alone targets 71 agents). Since v3.7.0 the repo also ships the cross-tool .agents/skills/planning-with-files/ layout in-tree, so tools that read the Agent Skills standard path natively (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the current skill from a plain git clone with no per-tool setup. Installation is one command; see Quick Install above.

They are complementary stages, not alternatives. Plan mode is where you design and approve the approach before execution. planning-with-files persists the live execution state (phase status, findings, errors, progress) on disk while the work runs and re-injects it every turn. The handoff is one step: after accepting a plan-mode plan, tell the agent to write it into task_plan.md as phases (or invoke /plan and let the skill create the files from it), then execute in normal mode. From that point the hooks keep the phases in the attention window, and the files survive /clear, compaction, and session death.

They are working memory, not a tracked deliverable. task_plan.md, findings.md, progress.md, and the .planning/ directory are gitignored by default and are not archived automatically: the next task overwrites the root plan, and a slug directory just stops being active. Anything worth keeping should be promoted into code, a commit, or a doc. See After Completion: What Happens to the Plan Files for the full lifecycle and how to retain a completed plan. This is a deliberate default, not a missing feature; a completion-triggered archive step is a welcome opt-in extension.

One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from 2.0 to 2.4 seconds before it, and the injected plan block is KV-cache stable by construction. The plan stays in the attention window every turn, and /clear stops being fatal.

View all releases · CHANGELOG

Parallel plan isolation (.planning/YYYY-MM-DD-slug/ directories) and Codex session isolation shipped in v2.36.0. The experimental/isolated-planning branch was the earlier prototype; master is now the canonical location.

Built something? Open an issue to get listed!

Full list of everyone who made this project better: CONTRIBUTORS.md.

Everything in that table is opt-in per plan and byte-identical to the previous behavior when no mode marker is set. Details: v3 Long-Running Agent Features and docs/long-running-agent-tasks.md.

Claude Code, plugin route (ships everything: skill, hooks, slash commands):

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Every other agent, one line, 60+ agents via the Agent Skills standard:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

npm, to pin an exact version into a project or vendor it:

npm install planning-with-files

The package carries SKILL.md, scripts/ and templates/, so this is the route for locking a version into a repo's dependencies or copying the skill in yourself. It does not register hooks on its own.

Pi Coding Agent, same npm package, wired up for you (skill, extension, status bar):

pi install npm:planning-with-files

Hermes Agent (Nous Research), native plugin plus skill bundle, CLI and Desktop:

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

OpenCode, native plugin plus the skill (the npx skills add command above lands in ~/.agents/skills/, which OpenCode reads):

{ "plugin": ["opencode-planning-with-files"] }

in opencode.json or ~/.config/opencode/opencode.json; OpenCode installs it on the next start.

DeepSeek Harness (DSH), native plugin plus the skill (the npx skills add command above lands in ~/.agents/skills/, which DSH reads):

dsh plugin --profile web add dsh-planning-with-files

then restart dsh web; the same command works for the headless, sdk and acp profiles.

Under a minute. Safe to re-run. Trigger it by typing /plan (plugin) or asking the agent to "plan this task"; the skill also self-triggers on multi-step tasks.

What each route actually ships:

Skill-route installs can end up silently hook-less (project trust not accepted, or frontmatter hooks not registering on project-level installs). The hooks are the differentiating mechanism, so if they matter to you, use the plugin route, then verify with /plan-doctor. Full matrix and the two silent killers: docs/installation.md.

Install acting up? Open your agent and say: "Read docs/installation.md and docs/troubleshooting.md from OthmanAdi/planning-with-files and fix my install." Then run /plan-doctor.

Hermes needs its skill bundle from .hermes/skills/planning-with-files (hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes); OpenCode and DeepSeek Harness read the skill that npx skills add ... -g places in ~/.agents/skills/. Each host's own /plan command is never shadowed.

One skill, three integration tiers. Know what your agent gets before you install:

Per-platform setup guides, discovery paths and sandbox runtimes are in the collapsible sections below First-class hosts: native plugins.

NOTE Markdown on disk is the shared state between agents. One orchestrator owns task_plan.md and the shared summaries; every worker appends to its own ledger or assigned file. Pin each independent task with PLAN_ID before starting its host, or use separate worktrees.

• Run ledger per agent. Workers append one JSON line per event to .planning/<id>/ledger-<agent>.jsonl (ledger-append.sh); ledger-summary.sh synthesizes a fixed-shape, KV-cache-stable block from all ledgers that replaces the raw progress.md tail in autonomous and gated mode. No free text from disk reaches the model through that block.
• Plan isolation per task. init-session.sh "<name>" gives each parallel task its own .planning/YYYY-MM-DD-<slug>/ directory; PLAN_ID pins a terminal to one of them, set-active-plan.sh --list shows available plans and phase counts, and set-active-plan.sh <id> switches the shared pointer.
• Threads whose cwd is a shared parent. PWF_PLAN_ROOT=<absolute path> binds an agent thread to the project that owns the plan; an ambiguous cwd, where a nested project carries its own planning state, injects nothing rather than guessing.
• Session attachment. An .attached marker authorizes context but does not select a task. In the Codex, Hermes, Pi, and standalone hook routes, armed isolation with multiple plans requires PLAN_ID; otherwise context is refused. A project-root pin alone cannot distinguish tasks within that root.
• Parallel-write guard. The next turn warns if checked items or completed phases decrease. This is an advisory check after the write, not a lock or merge mechanism. It does not detect every overwritten plan, progress.md, or findings.md.
• Stall-aware gate. The completion gate reads the ledger, not progress.md mtime, so a worker that stopped producing events releases the stop instead of looping.
• One plan, many hosts. Claude Code, Codex, Pi, Hermes and OpenCode read the same files, the same .attestation and the same gate counters, so a plan can be handed from one agent to another mid-run.

The contract and the .mode tokens are specified in the skill itself (SKILL.md, Autonomous and Gated Modes) and in docs/long-running-agent-tasks.md.

To find a saved plan, run the installed scripts/set-active-plan.sh --list helper from your project directory, or scripts/set-active-plan.ps1 -List in PowerShell. It lists named plans under that project's .planning/ directory, with phase counts for the shipped English and translated templates. [active] marks the shared default pointer. Listing does not select a plan or attach a session; use the displayed ID as PLAN_ID before starting a concurrent task. Kiro's separate .kiro/plan layout is not part of this inventory.

The agent stops at the first rung that applies:

1. Starting work with planning-with-files? → create the three files first
2. Learned something?                     → append it to findings.md
3. Did something?                         → log it in progress.md
4. Phase done?                            → check it off in task_plan.md
5. Context died (/clear, crash)?          → hooks re-read selected project planning state
6. Every phase complete?                  → only then does the Stop gate release (gated mode)

Hooks make steps 2 to 6 mechanical rather than optional: the Claude Code plugin runs 6 lifecycle hooks, its activation-scoped standalone skill runs 5, Codex runs 7, Pi runs 8, the Hermes plugin runs 3 (pre_llm_call, post_tool_call, pre_verify), the OpenCode plugin runs 4 (chat.message, tool.execute.after, experimental.session.compacting, session.idle), and the DeepSeek Harness plugin runs 4 (agent/pre-step, session/event for the compaction end, tools/post-execute, agent/turn-stopping). Together they re-inject the plan each turn, remind after writes, and check completion before stopping.

flowchart LR
    A["agent works"] -->|"writes decisions, findings, errors"| F["task_plan.md<br/>findings.md<br/>progress.md"]
    F -->|"hooks re-inject the plan<br/>at the start of each turn"| A
    K["/clear · crash · compaction"] -.->|"wipes the context window"| A
    F ==>|"hooks re-read project planning state"| R["fresh session resumes<br/>at the current phase"]

On the Claude plugin route, startup, resume, clear, and post-compaction lifecycle events restore selected active-plan context from project files automatically. Standalone skill installs do the same after the skill is invoked for that session. Automatic hooks and bare session-catchup.py do not inspect host session stores.

Local host history is a separate explicit action:

1. session-catchup.py --metadata <project> reads same-project local session records and emits aggregate counts only. It emits no transcript, tool-command, or path bytes.
2. session-catchup.py --replay <project> emits bounded nonce-framed excerpts from same-project records. Treat those excerpts as untrusted data.
3. Neither catchup mode contains a network request or upload path. If its output is placed in model context, the host agent may send that context to its configured model provider.

Optional gated mode can request continuation only on a host that supports the required Stop behavior. It evaluates runtime state such as mode, phase status, block count, and ledger progress. It never executes a command declared in a Markdown planning file.

Keep automatic compaction enabled. The PreCompact hook flushes the planning reminder before compaction, and the plugin SessionStart path restores the active plan for the continuation.

Maintainer depth (hook architecture, dispatcher layout, parity tooling) lives in AGENTS.md and docs/.

Slash commands ship with the Claude Code plugin route (see the install matrix above).

Typing /plan prefix-matches every plan* command in autocomplete; /planning-with-files:status autocompletes as /status (the older /plan:status label predates the rename).

Install the Pi extension with pi install npm:planning-with-files; it registers these commands, typed with no /planning-with-files: prefix.

On Pi there is no /plan command to create the files; the skill creates them, then /plan-execute approves and activates the hooks. Pi plan-goal/plan-loop run their own logic, while the Claude Code commands of the same name forward to native /goal and /loop. The doctor ships as a script in every mirror since v3.7.0: run sh scripts/plan-doctor.sh directly on platforms without the command.

The OpenCode plugin ships two Markdown commands (.opencode/commands/), copied to ~/.config/opencode/commands/ or a project's .opencode/commands/.

The Hermes plugin registers these in-session commands (CLI, gateway and Desktop), typed with no prefix.

/plan on Hermes is Hermes' own bundled software-development plan skill and is left untouched.

The DSH plugin registers these in-session commands, typed with no prefix. /plan is DSH's own plan mode and is left untouched.

On the plugin route the model-invocable SKILL is planning-with-files:planning-with-files; the doubled form is the skill id, not a command you type. The five language variants live under skills/i18n/, which the plugin scan does not reach, so there is no planning-with-files:planning-with-files-de to invoke by name — reach a translation through its /plan-ar, /plan-de, /plan-es, /plan-zh or /plan-zht command, or install it as its own skill with npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g, which registers it under its own name. There is no /pwf-de and no /planning-with-files:planning-with-files-goal; /pwf is just a short alias for /plan.

The v3 line adds features aimed at long-running agentic runs. Each one is listed with the command or flag that turns it on. Without a mode marker, hooks retain the legacy content format. Since v3.24.0, Claude Code suppresses repeated unchanged PreToolUse views when session identity and private cache storage are available.

• Autonomous mode (/pwf --autonomous, or init-session.sh --autonomous): drops the per-tool-call plan recitation, keeps the turn-start injection, and turns attestation on by default.
• Gated mode (--gated): adds a Stop completion gate that blocks only when all completion conditions hold at once, so an incomplete plan alone never traps a session.
• Auto-continue on Pi (agent_end handler): re-prompts the agent up to a limit of 3 to keep an unfinished plan moving, plus an optional /plan-goal string appended to the prompt.
• Pi approval gate (/plan-execute): Pi hooks stay passive with a status line until you approve the active plan for the current session.
• Session-catchup: automatic recovery uses project planning files only. Explicit --metadata reads same-project local session records and emits aggregate counts only; explicit --replay may emit bounded nonce-framed excerpts.
• PreCompact progress flush (PreCompact hook): surfaces a reminder to flush progress before compaction completes, and prints the active Plan-SHA256 when attested.
• SHA-256 plan attestation (/plan-attest): locks task_plan.md; a tampered plan body is refused at injection.
• Run ledger: an append-only JSONL record of phase transitions that replaces the raw progress.md tail in v3 modes with a fixed-shape summary.
• Host capability tiers: hard block on Claude Code, Codex, and Continue; follow-up injection on Cursor, Pi, Kiro, Hermes Agent, and OpenCode; notify-only elsewhere.
• Per-invocation opt-out (PLANNING_DISABLED=1, v3.4.0): a one-shot session that merely shares a cwd with an incomplete plan skips all plan reading at every hook entry point. Covers the Copilot and Cursor routes since v3.10.2 and the Hermes plugin since v3.13.0; Gemini lifecycle hooks, including SessionEnd, honor it since v3.26.0.
• Absolute plan-root pin (PWF_PLAN_ROOT, v3.9.0): binds a thread to a project root by absolute path, for agent threads whose cwd is a shared parent of the project they are actually working in. Ambiguous cwds refuse to inject rather than guessing.

Pi runtime modes:

1. Create Plan First — Never start without task_plan.md
2. The 2-Action Rule — Save findings after every 2 view/browser operations
3. Log ALL Errors — They help avoid repetition
4. Never Repeat Failures — Track attempts, mutate approach

• Manus AI, for pioneering the context-engineering pattern this skill implements
• Anthropic, for Claude Code, Agent Skills, and the Plugin system
• Nous Research, for Hermes Agent and a plugin API that made native support possible
• Lance Martin, for the detailed Manus architecture analysis
• Based on Context Engineering for AI Agents

A note from the author: this project blew up in less than 24 hours, and everyone who starred, forked, shared, and shipped fixes is the reason it kept going. If the skill helps you work smarter, that is all I wanted. Thank you.

Everything below is the proof and the reference half: the benchmarks and their limits, what lands in your project and what the repository ships, and every guide in docs/. Release history and community projects sit in the collapsible sections below First-class hosts: native plugins.

Methodology note: the 96.7% figure comes from the v2.21.0 evaluation run on claude-sonnet-4-6 (2026-03-06). It measures file-pattern fidelity (does the agent create and maintain the 3-file structure), not goal-drift over long autonomous runs. Newer models and the autonomous-mode work are not yet covered by this number. Full methodology, dataset, and assertion list: docs/evals.md.

Evaluated with Anthropic's skill-creator framework: skill v2.21.0, model claude-sonnet-4-6, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.

Internal benchmark, v1 (2026-07-06). Author-run against v3.4.0, harness-authored tasks, deterministic grading, no LLM grades anything. Treat it as the project's own measurement, not an independent comparison. Full method, arms, disclosed limits, and grader validation: docs/evals.md.

Protocol: the session is hard-stopped at roughly half done, and a fresh session is told only "Continue the work in this directory." Every graded run across every arm ended pytest-green (77/77), so the difference is re-orientation cost, not correctness.

With the planning files on disk, a resume took 5.0 turns on average; a raw agent took 13.3. Planning-file recovery plus hook injection put phase state in front of the model before its first tool call, and the same run found no correctness penalty anywhere. This internal v1 used the earlier default transcript catchup; current automatic recovery is file-only and has not been re-benchmarked under the same protocol. Contributors can run that current protocol from examples/file-only-recovery/. Running the fixture is not a new measurement of the 5.0 or 13.3 figures. An animated summary lives at docs/benchmark/index.html (rendered view).

Full methodology and results · Technical write-up

What the skill writes into your project is three markdown files (see the 3-file pattern). What the repository ships:

planning-with-files/
├── skills/planning-with-files/   # canonical skill: SKILL.md, scripts/, templates/, reference.md, examples.md
├── skills/i18n/                  # 5 translated variants: -ar / -de / -es / -zh / -zht
├── .agents/skills/planning-with-files/   # Agent Skills standard path, full surface (v3.7.0+)
├── commands/                     # 13 slash commands (plugin route only)
├── scripts/ · templates/        # root-level copies for CLAUDE_PLUGIN_ROOT
├── .claude-plugin/               # plugin + marketplace manifests
├── .codex/ .cursor/ .github/ .gemini/ .kiro/ .continue/ .pi/
├── .codebuddy/ .factory/ .hermes/ .mastracode/ .opencode/   # per-IDE mirrors, parity-locked
├── .hermes/plugins/planning-with-files/   # native Hermes Agent plugin (tools, /pwf, hooks, gate)
├── .opencode/packages/opencode-planning-with-files/   # native OpenCode plugin (npm)
├── .dsh/packages/dsh-planning-with-files/             # native DeepSeek Harness plugin (npm)
├── docs/                         # 25+ guides incl. per-platform setup, evals.md, benchmark/
├── tests/                        # cross-platform pytest suite, green on Windows, Linux, and macOS CI
├── CHANGELOG.md · MIGRATION.md · SECURITY.md · CONTRIBUTING.md · CONTRIBUTORS.md
├── CITATION.cff · llms.txt · LICENSE
└── README.md

Every release maintains 20 tracked parity targets plus the gitignored ClawHub upload stage when it is present. scripts/bump-version.py updates every available target, and CI fails if a tracked variant lags. The npm package's SKILL.md is byte-identical to the canonical skill.

Contributions welcome. Start with CONTRIBUTING.md. Every shipped contribution is credited: commit authorship is preserved on merge, and contributors are listed in CONTRIBUTORS.md, the CHANGELOG Thanks section, and the release notes.

MIT License — feel free to use, modify, and distribute.

Author: Ahmad Othman Ammar Adi