Adds a bundled TypeScript extension under .pi/skills/planning-with-files/extensions/planning-with-files/ that maps Pi lifecycle events onto the same behavior the skill provides on Claude Code (PR #157 by @TomXPRIME). Event surface: session_start, before_agent_start, tool_call, tool_result, agent_end, session_before_compact, session_shutdown, input. Four modes: auto (DeepSeek-aware), parity, cache-safe, notify. Attestation gate shares the v2.37 .attestation file. Four slash commands registered (/plan-status, /plan-attest, /plan-goal, /plan-loop). 12 new contract tests. Fixes docs/codex.md to use the canonical [features] hooks = true key (Issue #154 by @DLI1996), with a deprecated-alias note so users on older configs keep working. Version bumped to 2.39.0 across 14 SKILL.md variants, plugin.json, marketplace.json, CITATION.cff via scripts/bump-version.py. .pi npm scheme bumped 1.0.1 -> 1.1.0 for the extension surface. .continue, .gemini, .kiro lag intentionally. Tests: 110 pass, 2 pre-existing Windows exec-bit failures unrelated to this release.
2.8 KiB
2.8 KiB
Pi Agent Setup
How to use planning-with-files with Pi Coding Agent.
Installation
Recommended: Install from npm
pi install npm:pi-planning-with-files
This package now installs both:
- Skill:
planning-with-files(3-file planning workflow) - Extension:
planning-with-fileshook 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 - Plan context reminder/injection on
before_agent_start - Pre-tool plan recitation equivalent on
tool_call - Post-write reminders on
tool_result - Auto-continue guard on
agent_end(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
- DeepSeek model ->
parity: maximum Claude-equivalent behavior (dynamic plan injection)cache-safe: stable fixed reminder for better DeepSeek KV-cache hit ratenotify: 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-goal <text|default|clear>— set/clear continuation goal text/plan-loop [10m] [prompt...]— periodic planning tick; usestopto cancel
Usage
Start with:
/skill:planning-with-files
Then ask Pi to create/update:
task_plan.mdfindings.mdprogress.md
For long tasks, keep task_plan.md as the source of truth and let hooks/extension events enforce the loop.
Troubleshooting
- Confirm package installed:
pi list - Reload runtime:
/reload - Check skill and extension paths:
- skill:
.pi/skills/planning-with-files/ - extension:
extensions/planning-with-files/index.ts
- skill:
- If plan injection is blocked, run:
Then re-attest intentionally changed plans:
/plan-attest --show/plan-attest