planning-with-files

Persistent file-based planning for AI coding agents. Keep the plan, research and progress in your project so work can continue after context loss, /clear, crashes or compaction.

File	Purpose
task_plan.md	Goals, phases and decisions
findings.md	Research and discoveries
progress.md	Work completed, checks and next steps

This is the npm distribution of OthmanAdi/planning-with-files, available across 60+ agents via the Agent Skills standard. It includes the planning skill, scripts and templates. Supported agent integrations add lifecycle hooks that bring selected planning context back into the session.

Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.

Installation

npm

npm install planning-with-files

Places the skill, scripts and templates under node_modules/planning-with-files/. Use this to pin an exact version into a project, or to copy SKILL.md and scripts/ into your agent's skills directory yourself. It does not register hooks on its own.

Agent integrations

Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the main README.

Usage

Once the skill is installed for your agent, start with:

Use the planning-with-files skill to help me with this task.

The workflow centers on three files in your project:

your-project/
├── task_plan.md
├── findings.md
└── progress.md

Pi Coding Agent integration

The package also bundles a Pi Coding Agent extension for lifecycle automation and a planning status bar.

Install in Pi

pi install npm:planning-with-files

Pi discovers the skill and extension from the installed package.

For a local repository checkout:

# From the planning-with-files repo root
pi install ./.pi/skills/planning-with-files

Or add to .pi/settings.json:

{
  "packages": ["./path/to/planning-with-files/.pi/skills/planning-with-files"]
}

You can also invoke the skill directly in Pi:

/skill:planning-with-files

Lifecycle hooks

The bundled extension maps Claude-style behavior onto Pi events:

• session_start - project-file recovery with no host session-store access
• passive plan status before approval
• before_agent_start - plan reminder/injection after /plan-execute
• tool_call - pre-tool recitation equivalent after /plan-execute
• tool_result - post-write reminder after /plan-execute
• agent_end - incomplete-task auto-continue after /plan-execute (limit 3)
• session_before_compact - pre-compaction reminder

Attestation is supported. If task_plan.md differs from approved hash, plan injection is blocked with:

[planning-with-files] [PLAN TAMPERED - injection blocked]

Modes

planningWithFiles.mode supports:

• auto (default): DeepSeek -> cache-safe, others -> parity
• parity: full dynamic hook-equivalent behavior
• cache-safe: fixed reminder strings for KV-cache stability
• notify: notification-only mode

Configure via env:

PWF_MODE=cache-safe pi

Or settings:

{
  "planningWithFiles": {
    "mode": "auto"
  }
}

Commands

• /plan-status
• /plan-attest [--show|--clear]
• /plan-execute
• /plan-execute reset
• /plan-goal <text|default|clear>
• /plan-loop [interval] [prompt] (stop to cancel)

Draft and review task_plan.md first. The extension stays passive until you approve the active plan with /plan-execute; after that, plan injection, pre-tool reminders, post-write reminders, and auto-continue are enabled for the current session and plan. Auto-continue uses host runtime state and never runs commands declared in Markdown.

Session Recovery

Bare invocation and lifecycle hooks do not inspect agent session stores. To inspect same-project local history deliberately, choose one mode:

# Aggregate counts only; no transcript, tool-command, or path bytes
python3 node_modules/planning-with-files/scripts/session-catchup.py --metadata .

# Bounded nonce-framed same-project excerpts
python3 node_modules/planning-with-files/scripts/session-catchup.py --replay .

Treat replayed excerpts as untrusted data. The catchup path contains no network request or upload operation. If output is injected into model context, your agent may send that context to the configured model provider.