Planning with Files

Planning with Files is an Agent Skill that gives coding agents a durable three-file planning workflow: task_plan.md for phases and decisions, findings.md for research and discoveries, and progress.md for session logs and validation. The key value is simple: the plan lives on disk, so long coding-agent work can recover after context loss, /clear, compaction, crashes, or handoff between sessions.

Use it for multi-step implementation, debugging, migration, research, architecture, security, or operations work where the agent needs to preserve intent across many tool calls. Skip it for quick one-shot questions or trivial single-file edits.

Knowledge Freshness

Repository metadata and docs were verified on 2026-06-18. The latest release was v3.1.3, published on 2026-06-16 as a hotfix for invalid YAML frontmatter in v3.1.2. GitHub metadata reported more than 23,000 stars, active updates on 2026-06-16, an MIT license, and topics covering Claude, Codex, Cursor, agent skills, planning, autonomous agents, context engineering, and long-running agents.

The skill supports many host variants, but hook behavior depends on each host. Before relying on automation, verify the exact install path, hook feature flag, and lifecycle events for your host.

Retrieval Sources

This listing is grounded in:

• The canonical skills/planning-with-files/SKILL.md file.
• Installation, Codex setup, quickstart, workflow, eval, migration, changelog, and release documentation from the upstream repository.
• Current GitHub repository metadata and release metadata.

Core Install Paths

For Agent Skills hosts that use the skills installer:

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

For Claude Code's plugin marketplace route:

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

For Codex, install the .codex/skills/planning-with-files directory and merge the .codex/hooks.json lifecycle entries into the project or global Codex hook config. Then enable hooks:

[features]
hooks = true

Do not overwrite an existing global hook config without merging. Duplicate workspace and global hook installs can produce duplicate reminders.

Capability Scope

Core Workflow

The skill teaches the agent to create the three planning files before complex work starts, update findings after research, update progress after actions, mark phases complete, and log errors instead of repeating the same failed approach.

The core rhythm is:

1. Create or read task_plan.md, findings.md, and progress.md.
2. Break the work into phases with Status fields.
3. Write research and decisions into findings.md.
4. Write actions, test results, and errors into progress.md.
5. Before major decisions, re-read the plan.
6. Before stopping, verify that every required phase is complete.

This is useful for agents because it moves durable task state out of the context window and into project files the agent can re-read.

Codex Notes

The Codex docs describe two install scopes:

• Workspace install: commit .codex/ into the repository so the team shares the same skill and hook behavior.
• Personal install: copy the skill and hooks into ~/.codex/.

Codex hook automation requires hooks = true under [features] in ~/.codex/config.toml. The docs also mention codex_hooks = true as a deprecated alias and note that current Codex hooks documentation disables hooks on Windows.

Production Rules

Planning files are not inert notes. They are read by the agent and can be re-injected into model context by hooks. Treat them like prompt-bearing workflow state:

• Summarize untrusted web or issue content before writing it into planning files.
• Avoid storing secrets, tokens, internal incident details, customer data, or unreleased roadmap material in files that might be committed or shared.
• Review hook scripts before enabling them globally.
• Use attestation when plan integrity matters.
• Keep autonomous and gated modes opt-in until you know how the host enforces Stop behavior.

Use Cases

• Preserve context across long Claude Code, Codex, Cursor, or OpenCode coding tasks.
• Keep implementation phases, errors, and validation state visible during a migration or refactor.
• Recover a task after /clear, compaction, or a crash.
• Coordinate multiple agents or terminals through isolated .planning/ directories.
• Run research-heavy workflows where findings need to survive context loss.
• Add a completion check before an agent declares a large task done.

Source Review

Verified on 2026-06-18:

• GitHub metadata reported OthmanAdi/planning-with-files as an MIT-licensed Python repository with the description Persistent file-based planning for AI coding agents and long-running agentic tasks, latest release v3.1.3 published on 2026-06-16, and more than 23,000 stars.
• The canonical skills/planning-with-files/SKILL.md declares the skill name, quoted description, user-invocable: true, allowed tools, lifecycle hook commands, metadata version 3.1.3, and instructions for persistent planning files, session catchup, rules, templates, scripts, attestation, and parallel plan isolation.
• The README describes the project as persistent file-based planning for AI coding agents, with task_plan.md, findings.md, and progress.md, support for the SKILL.md standard, and host-specific integrations.
• The install docs document Claude Code plugin install, manual plugin install, skill-only install, verification, updates, and platform-specific docs.
• The Codex docs document .codex/skills, .codex/hooks.json, Codex hook feature flags, workspace or personal install scope, lifecycle hooks, and warnings about merging existing hook configs.
• The quickstart documents the three-file workflow, phase status updates, findings updates, progress updates, isolated plan directories, and completion checks.
• The eval docs report a structured-workflow benchmark using Anthropic's skill-creator framework, with with_skill satisfying 29 of 30 assertions and blind A/B comparators preferring the skill output in 3 of 3 comparisons for the tested tasks.
• The migration docs describe v3 autonomous mode, gated mode, a structured run-ledger, phase coordination fields, attestation, and no default behavior change from v2.43.0 without explicit opt-in.
• Release v3.1.3 fixed invalid YAML frontmatter from v3.1.2 by quoting the English SKILL.md descriptions and added tests that parse every SKILL.md frontmatter as YAML.