othmanadi--planning-with-files/docs/pi-agent.md

Pi Agent Setup

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

---

Installation

Recommended: Install from npm

pi install npm:planning-with-files

This package now installs both:

• Skill: planning-with-files (3-file planning workflow)
• Extension: planning-with-files hook parity runtime

Manual Install (repo copy)

# Clone repo
git clone https://github.com/OthmanAdi/planning-with-files.git
cd planning-with-files

# Copy skill package into your Pi skills directory
mkdir -p ~/.pi/agent/skills/planning-with-files
cp -r .pi/skills/planning-with-files/* ~/.pi/agent/skills/planning-with-files/

---

What Pi Now Supports

Pi integration provides Claude-style lifecycle behavior via extension events:

• Session catchup on session_start
• Passive plan status before approval
• Plan context reminder/injection on before_agent_start after /plan-execute
• Pre-tool plan recitation equivalent on tool_call after /plan-execute
• Post-write reminders on tool_result after /plan-execute
• Auto-continue guard on agent_end after /plan-execute (limit: 3)
• Pre-compaction reminder on session_before_compact
• Plan attestation guard ([PLAN TAMPERED — injection blocked])

---

Mode System (DeepSeek-aware)

The extension supports four modes:

• auto (default):
  • DeepSeek model -> cache-safe
  • Other models -> parity
• parity: maximum Claude-equivalent behavior (dynamic plan injection)
• cache-safe: stable fixed reminder for better DeepSeek KV-cache hit rate
• notify: UI notifications only, no conversation injection

Configure via environment variable

PWF_MODE=auto pi
PWF_MODE=parity pi
PWF_MODE=cache-safe pi
PWF_MODE=notify pi

Configure via settings

Project-level (.pi/settings.json) overrides global (~/.pi/agent/settings.json):

{
  "planningWithFiles": {
    "mode": "auto"
  }
}

---

Commands

After installation, these extension commands are available:

• /plan-status — show current plan counts and paths
• /plan-attest [--show|--clear] — manage plan SHA-256 attestation
• /plan-execute — approve the active plan and enable hook activation
• /plan-execute reset — return the active plan to passive review mode
• /plan-goal <text|default|clear> — set/clear continuation goal text
• /plan-loop [10m] [prompt...] — periodic planning tick; use stop to cancel

---

Usage

Start with:

/skill:planning-with-files

Then ask Pi to create/update:

• task_plan.md
• findings.md
• progress.md

Review and edit the plan until it matches your intent. During this review stage, the extension stays passive: it may show plan status, but it does not inject plan context, recite the plan before tools, or auto-continue.

When you are ready to execute, run:

/plan-execute

For long tasks, keep task_plan.md as the source of truth and let the activated hooks/extension events enforce the loop.

---

Troubleshooting

1. Confirm package installed:

   pi list
   

2. Reload runtime:

   /reload
   

3. Check skill and extension paths:
   • skill: .pi/skills/planning-with-files/
   • extension: extensions/planning-with-files/index.ts
4. If plan injection is blocked, run:

   /plan-attest --show
   

   Then re-attest intentionally changed plans:

   /plan-attest