Compare commits

...
3 Commits
24 changed files with 90 additions and 74 deletions
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
# Planning with Files
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.17.1"
"version": "3.17.2"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.17.1",
"version": "3.17.2",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/skill-hook.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
+2 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.17.1",
"version": "3.17.2",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
@@ -8,6 +8,7 @@
},
"repository": "https://github.com/OthmanAdi/planning-with-files",
"license": "MIT",
"commands": [],
"skills": "./.agents/skills/",
"hooks": "./hooks/codex-hooks.json"
}
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
# Planning with Files
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.17.1"
version: "3.17.2"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
+54 -52
View File
@@ -1,13 +1,25 @@
# planning-with-files
<div align="center">
<img src="https://raw.githubusercontent.com/OthmanAdi/planning-with-files/master/media/v3-banner-1400.jpg" alt="planning-with-files: task_plan.md, findings.md, and progress.md as three stone tablets" width="100%">
</div>
> **Your agent's context window dies. The plan does not.**
<h1 align="center">Planning with Files</h1>
Persistent file-based planning for AI coding agents. The skill keeps `task_plan.md`, `findings.md` and `progress.md` on disk. After `/plan-execute`, Pi lifecycle hooks inject selected project planning context so the plan survives context loss, `/clear`, crashes and compaction. Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.
<p align="center">
<strong>The planning skill your agent cannot ignore.</strong><br>
Your agent's context window dies. The plan does not.
</p>
This is the npm distribution of [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), which installs across 60+ agents via the Agent Skills standard. The package ships:
Persistent file-based planning for AI coding agents. Keep the plan, research and progress in your project so work can continue after context loss, `/clear`, crashes or compaction.
- the planning skill itself: `SKILL.md`, `scripts/` and `templates/`
- a [Pi Coding Agent](https://pi.dev) extension providing Claude-style lifecycle automation
| File | Purpose |
| --- | --- |
| `task_plan.md` | Goals, phases and decisions |
| `findings.md` | Research and discoveries |
| `progress.md` | Work completed, checks and next steps |
This is the npm distribution of [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), available across 60+ agents via the Agent Skills standard. It includes the planning skill, scripts and templates. Supported agent integrations add lifecycle hooks that bring selected planning context back into the session.
Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.
## Installation
@@ -19,19 +31,40 @@ npm install planning-with-files
Places the skill, scripts and templates under `node_modules/planning-with-files/`. Use this to pin an exact version into a project, or to copy `SKILL.md` and `scripts/` into your agent's skills directory yourself. It does not register hooks on its own.
### Pi Install
### Agent integrations
Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the [main README](https://github.com/OthmanAdi/planning-with-files#quick-install).
## Usage
Once the skill is installed for your agent, start with:
```text
Use the planning-with-files skill to help me with this task.
```
The workflow centers on three files in your project:
```text
your-project/
├── task_plan.md
├── findings.md
└── progress.md
```
## Pi Coding Agent integration
The package also bundles a [Pi Coding Agent](https://pi.dev) extension for lifecycle automation and a planning status bar.
### Install in Pi
```bash
pi install npm:planning-with-files
```
Wires up the skill, the extension and the status bar automatically.
Pi discovers the skill and extension from the installed package.
### Other agents
Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the [main README](https://github.com/OthmanAdi/planning-with-files#quick-install).
### Manual Install
For a local repository checkout:
```bash
# From the planning-with-files repo root
@@ -45,27 +78,13 @@ Or add to `.pi/settings.json`:
}
```
---
## Usage
Pi discovers the skill and extension from the installed package.
Start with:
```text
Use the planning-with-files skill to help me with this task.
```
Or:
You can also invoke the skill directly in Pi:
```text
/skill:planning-with-files
```
---
## Hook Parity in Pi
### Lifecycle hooks
The bundled extension maps Claude-style behavior onto Pi events:
@@ -83,9 +102,7 @@ Attestation is supported. If `task_plan.md` differs from approved hash, plan inj
[planning-with-files] [PLAN TAMPERED - injection blocked]
```
---
## Mode System
### Modes
`planningWithFiles.mode` supports:
@@ -110,9 +127,7 @@ Or settings:
}
```
---
## Commands
### Commands
- `/plan-status`
- `/plan-attest [--show|--clear]`
@@ -127,8 +142,6 @@ pre-tool reminders, post-write reminders, and auto-continue are enabled for the
current session and plan. Auto-continue uses host runtime state and never runs
commands declared in Markdown.
---
## Session Recovery
Bare invocation and lifecycle hooks do not inspect agent session stores. To
@@ -136,23 +149,12 @@ inspect same-project local history deliberately, choose one mode:
```bash
# Aggregate counts only; no transcript, tool-command, or path bytes
python3 .pi/skills/planning-with-files/scripts/session-catchup.py --metadata .
python3 node_modules/planning-with-files/scripts/session-catchup.py --metadata .
# Bounded nonce-framed same-project excerpts
python3 .pi/skills/planning-with-files/scripts/session-catchup.py --replay .
python3 node_modules/planning-with-files/scripts/session-catchup.py --replay .
```
Treat replayed excerpts as untrusted data. The catchup path contains no network
request or upload operation. If output is injected into model context, Pi may
send that context to the configured model provider.
## File Structure
The skill workflow still centers on three files in your project:
```text
your-project/
├── task_plan.md
├── findings.md
└── progress.md
```
request or upload operation. If output is injected into model context, your agent
may send that context to the configured model provider.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.17.1",
"version": "3.17.2",
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
+8
View File
@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
## [Unreleased]
## [3.17.2] - 2026-09-09
### Fixed
- The native Codex plugin explicitly disables legacy command migration with `"commands": []`. Codex no longer turns the 13 top-level Claude commands into redundant `source-command-*` skills when installing the plugin. The canonical planning skill and Codex hooks remain configured, and Claude retains its commands (#241).
### Thanks
- @sunznx, for reporting the duplicate skills, tracing the fallback, and proposing the scoped manifest fix in #241.
## [3.17.1] - 2026-09-08
### Fixed
+2 -2
View File
@@ -7,8 +7,8 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.17.1"
date-released: "2026-08-31"
version: "3.17.2"
date-released: "2026-09-09"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
repository-code: "https://github.com/OthmanAdi/planning-with-files"
+3 -2
View File
@@ -106,8 +106,9 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[@sunznx](https://github.com/sunznx)**, [Issue #240](https://github.com/OthmanAdi/planning-with-files/issues/240)
- **[@sunznx](https://github.com/sunznx)**, [Issue #240](https://github.com/OthmanAdi/planning-with-files/issues/240), [Issue #241](https://github.com/OthmanAdi/planning-with-files/issues/241)
- Reported and reproduced named-plan crossover between Codex sessions sharing a working directory after compaction.
- Reported the 13 duplicate Codex command skills, traced the legacy command fallback, and proposed the native manifest setting that disables it.
- **[@hzura](https://github.com/hzura)**, [Issue #50](https://github.com/OthmanAdi/planning-with-files/issues/50)
- Raised the same-repository parallel-task workflow that led to explicit plan selection and shared-file ownership guidance.
@@ -426,4 +427,4 @@ If you've contributed and don't see your name here, please open an issue! We wan
**Total Contributors:** 59+ and growing!
*Last updated: 2026-09-08*
*Last updated: 2026-09-09*
+1
View File
@@ -354,6 +354,7 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.17.2** | Fixes #241: the native Codex manifest disables legacy command migration, removing 13 redundant `source-command-*` skills from plugin installs. The canonical planning skill, Codex hooks, and Claude commands remain available. |
| **v3.17.1** | Fixes #240: two named plans in the same project now require `PLAN_ID`, even without `.planning/sessions/`. A shared pointer or newest-plan guess cannot redirect a Codex session across compaction. Ambiguous hooks inject no plan and Stop does not gate against a guessed plan. |
| **v3.17.0** | **Every Claude Code hook fire forked about 130 processes, and under Git Bash on Windows that took 7 to 12 seconds against the 10 second hook timeout.** Claude Code discarded the plan context ("UserPromptSubmit hook timed out after 10s") and every Bash, Read, Grep and Edit call waited 5 more seconds in PreToolUse before it ran. Linux and macOS never showed it because a fork costs milliseconds there. The events now run in one Python process, `scripts/inject-plan.py`, a byte-identical twin of the shell chain proven by a parity suite on all three CI legs, with the shell chain kept as the reference and as the fallback for hosts without Python: 0.3 s per prompt and per tool call on the reporting machine. Hook interpreters now start in isolated mode, so a repository's own `secrets.py` or `hashlib.py` is never imported by a hook. `PWF_FAST_PATH=0` forces the shell chain. |
| **v3.16.1** | Attached Codex, Hermes and Pi sessions require an explicit plan when several tasks share an armed project. Standalone hooks deliver model context through the proper event fields, preserve native session identity and throttle progress reminders. Packages include the loop template and Stop dependencies; recovery and security guidance state the selected-plan and trust boundaries. |
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
# نظام تخطيط الملفات
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
# Dateiplanungssystem
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
# Sistema de Planificación con Archivos
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zh/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.1"
version: "3.17.2"
---
# Planning with Files
+3
View File
@@ -62,6 +62,9 @@ class CodexPluginOperationsTests(unittest.TestCase):
self.assertEqual("planning-with-files", manifest["name"])
self.assertEqual("./.agents/skills/", manifest["skills"])
# Omitting commands makes Codex migrate the top-level Claude commands
# into redundant source-command-* skills even with an explicit skills root.
self.assertEqual([], manifest.get("commands"), "Disable Codex's legacy command fallback")
self.assertEqual("./hooks/codex-hooks.json", manifest["hooks"])
self.assertNotIn("hooks/hooks.json", manifest.values())