@tomxprime/planning-with-files

Manus-style file-based planning for Pi Coding Agent

Packages

Package details

extensionskill

Install @tomxprime/planning-with-files from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@tomxprime/planning-with-files
Package
@tomxprime/planning-with-files
Version
1.1.0
Published
May 22, 2026
Downloads
not available
Author
tomxprime
License
MIT
Types
extension, skill
Size
123.2 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "skills": [
    "SKILL.md"
  ],
  "extensions": [
    "extensions/planning-with-files/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Pi Planning With Files

Work like Manus - Use persistent markdown files as your "working memory on disk."

A Pi Coding Agent package that ships both:

  • the planning skill (task_plan.md / findings.md / progress.md)
  • a Pi extension that provides Claude-style lifecycle automation

Installation

Pi Install

pi install npm:pi-planning-with-files

Manual Install

  1. Navigate to your project root.
  2. Copy .pi/skills/planning-with-files/ into your Pi skills directory.
  3. Reload Pi (/reload) if already running.

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 - session catchup
  • before_agent_start - plan reminder/injection
  • tool_call - pre-tool recitation equivalent
  • tool_result - post-write reminder
  • agent_end - incomplete-task auto-continue (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-goal <text|default|clear>
  • /plan-loop [interval] [prompt] (stop to cancel)

Session Recovery

If needed, run catchup manually:

python3 .pi/skills/planning-with-files/scripts/session-catchup.py .

File Structure

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

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