[PR #77] [MERGED] Add isolated .planning plan sessions with UUID + PLAN_ID pinning #80

New issue

Closed

opened 2026-03-03 18:50:28 +03:00 by kerem · 0 comments

kerem commented

2026-03-03 18:50:28 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/OthmanAdi/planning-with-files/pull/77
Author: @ciberponk
Created: 2/15/2026
Status: ✅ Merged
Merged: 2/22/2026
Merged by: @OthmanAdi

Base: experimental/isolated-planning ← Head: feat/isolated-plans-dot-planning

📝 Commits (5)

3a8547f fix: prevent false-positive catchup in skill-distributed scripts
f3c07ea docs: add @gydx6 to contributors, bump version to v2.15.1
bc642b9 docs: move @gydx6 to CONTRIBUTORS.md (proper location)
6a9effe docs: add link to experimental isolated-planning branch
5d52141 merge upstream/master and resolve session-catchup conflict

📊 Changes

10 files changed (+90 additions, -76 deletions)

View changed files

📝 .adal/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 .codebuddy/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 .codex/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 .continue/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 .gemini/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 .openclaw/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 .opencode/skills/planning-with-files/scripts/session-catchup.py (+7 -9)
📝 .pi/skills/planning-with-files/scripts/session-catchup.py (+10 -9)
📝 CONTRIBUTORS.md (+8 -2)
📝 README.md (+5 -2)

📄 Description

Summary

This PR ports a set of parallel-safe planning extensions from our production usage into the upstream skill, while keeping the core Manus workflow intact.

Original behavior (upstream)

Planning files were created directly in project root (task_plan.md, findings.md, progress.md).
Hooks read/write a single root-level task_plan.md.
Session catchup did not scope to a specific active plan directory.

Added extensions in this PR

Introduce isolated per-task plan folders under ./.planning/{plan_id}.
Generate a UUID for every new plan session.
Create and maintain .planning/.active_plan as shared default pointer.
Add per-terminal parallel pinning via PLAN_ID environment variable.
Add active plan resolver scripts for Unix + PowerShell:
- resolve-plan-dir.sh / resolve-plan-dir.ps1
- set-active-plan.sh / set-active-plan.ps1
Update init/check scripts (root + skill) to operate on active plan directories.
Update hooks in skills/planning-with-files/SKILL.md to resolve and read the active plan before actions.
Update examples/reference to document isolated plan paths and parallel-safe usage.
Update root scripts/session-catchup.py to scope planning updates to active .planning/{plan_id} when available.

Why this helps

Multiple plans can run in parallel without overwriting each other's planning files.
Reduces cross-task context pollution in long-running or multi-terminal workflows.
Keeps a safe default pointer (.active_plan) while enabling explicit session pinning (PLAN_ID).

Verification

Ran Python compile checks for catchup scripts.
Validated root and skill init/check flows in temporary directories:
- init-session creates .planning/{uuid} + 3 planning files.
- resolve-plan-dir returns the expected active plan path.
- check-complete reports status using the resolved active plan file.

Scope

This PR updates the canonical skill and its root script equivalents used by hooks.
IDE-specific skill variants are intentionally left for follow-up to keep this change focused and reviewable.

Prepared collaboratively by ciberponk and Codex (GPT-5).

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/OthmanAdi/planning-with-files/pull/77 **Author:** [@ciberponk](https://github.com/ciberponk) **Created:** 2/15/2026 **Status:** ✅ Merged **Merged:** 2/22/2026 **Merged by:** [@OthmanAdi](https://github.com/OthmanAdi) **Base:** `experimental/isolated-planning` ← **Head:** `feat/isolated-plans-dot-planning` --- ### 📝 Commits (5) - [`3a8547f`](https://github.com/OthmanAdi/planning-with-files/commit/3a8547ff24263ab34720704eaf3d8b80606b8f39) fix: prevent false-positive catchup in skill-distributed scripts - [`f3c07ea`](https://github.com/OthmanAdi/planning-with-files/commit/f3c07ea4c736e3c99fa7935aaf8be32cfcda6e01) docs: add @gydx6 to contributors, bump version to v2.15.1 - [`bc642b9`](https://github.com/OthmanAdi/planning-with-files/commit/bc642b9bf6d932a0e62bc8979c6361a49a592599) docs: move @gydx6 to CONTRIBUTORS.md (proper location) - [`6a9effe`](https://github.com/OthmanAdi/planning-with-files/commit/6a9effe7d740b09c383ae8220c2576fcfb3eafcc) docs: add link to experimental isolated-planning branch - [`5d52141`](https://github.com/OthmanAdi/planning-with-files/commit/5d52141f050d67949e7f9713d3bad24a2dacf4fe) merge upstream/master and resolve session-catchup conflict ### 📊 Changes **10 files changed** (+90 additions, -76 deletions) <details> <summary>View changed files</summary> 📝 `.adal/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `.codebuddy/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `.codex/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `.continue/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `.gemini/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `.openclaw/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `.opencode/skills/planning-with-files/scripts/session-catchup.py` (+7 -9) 📝 `.pi/skills/planning-with-files/scripts/session-catchup.py` (+10 -9) 📝 `CONTRIBUTORS.md` (+8 -2) 📝 `README.md` (+5 -2) </details> ### 📄 Description ## Summary This PR ports a set of parallel-safe planning extensions from our production usage into the upstream skill, while keeping the core Manus workflow intact. ## Original behavior (upstream) - Planning files were created directly in project root (`task_plan.md`, `findings.md`, `progress.md`). - Hooks read/write a single root-level `task_plan.md`. - Session catchup did not scope to a specific active plan directory. ## Added extensions in this PR - Introduce isolated per-task plan folders under `./.planning/{plan_id}`. - Generate a UUID for every new plan session. - Create and maintain `.planning/.active_plan` as shared default pointer. - Add per-terminal parallel pinning via `PLAN_ID` environment variable. - Add active plan resolver scripts for Unix + PowerShell: - `resolve-plan-dir.sh` / `resolve-plan-dir.ps1` - `set-active-plan.sh` / `set-active-plan.ps1` - Update init/check scripts (root + skill) to operate on active plan directories. - Update hooks in `skills/planning-with-files/SKILL.md` to resolve and read the active plan before actions. - Update examples/reference to document isolated plan paths and parallel-safe usage. - Update root `scripts/session-catchup.py` to scope planning updates to active `.planning/{plan_id}` when available. ## Why this helps - Multiple plans can run in parallel without overwriting each other's planning files. - Reduces cross-task context pollution in long-running or multi-terminal workflows. - Keeps a safe default pointer (`.active_plan`) while enabling explicit session pinning (`PLAN_ID`). ## Verification - Ran Python compile checks for catchup scripts. - Validated root and skill init/check flows in temporary directories: - `init-session` creates `.planning/{uuid}` + 3 planning files. - `resolve-plan-dir` returns the expected active plan path. - `check-complete` reports status using the resolved active plan file. ## Scope - This PR updates the canonical skill and its root script equivalents used by hooks. - IDE-specific skill variants are intentionally left for follow-up to keep this change focused and reviewable. --- Prepared collaboratively by **ciberponk** and **Codex (GPT-5)**. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>