Build a feature across several phases
Keep investigation, implementation and testing in a persistent plan. The workflow directs the agent to update phase status, record failures and name the next action as the work progresses.
Overview
Planning with Files is a plugin for managing complex agent tasks through Markdown files in your project. task_plan.md tracks phases and next steps, findings.md stores research and decisions, and progress.md records work and test results. It suits research and implementation that span many tool calls or sessions.
In Claude Code, the agent can select the planning skill for complex work, or you can start a session with a planning command. Installed plugin hooks automatically restore selected planning context and provide reminders as work proceeds. Commands for checking progress, choosing a language, recording a plan digest and scheduling planning checks are invoked manually.
Automatic recovery reads project planning files. Reading local agent session history is a separate, explicit action; replayed excerpts may enter the host agent’s model context.
Use Cases
Research before choosing an approach
Save discoveries and decisions in findings.md while investigating a question, then refer back to the plan before committing to an approach.
Resume after clearing a conversation
Continue from the selected plan, findings and progress log after a context reset. The Claude Code plugin restores active-plan context from project files at startup and after compaction.
Components
For the commands below, open slash-command autocomplete in Claude Code and select the entry under planning-with-files. The language commands load translated planning instructions; phase-status markers remain in English so completion checks can read them. See the command reference for invocation details.
Each host loads its own hooks. Installing the whole Claude Code plugin registers its lifecycle hooks automatically. Inspect them in Claude Code’s hooks view, then check recovery in a project with an active plan; startup is intentionally silent without one. The installation guide covers these checks.
The Codex plugin selects its own lifecycle hooks. Keep plugin mode and standalone hook configuration as alternatives to avoid duplicate reminders. Restart Codex after adding or changing hooks, then review and trust their definitions in its hooks view. The integration needs Python 3 and a shell; on Windows, install Git for Windows for the shell-backed hooks. See the Codex hook setup and checks.
To disable the Claude Code or Codex planning hooks for one invocation, set the PLANNING_DISABLED environment variable to 1 before launching that host.
Qoder CLI hooks
Installing the native Qoder CLI plugin registers its seven lifecycle hooks. They require Bash and Python 3.10 or newer; on Windows, make Git for Windows Bash available on PATH. Restart Qoder CLI after installation. This integration targets the CLI; Qoder IDE hook execution and completion gating have not been validated for this package. See the Qoder plugin setup.
To check activity, use a project with a selected active plan and submit a prompt: the handler supplies the plan’s current state and recent progress. If session isolation is enabled, the session must be attached before it receives planning context. Set the PLANNING_DISABLED environment variable to 1 before launching Qoder CLI to suppress these planning hooks for that invocation.
Project hook configurations
The Codex project rows come from .codex/hooks.json, separate from the plugin descriptor. For standalone setup, copy the supplied scripts into .codex/hooks/ and merge the planning registrations into an existing .codex/hooks.json; personal setup uses ~/.codex/. Preserve other hooks. Use the Codex review, trust, restart and opt-out checks above. The standalone Codex guide covers merging.
For Cursor, copy the supplied skill and hook scripts into the project’s .cursor/ directory and merge the four planning registrations into .cursor/hooks.json. Back up same-named scripts before copying. The default configuration uses Bash; for native PowerShell, use the matching entries from .cursor/hooks.windows.json in the active .cursor/hooks.json, preserving your other hooks. Check Cursor’s output panel for hook execution logs. Set PLANNING_DISABLED to 1 before launching Cursor to suppress planning context, progress reminders and completion follow-ups; the pre-tool handler still allows tools. To stop loading these handlers entirely, remove their four registrations. See the Cursor setup guide.
For Mastra Code, place the supplied skill and scripts under .mastracode/skills/planning-with-files/ and merge the four planning event entries into .mastracode/hooks.json; personal setup uses ~/.mastracode/. Restart Mastra Code after changing the configuration. With a root task_plan.md, a submitted prompt supplies plan context and Stop reports phase counts. To disable these handlers, remove their planning registrations from the active hook configuration and restart; PLANNING_DISABLED suppresses the completion script but does not guard the three inline context and reminder handlers. See the Mastra Code setup guide.
Copilot project files. Copy the supplied .github/hooks/planning-with-files.json and hook scripts into the same paths in your project, and copy the supplied planning skill to .github/skills/planning-with-files/. Preserve existing hook files and make the Bash scripts executable on macOS or Linux; Windows uses the supplied PowerShell handlers. The Bash handlers need Bash and Python available. Committing these files shares the hooks with teammates using the repository. These handlers target Copilot CLI and the Copilot harness in VS Code; the legacy VS Code Local harness does not receive their startup or post-tool context. See the Copilot repository setup.
Copilot CLI checks and controls. Start a new CLI session after changing the hook configuration, then use /env to inspect loaded hooks. A separate hooks-only listing command is not documented in the CLI command reference. To disable just this file’s hooks while keeping the file, set its top-level disableAllHooks property to true and start a new session. Removing .github/hooks/planning-with-files.json also removes these registrations; see the Copilot hook controls.
VS Code checks and controls. Select Copilot as the Session Target, then open Customizations > Hooks or enter /hooks to inspect the sources. Start a disposable session and confirm the expected hook fires; a listed file alone does not prove execution. To remove these project hooks, remove their registrations from .github/hooks/planning-with-files.json and check again in a fresh session. Whether VS Code honors disableAllHooks is not documented, and chat.useHooks controls only the legacy Local harness. See the VS Code hook guide.
Gemini CLI project files. Copy the supplied .gemini/hooks/ scripts into your project and merge the supplied hooks entries into .gemini/settings.json, preserving existing settings. The configured commands point to scripts under the project root; have Bash and Python available and make the scripts executable. For the shutdown completion report, also place the planning skill’s scripts under .gemini/skills/planning-with-files/, as described in the completion-report row. See the Gemini hook setup.
Gemini CLI checks and controls. Start a new session after setup and inspect /hooks panel for planning-session-start, planning-before-agent, planning-after-tool and planning-session-end. Changed project hook names or commands are treated as new, untrusted hooks, so review the warning before allowing them to run. Use /hooks disable with a name from the panel to disable that hook, or /hooks disable-all to disable every hook. Setting PLANNING_DISABLED to 1 before launching Gemini suppresses these planning handlers for that invocation. See the Gemini hook guide.
Skills
This plugin's skills 1English 1
Local tool needed
planning-with-files
Guide multi-step work through persistent plans, research notes and progress logs.
Commands
13/planning-with-files:plan-arStart planning with Arabic instructions.
/planning-with-files:plan-attestRecord a SHA-256 digest so hooks can detect changes to the plan.
Record or inspect a plan digest
Use this after reviewing the active plan. Its show and clear options inspect or remove the recorded attestation.
/planning-with-files:plan-deStart planning with German instructions.
/planning-with-files:plan-doctorCheck plan resolution, context injection, attestation, installation files and hook latency.
/planning-with-files:plan-esStart planning with Spanish instructions.
/planning-with-files:plan-goalDerive a completion condition from the active plan for Claude Code’s goal feature.
Set the completion condition
Requires Claude Code’s native goal feature. With no extra input, the condition is that every plan phase reports complete; an additional clause extends that condition.
/planning-with-files:plan-loopSchedule recurring checks of planning files and completion status.
Choose a check interval
Requires Claude Code’s native loop feature. The default interval is 10 minutes; you can supply another interval and an optional custom prompt.
/planning-with-files:plan-zhStart planning with Simplified Chinese instructions.
/planning-with-files:plan-zhtStart planning with Traditional Chinese instructions.
/planning-with-files:planCreate the planning files and start a planning session.
/planning-with-files:pwfStart planning through the short alias, with optional autonomous or gated mode.
/planning-with-files:startStart a planning session with the original command.
/planning-with-files:statusShow the current phase and phase totals.
Hooks
48Claude Code session recovery
Restores selected project planning context when Claude Code starts, resumes, clears a conversation or returns from compaction.
Claude Code prompt context
Adds active-plan context on each user prompt and resets the progress reminder for the new turn.
Claude Code plan reminder before tools
Checks selected plan context before Write, Edit, Bash, Read, Glob or Grep; unchanged views may be suppressed.
When plan reminders appear
Autonomous mode omits the repeated plan view before tool calls while retaining turn-start context. In the default Claude Code behavior, a changed selected view refreshes once; missing session identity or unavailable cache storage can leave reminders repeating.
Claude Code progress reminder after edits
After Write or Edit, reminds the agent to update progress and completed phases, normally once per turn.
Claude Code reminder before compaction
Before compaction, surfaces a reminder to save progress and phase status, including the recorded plan digest when present.
Claude Code completion check
Checks completion when Claude Code stops; opt-in gated mode can request continuation when its conditions pass.
Completion gating is optional
An incomplete plan alone does not trap the session. Gated mode also checks runtime conditions such as phase state, the block limit and recorded progress before requesting continuation.
Codex session recovery
Restores selected project planning context at Codex startup, resume, clear or compaction recovery without reading session history.
Codex prompt context
Adds the selected plan and recent progress to Codex’s context on each user prompt.
Codex plan reminder before tools
Before Bash, apply_patch, Edit or Write, supplies a bounded plan reminder in legacy mode while allowing the tool call.
Mode changes the reminder
Autonomous and gated modes skip the plan recitation before tools. In legacy mode, the hook can add a bounded plan excerpt; it still allows the tool call.
Codex approval reminder
When Codex requests tool permission, reminds you to review the active plan without approving or blocking the request.
Review the plan before approving
This hook displays a reminder to inspect the current phase in task_plan.md. You still decide whether to approve the tool request.
Codex progress reminder after edits
After apply_patch, Edit or Write, reminds the agent to update progress and phase status, normally once per turn.
Codex reminder before compaction
Before Codex compaction, reminds the agent to save progress and phase status and reports the recorded plan digest when present.
Codex completion check
Checks completion when Codex stops; requests continuation only when the optional gate permits it, otherwise allowing the stop.
Completion gating is optional
Outside a gated continuation, an unfinished phase-structured plan produces an advisory status message. A completed plan needs no follow-up, and the adapter avoids requesting continuation recursively.
Qoder session recovery
Restores planning context when Qoder CLI starts, resumes, clears a conversation, returns from compaction or opens a new session.
Qoder prompt context
Injects planning context when you submit a prompt in Qoder CLI.
Qoder plan context before tools
Before Bash, Edit, Write, Read, Glob or Grep in Qoder CLI, can add bounded plan context in legacy mode; autonomous and gated modes skip the repeated plan view.
Qoder permission request
When Qoder CLI requests tool permission, shows a reminder to review the active plan without approving or blocking the request.
Review the plan before approving
When the selected plan is available to the session, this hook shows a reminder to review its current phase in task_plan.md. You still decide whether to approve the request.
Qoder progress reminder after edits
After Edit or Write in Qoder CLI, reminds the agent to update progress and phase status, normally once per turn.
Qoder reminder before compaction
Displays a reminder to preserve progress before Qoder CLI compacts the conversation.
Qoder completion check
Checks completion when Qoder CLI stops; opt-in gated mode can block the stop, while advisory plans may finish.
Only the optional gate blocks Stop
The Qoder adapter translates an eligible gated Stop decision into exit code 2 with the reason on standard error. Advisory status does not block the stop, and an already active Stop hook does not trigger another gated continuation.
Codex project session recovery
Through Codex’s standalone configuration, restores selected project planning context at startup, resume, clear or compaction recovery without reading session history.
Codex project prompt context
Through Codex’s standalone configuration, adds the selected plan and recent progress on each user prompt.
Codex project plan reminder before tools
Through Codex’s standalone configuration, can add a bounded plan reminder before Bash, apply_patch, Edit or Write in legacy mode while allowing the tool call.
Codex project approval reminder
Through Codex’s standalone configuration, reminds you to review the active plan when tool permission is requested, without approving or blocking it.
Codex project progress reminder after edits
Through Codex’s standalone configuration, reminds the agent to update progress after apply_patch, Edit or Write, normally once per turn.
Codex project reminder before compaction
Through Codex’s standalone configuration, reminds the agent to save progress and phase status before compaction.
Codex project completion check
Through Codex’s standalone configuration, checks completion at Stop and requests continuation only when the optional gate permits it.
Cursor session context through Bash
Adds selected plan context and recent progress when Cursor creates a conversation; Cursor Cloud Agents do not run this event.
Cursor tool permission through Bash
Before Write, Edit, Shell or Read in Cursor, returns permission to allow the operation; it does not inject plan context.
Cursor progress reminder through Bash
After Write or Edit in Cursor, adds a reminder to update progress and phase status when a selected plan exists.
Cursor completion check through Bash
When Cursor stops with incomplete plan phases, supplies a continuation message; the configuration limits retries to three.
Cursor session context through PowerShell
Uses PowerShell to add selected plan context and recent progress when Cursor creates a conversation; Cursor Cloud Agents do not run this event.
Cursor tool permission through PowerShell
Before Write, Edit, Shell or Read in Cursor, uses PowerShell to return permission to allow the operation without injecting plan context.
Cursor progress reminder through PowerShell
After Write or Edit in Cursor, uses PowerShell to add a progress and phase-status reminder when a selected plan exists.
Cursor completion check through PowerShell
Uses PowerShell to supply a continuation message when Cursor stops with incomplete plan phases; the configuration limits retries to three.
Mastra Code prompt context
On each Mastra Code prompt, adds the first 50 lines of the root plan and the last 20 lines of progress when the plan exists.
Mastra Code plan reminder before tools
Before Write, Edit, Bash, Read, Glob or Grep in Mastra Code, reads the first 30 lines of the root plan.
Mastra Code progress reminder after edits
After Write or Edit in Mastra Code, reminds the agent to update progress and phase status when the root plan exists.
Mastra Code completion report
When Mastra Code stops, reports phase completion from the root plan; an unfinished plan does not block the stop.
Gemini CLI session recovery
At Gemini CLI startup, restores project-file planning context or requests that the agent read the planning files; remains silent without a root plan.
Gemini CLI context before each turn
Before each Gemini CLI agent turn, adds the first 30 lines of the root plan when Python and a nonempty plan are available.
Gemini CLI progress reminder after edits
After write_file, edit_file, replace, create_file or patch in Gemini CLI, reminds the agent to update progress and completed phases when a root plan exists.
Gemini CLI completion report
At Gemini CLI shutdown, reports completion status when the root plan and workspace completion script exist; it does not block shutdown.
The completion script must be in the workspace
This hook looks for .gemini/skills/planning-with-files/scripts/check-complete.sh under the project root. Install the skill with workspace scope or follow the workspace copy instructions to put it there. The default user-level skill installation does not supply that project file, so this hook remains silent. Its completion report is advisory and user-facing.
Copilot session recovery
At Copilot session startup, supplies project planning context or, without a root plan, the installed planning skill’s instructions.
Copilot pre-tool permission handling
Before Copilot tool use, returns an empty result, leaving normal permission handling unchanged and adding no planning context.
Copilot progress reminder after tools
After Copilot tool use, adds a reminder to update progress and completed phases.
Copilot completion reminder
When Copilot stops, emits a phase-completion reminder for a root plan with phase headings; it never prevents stopping.
The reminder does not enforce completion
The repository guide says this hook prevents stopping when tasks remain, but the supplied Bash and PowerShell scripts return no blocking decision. Do not rely on it to keep work running. Whether Copilot delivers this particular reminder to the model is not documented in the Copilot hooks reference.
Copilot error-recording reminder
On a Copilot error, emits a reminder to record the error in the root plan when a plan and an error message are present.
Error recording still needs an action
The handler includes up to 200 characters of the error message in its reminder. It does not write the error to task_plan.md itself.
Install
Choose the Claude Code plugin for its planning skill, slash commands and lifecycle hooks, or the Pi package for its planning skill and extension.
Claude Code
- 01
Inside a Claude Code session, add the plugin marketplace.
/plugin marketplace add OthmanAdi/planning-with-files - 02
In the same Claude Code session, install Planning with Files.
/plugin install planning-with-files@planning-with-files - 03
Inspect the installed plugin in Claude Code’s plugin manager and its registered hooks in the hooks view. Start a new session in a project with an active plan to check that planning context is restored. A project without an active plan produces no startup message.
This package installs the planning skill and Pi extension together.
- 04
In your terminal, install the Planning with Files package through Pi.
pi install npm:planning-with-files - 05
Reload Pi’s runtime if it is already running, following the reload instruction in the Pi setup guide.
- 06
Inside Pi, run the planning status command to confirm that the extension responds. With an active plan, it shows the plan paths and phase counts.
/plan-status