planning-with-files

Name: planning-with-files
Author: OthmanAdi

Verified

Persistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard.

25,173stars

2,128forks

Python

Installation

# Add to your Claude Code skills
git clone https://github.com/OthmanAdi/planning-with-files

Getting Started

Guides for using ai agents skills like planning-with-files.

Security ReportVerified

Last scanned: 4/16/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-04-16T06:05:52.470Z",
  "semgrepRan": false,
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is planning-with-files?

planning-with-files is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by OthmanAdi. Persistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. It has 25,173 GitHub stars.

Is planning-with-files safe to use?

Yes. planning-with-files passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install planning-with-files?

Clone the repository with "git clone https://github.com/OthmanAdi/planning-with-files" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is planning-with-files written in?

planning-with-files is primarily written in Python. It is open-source under OthmanAdi on GitHub, so you can review or fork the full source.

Are there alternatives to planning-with-files?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh planning-with-files against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

beads frontend-slides

Planning with Files

📣 New in v3.0.0: opt-in autonomous and gated modes for long-running agent runs, with a completion gate that holds the agent until the plan is actually done. Existing setups change nothing.

Work like Manus — the AI agent company Meta acquired for $2 billion.

planning-with-files is a persistent file-based planning skill for AI coding agents. It keeps task_plan.md, findings.md, and progress.md on disk so the agent survives context loss, /clear, and crashes, with an opt-in completion gate that holds the agent until the plan is actually done. It installs across 60+ agents via the SKILL.md standard.

To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.

If this skill helps you work smarter, that's all I wanted.

Forks & Extensions

Fork	Author	What They Built
devis	@st01cs	Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation
multi-manus-planning	@kmichels	Multi-project support, SessionStart git sync
plan-cascade	@Taoidle	Multi-level task orchestration, parallel execution, multi-agent collaboration
agentfund-skill	@RioTheGreat-ai	Crowdfunding for AI agents with milestone-based escrow on Base
openclaw-github-repo-commander	@wd041216-bit	7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw

Used in the Wild

Project	What It Is
lincolnwan/Planning-with-files-copilot-agent	Entire Copilot agent repo built around the planning-with-files skill
cooragent/ClarityFinance	AI finance agent framework — Planning-with-Files approach directly credited
oeftimie/vv-claude-harness	Claude Code harness built on Manus-style persistent markdown planning
jessepwj/CCteam-creator	Multi-agent team orchestration skill using file-based planning

Skill Registries & Hubs

Registry	What It Is
buzhangsan/skill-manager	Bilingual (EN/中文) skill hub indexing 31,000+ Claude Code skills — planning-with-files installable one-click.

Built something? Open an issue to get listed!

See the full list of everyone who made this project better in CONTRIBUTORS.md.

Current Version: v3.4.0

Version	Highlights
v3.4.0	`PLANNING_DISABLED=1` per-invocation opt-out for one-shot sessions (closes #195, reported by @marcmuon). One-shot `codex exec` runs (CI review bots, read-only research agents, nested orchestrators) that merely shared a cwd with an incomplete plan were hijacked: plan context injected, the actual output redirected into `progress.md`, a fabricated completed phase appended to `task_plan.md`. All Codex hook entry points, the Python adapter route, and the canonical dispatchers (`inject-plan.sh`, `gate-stop.sh`, `check-complete.sh`/`.ps1`) now exit before reading the plan when `PLANNING_DISABLED=1` is set; PreToolUse keeps emitting its allow decision so tool calls proceed. The guard ships in every distributed copy including the five language variants. Also corrected `docs/codex.md`'s stale claim that the Stop hook blocks (non-blocking since v3.1.0). Suite at 200 passed.
v3.3.0	Pi extension hooks now wait for explicit user approval via `/plan-execute` (PR #193 by @Dikshj, closes #190, requested by @lazyst). The Pi extension previously activated all hooks as soon as `task_plan.md` existed, so plan injection, pre-tool recitation, post-write reminders, and auto-continue could start while the user was still reviewing a draft plan. The extension now stays passive with a status line until the active plan is approved with `/plan-execute`; approval is scoped to the current session and plan path, resets on session lifecycle events, and `/plan-execute reset` returns to passive review. A plan with a tampered SHA-256 attestation cannot be approved. Suite at 188 passed plus 21 Pi extension vitest tests.
v3.2.0	Repository health audit: session-catchup.py was non-functional on Windows, plus the "0/0 phases" false status (closes #191, addresses #103, closes #188). `session-catchup.py`, the mechanism behind "resume after `/clear`," never sanitized Windows-style paths correctly and had no explicit encoding on three reads, so it silently did nothing on Windows with no error. `inject-plan.sh`'s containment guard also silently dropped plan injection and tamper detection under 8.3 short-name or `/tmp`-aliased paths. Both fixed. Separately, `check-complete.sh`/`.ps1` and three IDE-specific Stop hooks reported a false "0/0 phases complete" for any `task_plan.md` without `### Phase` headings (#191, reported by @mixian939); fixed everywhere the pattern appeared, canonical scripts included. The `--template analytics` flag (v2.29.0) was silently falling back to default templates in every installed skill package; the analytics templates now actually ship where `init-session.sh` reads them. Merged PR #187 (@Stephen-abc: Windows test-encoding fixes, stale install-path docs) and PR #192 (@igorcosta: Autohand Code setup docs). Added `SECURITY.md` and enabled private vulnerability reporting (@AvitalAviv). Corrected `AGENTS.md`'s contributor-PR-merge guidance, which told agents to squash-merge in a way that reassigns authorship. Suite at 186 passed, 5 skipped, 0 failed.
v3.1.3	Hotfix: SKILL.md frontmatter was invalid YAML in v3.1.2. The v3.1.2 description refresh added a colon, and the English SKILL.md keep `description` unquoted, so YAML rejected the frontmatter ("mapping values are not allowed here"), which could break skill loading and the model-triggering description. v3.1.3 quotes the description (matching the already-quoted translated variants; the parsed value is identical) across the canonical file and the seven English IDE variants, and adds `tests/test_skill_frontmatter_valid.py` to validate every SKILL.md frontmatter as YAML. Suite at 184 passed.
v3.1.2	Session-catchup command works outside the plugin runtime, `.hermes` parity, refreshed skill description (PR #186 by @shunfeng8421 closes #185, reported by @xwang118). The documented Restore Context command used `${CLAUDE_PLUGIN_ROOT}`, which the plugin runtime sets only inside hook execution, so a skill-only install (`npx skills add`, Codex, Cursor) running it in a shell got an empty variable and a broken `/scripts/...` path. Now `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"` on the canonical file, `.codebuddy`, and the five language variants; the `.hermes` variant got the same fallback for `$HERMES_HOME`. The eight English SKILL.md descriptions were refreshed to lead with planning for AI coding agents and context-loss survival, with the `Use when` trigger and translated variants unchanged. Documentation only; suite at 180 passed.
v3.1.1	Codex verification command checks the canonical `hooks` feature flag (PR #184 by @Fat-Jan). The `docs/codex.md` verify bl