planning-with-files

Purpose

planning-with-files is a planning skill based on Markdown files, used for AI coding agents and long-running agent tasks. The core problem it solves is: an agent's context window loses its working memory after /clear, compaction, or a crash, whereas a plan on disk does not. This skill keeps task plans, findings, and progress in Markdown files within the project, and re-injects selected planning context at the start of each conversation turn via hooks, so the plan can still be recovered after context loss.

Main capabilities

• Three-file pattern: Maintains task_plan.md, findings.md, and progress.md in the project. Parallel tasks use an isolated directory .planning/YYYY-MM-DD-slug/, containing the same three files, selected via .active_plan (v2.36.0+). Pure Markdown, gitignored by default, with no runtime state stored anywhere else.
• Re-injection every turn: The UserPromptSubmit hook re-injects the selected active plan context at the start of each turn, countering context rot.
• Crash and /clear recovery: After /clear or a new session, the skill re-reads the project files from disk. The automatic recovery path only reads project files; reading same-project local agent session records for aggregate counts or bounded replay requires explicitly enabling catchup mode.
• Deterministic completion gate: The completion gate reads the ledger rather than the modification time of progress.md, and can prevent the agent from stopping before the plan reports completion.
• Hash attestation: The plan is hash-attested.
• Multi-agent operation: The Markdown on disk is the shared state between agents. One orchestrator owns task_plan.md and the shared summary; each worker appends to its own ledger or assigned file. Each agent has a run ledger (.planning/<id>/ledger-<agent>.jsonl), and ledger-summary.sh synthesizes a fixed-shape, KV-cache-stable block from all ledgers.
• Plan isolation: init-session.sh "<name>" gives each parallel task its own .planning/YYYY-MM-DD-<slug>/ directory; PLAN_ID pins the 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.
• Parallel write protection: If checked items or completed phases decrease, the next turn emits a warning. This is an advisory post-write check, not a lock or merge mechanism.
• Stall-aware gate: The completion gate reads the ledger, so a worker that stops producing events releases the stop instead of looping.
• Multi-host sharing: 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 off from one agent to another mid-run.

Usage

Installation routes:

• Claude Code plugin route (includes skills, hooks, slash commands):

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

• Other agents, one-line command, supporting 60+ agents via the Agent Skills standard:

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

• npm, pinning the exact version to the project or vendoring it:

npm install planning-with-files

The package contains SKILL.md, scripts/, and templates/, making it suitable for locking the version into repository dependencies or copying the skill yourself. It does not register hooks by itself.

• Pi Coding Agent, the same npm package, already wired up for you (skills, extension, status bar):

pi install npm:planning-with-files

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

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

• OpenCode, native plugin plus skill (the npx skills add command installs to ~/.agents/skills/, which OpenCode reads):

"plugin": ["planning-with-files"]

In opencode.json or ~/.config/opencode/opencode.json; installed the next time OpenCode starts.

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

dsh plugin install planning-with-files

Then restart dsh web; the same command applies to the headless, sdk, and acp profiles.

Triggering: type /plan (plugin) or tell the agent to "plan this task"; the skill also self-triggers on multi-step tasks.

When to use

• Long-running agent tasks: the todo lists most toolchains provide live inside the context window, whereas planning-with-files plans live on disk, are re-injected every turn, are hash-proven, and can stop the agent from halting until the plan report is complete.
• Coding tasks that need to survive /clear, compaction, or crash recovery.
• Multi-agent runs: orchestrators, workers, and subagents share state through Markdown on disk.
• Complementary to Claude Code's plan mode: plan mode designs and approves the approach before execution, while planning-with-files persists live execution state to disk while the work runs and re-injects it every turn.

Limitations

• Plan files are working memory, not tracked deliverables. 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 the slug directory simply goes inactive. Anything worth keeping should be promoted into code, commits, or documentation.
• Skill-routed installation may silently end up without hooks (project trust not accepted, or frontmatter hooks not registered on project-level installs). Hooks are the differentiating mechanism, so if hooks matter to you, use the plugin route, then verify with /plan-doctor.
• Parallel-write protection is an advisory check, not a lock or merge mechanism, and cannot detect every overwritten plan, progress.md, or findings.md.
• The automatic recovery path does not inspect agent transcript storage; reading local agent session records for the same project requires explicit catchup mode.
• Hook performance: after the v3.6.0 optimization, one hook trigger measured 289ms wall-clock time, down from 2.0 to 2.4 seconds.
• Status tokens stay in literal English (Status: complete) because check-complete.sh matches them with grep -F, and translating them would disable the completion gate.
• If the IDE uses the legacy Rules system instead of Skills, see the legacy-rules-support branch.
• BoxLite is a sandbox runtime, not an IDE; skills are loaded through ClaudeBox (BoxLite's official Claude Code integration layer).

Supported platforms

Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent, CodeBuddy, Factory, Mastra, and 70+ more through the SKILL.md open standard. Since v3.7.0, the repository also ships an in-tree cross-tool .agents/skills/planning-with-files/ layout, so tools that natively read the Agent Skills standard path (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) can discover the current skill from a plain git clone, with no per-tool setup.

Languages

Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese translations are provided. These are real translations, not English body text plus a translation description: the SKILL.md body, the templates, and the user-visible output of check-complete, init-session, and session-catchup are all localized. They live under skills/i18n/, one directory deeper than the canonical skill. Since v3.10.0, the variants also provide the full script surface.