129 lines
2.7 KiB
Markdown
129 lines
2.7 KiB
Markdown
# Pi Agent Setup
|
|
|
|
How to use planning-with-files with [Pi Coding Agent](https://pi.dev).
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Pi Install
|
|
|
|
```bash
|
|
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.
|
|
|
|
```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:
|
|
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.
|