engineering / skill

Planning with Files

Planning skill for coding agents that keeps task_plan.md, findings.md and progress.md on disk, with lifecycle hooks that inject plan context.

Repository owner OthmanAdi

Not rated yet
0 comments

Like 0 Save

Published 11 Oct 2026Listing updated 12 Oct 2026

At a glance

Purpose: Planning skill for coding agents that keeps task_plan.md, findings.md and progress.md on disk, with lifecycle hooks that inject plan context.
Runs in: Local agent with shell
Operating systems: macOS, Linux, Windows
Needs: Runtime: Bash and Python 3.10+; Needs internet: Not stated; Needs accounts or API keys beyond your agent: Not stated
Files and data: Reads files: Yes; Writes files: Yes; Sends data to other services: Not stated
Tool type: Skill
Delivery: From GitHub
Version: Latest on the master branch
Access: Code on GitHub
Compatibility: According to the README, the skill installs through the Agent Skills standard, with native plugins for Claude Code, Codex CLI, Qoder CLI, Pi, Hermes Agent, OpenCode and DeepSeek Harness. It lists setup guides for Cursor, GitHub Copilot, Mastra Code, Gemini CLI, Kiro, Codex, CodeBuddy and FactoryAI Droid, and skill discovery paths for Continue, Pi Agent, OpenClaw, Autohand Code, Antigravity, Kilocode and AdaL CLI. A separate guide covers the BoxLite sandbox runtime.
External costs: The skill is MIT-licensed. Your coding agent or model provider may charge for usage.
Permissions: The skill acts through your coding agent with the access you give it. The README says the global skills command places the skill in ~/.agents/skills/ for OpenCode and DeepSeek Harness. The README's OpenCode route adds opencode-planning-with-files to opencode.json or ~/.config/opencode/opencode.json, and OpenCode installs the plugin on its next start. The README says OpenCode command files are copied to ~/.config/opencode/commands/ or the project's .opencode/commands/. The README says the workflow writes task_plan.md, findings.md and progress.md, plus named-plan directories, active-plan pointers, attestation and mode files, run ledgers and gate counters. The README describes lifecycle hooks that inject planning context, remind after writes and can request continuation in gated mode, with PLANNING_DISABLED=1 as an opt-out subject to its .gemini caveat. The README describes /plan-loop as a recurring planning tick and /plan-goal as continuation toward plan completion.
Usage terms: MIT License, as stated in the repository. See its LICENSE file for the exact terms.

Code on GitHub

OthmanAdi/planning-with-files

MIT

Python27,414 stars2,270 forksLast pushed 12 Oct 2026 UTC

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx sk

Topics: agent-skills autonomous-agents claude claude-code claude-code-skills claude-skills codex coding-agent

Public GitHub data fetched 13 Oct 2026 UTC · 0 days old

Skill folders in this repository (18)

Folders that contain a SKILL.md file, from GitHub's file list on 13 Oct 2026 UTC.

View on GitHub ↗

What it does

Planning with Files is a skill for AI coding agents and long-running agent tasks. According to the README, it keeps three plain markdown files in your project: task_plan.md for phases and checkboxes, findings.md for research notes and decisions, and progress.md for a session log and test results. The README says parallel tasks get their own .planning/ directories with the same three files.

The README says activated lifecycle hooks inject selected planning context, and that the skill re-reads the project files from disk after /clear or in a new session. The README says opt-in gated mode can hold the agent's stop while a phase is in progress, subject to a block cap and stall detection.

According to the README, the skill installs across many agents through the Agent Skills standard, with native plugins for Claude Code, Codex CLI, Qoder CLI, Pi, Hermes Agent, OpenCode and DeepSeek Harness. The README lists translated variants in Arabic, German, Spanish and two forms of Chinese. The README says the plan files are gitignored by default and are not archived automatically.

Who it is for

Developers who run coding agents on multi-step or long-running tasks and want the plan kept in files in the project.

Example tasks

Plan a multi-step task as phases with checkboxes in task_plan.md.
Resume a task from the plan files after /clear or in a new session.
Record research notes in findings.md and a session log in progress.md.
Run parallel tasks in separate .planning/ directories.
Install a translated variant of the skill, such as the German one.

Getting started

The README's Quick Install is npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g. Translated variants use the same command with another skill name, for example npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g for German. The README points to docs/installation.md for all install methods and to per-host setup guides. The README has the exact commands.

Limitations

The README gives host-specific plugins, setup guides and discovery paths. The README warns that skill-route installs can lack hooks when project trust is not accepted or frontmatter hooks do not register; npm installation does not register hooks on its own. The README says Pi hooks remain passive until /plan-execute approval, Cursor injects at session start, and Qoder CLI requires Bash and Python 3.10+ with IDE behaviour unverified. The README describes gated continuation as opt-in and host-dependent, with a block cap and stall detection. The README documents PLANNING_DISABLED=1 as an opt-out but says the .gemini route does not honour it. The README says parallel-write detection is advisory after a write, is not a lock or merge mechanism, and does not detect every overwritten plan, progress.md or findings.md. The README says multiple concurrent named plans require explicit selection. The README says plan files are gitignored by default and are not automatically archived; a later task overwrites the root plan. The repository can change at any time; check its README before you install.

Data practices

The README says project planning files are plain Markdown and automatic recovery reads project planning files without inspecting host session stores. The README also describes named-plan directories, attachment markers, attestation files, run ledgers, gate counters and private cache storage for repeated-view suppression. The README says explicit --metadata catchup reads same-project local session records and emits aggregate counts, while --replay can emit bounded excerpts. The README says neither catchup mode contains a network request or upload path, but output placed in model context may be sent by the host agent to its configured model provider.