Skip to content

pi-agent.md

Latest commit

 

History

History
128 lines (90 loc) · 2.7 KB

pi-agent.md

File metadata and controls

128 lines (90 loc) · 2.7 KB

Pi Agent Setup

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

Installation

Pi Install

pi install npm:pi-planning-with-files

Manual Install

  1. Navigate to your project root.
  2. Create the .pi/skills directory if it doesn't exist.
  3. Copy the planning-with-files skill.
# 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

/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: 
    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:

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