planning-with-files

Your agent's context window dies. The plan does not.

Persistent file-based planning for AI coding agents. The skill keeps task_plan.md, findings.md and progress.md on disk. After /plan-execute, Pi lifecycle hooks inject selected project planning context so the plan survives context loss, /clear, crashes and compaction. Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.

This is the npm distribution of OthmanAdi/planning-with-files, which installs across 60+ agents via the Agent Skills standard. The package ships:

• the planning skill itself: SKILL.md, scripts/ and templates/
• a Pi Coding Agent extension providing Claude-style lifecycle automation

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.

Pi Install

pi install npm:planning-with-files

Wires up the skill, the extension and the status bar automatically.

Other agents

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.

Manual Install

# 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"]
}

Usage

Pi discovers the skill and extension from the installed package.

Start with:

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

Or:

/skill:planning-with-files

Hook Parity in Pi

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]

Mode System

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 .pi/skills/planning-with-files/scripts/session-catchup.py --metadata .

# Bounded nonce-framed same-project excerpts
python3 .pi/skills/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, Pi may send that context to the configured model provider.

File Structure

The skill workflow still centers on three files in your project:

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