Pi Agent Setup

How to use planning-with-files with Pi Coding Agent.

Installation

Pi Install

bash

pi install npm:pi-planning-with-files

Manual Install

Navigate to your project root.
Create the .pi/skills directory if it doesn't exist.
Copy the planning-with-files skill.

bash

# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill
mkdir -p ~/.pi/agent/skills
cp -r planning-with-files/.pi/skills/planning-with-files .pi/skills/

Usage

Pi Agent automatically discovers skills in .pi/skills.

To use the skill, you can explicitly invoke it or let Pi discover it based on the task description.

Explicit Invocation

bash

/skill:planning-with-files

Or just ask Pi:

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

Important Limitations

Note: Hooks (PreToolUse, PostToolUse, Stop) are Claude Code specific and are not currently supported in Pi Agent.

What works in Pi Agent:

Core 3-file planning pattern
Templates (task_plan.md, findings.md, progress.md)
All planning rules and guidelines
The 2-Action Rule
The 3-Strike Error Protocol
Read vs Write Decision Matrix
Helper scripts (via explicit invocation or skill instructions)

What works differently:

Session Recovery: You must manually run the catchup script if needed:
bash
```
python3 .pi/skills/planning-with-files/scripts/session-catchup.py .
```
(The skill provides instructions for this)

Manual Workflow

Since hooks don't run automatically, follow the pattern:

1. Create planning files first

The skill instructions will guide Pi to create these files. If not, ask:

Start by creating task_plan.md, findings.md, and progress.md using the planning-with-files templates.

2. Re-read plan before decisions

Periodically ask:

Read task_plan.md to refresh our context.

3. Update files after phases

After completing a phase:

Update task_plan.md to mark this phase complete.
Update progress.md with what was done.

File Structure

your-project/
├── .pi/
│   └── skills/
│       └── planning-with-files/
│           ├── SKILL.md
│           ├── templates/
│           ├── scripts/
│           └── ...
├── task_plan.md
├── findings.md
├── progress.md
└── ...

Troubleshooting

If Pi doesn't seem to follow the planning rules:

Ensure the skill is loaded (ask "What skills do you have available?").
Explicitly ask it to read the SKILL.md file: Read .pi/skills/planning-with-files/SKILL.md.
Use the /skill:planning-with-files command if enabled.