MIGRATION.md
Version 2.0.0 adds hooks integration and enhanced templates while maintaining backward compatibility with existing workflows.
v2.0.0 adds Claude Code hooks that automate key Manus principles:
| Hook | Trigger | Behavior |
|---|---|---|
PreToolUse | Before Write/Edit/Bash | Reads task_plan.md to refresh goals |
Stop | Before stopping | Verifies all phases are complete |
Benefit: You no longer need to manually remember to re-read your plan. The hook does it automatically.
New templates provide structured starting points:
templates/
├── task_plan.md # Phase tracking with status fields
├── findings.md # Research storage with 2-action reminder
└── progress.md # Session log with 5-question reboot test
Helper scripts for common operations:
scripts/
├── init-session.sh # Creates all 3 planning files
└── check-complete.sh # Verifies task completion
# If installed via marketplace
/plugin update planning-with-files
# If installed manually
cd .claude/plugins/planning-with-files
git pull origin master
Your existing task_plan.md files will continue to work. The hooks look for this file and gracefully handle its absence.
To use the new structured templates, you can either:
./scripts/init-session.shtemplates/ directoryv2.0.0 templates use a more structured status format:
v1.x format:
- [x] Phase 1: Setup ✓
- [ ] Phase 2: Implementation (CURRENT)
v2.0.0 format:
### Phase 1: Setup
- **Status:** complete
### Phase 2: Implementation
- **Status:** in_progress
The new format enables the check-complete.sh script to automatically verify completion.
None. v2.0.0 is fully backward compatible.
If you prefer the v1.x behavior without hooks, use the legacy branch:
git checkout legacy
After every 2 view/browser/search operations, save findings to files:
WebSearch → WebSearch → MUST Write findings.md
Structured error recovery:
Your planning files should answer:
Version 3.0.0 adds opt-in modes for long-running and multi-agent runs: autonomous mode (less
recitation), gated mode (a deliberate completion gate), a structured run-ledger, and phase
coordination fields. None of this changes how v2 behaves. With no new flags and no .mode
marker, v3 runs exactly like v2.43.0.
Nothing. The default path is byte-for-byte v2.43 behavior. The hooks stay advisory, the Stop
hook never blocks, and your existing task_plan.md, findings.md, and progress.md keep
working without edits. Every v3 behavior is keyed off an explicit opt-in, so an unmodified
install behaves identically to v2.43.0.
For strong models on long runs. Recitation drops to once per turn (session start) instead of before every tool call, which removes the per-tool-call token tax. The plan on disk stays the source of truth; the model re-reads it when it needs detail. There is no completion gate in this mode. Recitation is reduced, not removed: published evidence still shows goal drift on long runs, so autonomous mode is opt-in, never the default.
Adds a deliberate completion gate. When a phase is left in_progress and the run was tasked
with executing the plan, the Stop hook can hold the turn and feed back a fixed reminder naming
the pending phase. This is the opposite of the accidental gate from issue #178: it fires only
in gated mode, never for any incomplete plan, and the reminder text is a fixed template plus
the phase name, never raw plan content. Guards keep it safe: a block cap (default 20, counted
in .planning/<id>/.stop_blocks and reset at init), a stall detector (no new ledger line since
the last block means the run is allowed to stop), and the host's own stop_hook_active and
block-cap backstops.
A structured, append-only progress record. Workers append one JSON line per tick to a per-agent
ledger; the orchestrator keeps progress.md as the human-readable tick log. The injected
context is a synthesized fixed-shape summary, not a raw tail of progress.md, which keeps it
stable for the host's prompt cache and removes a raw-text injection surface.
task_plan_autonomous.md adds optional per-phase lines: **DependsOn:** (phases that must
finish first), **Owner:** (which agent runs the phase), and **AcceptanceCheck:** (a command
the gate may run to confirm the phase is done). These sit next to the existing **Status:**
line, so the completion check counts phases and statuses exactly as in v2. The gate runs an
AcceptanceCheck command only when it is allowlisted at attest time, and never runs a command
from an unattested plan.
In autonomous and gated modes, task_plan.md is hashed at init and the hooks refuse to inject
plan content that diverges from the attested hash. Re-run scripts/attest-plan.sh after any
intentional edit. In multi-agent runs the orchestrator re-attests at phase boundaries, since a
worker editing the plan would break the hash by design. This is what makes the AcceptanceCheck
command safe to run.
The hook's mtime-SHA cache moved from ${TMPDIR:-/tmp}/pwf-sha (v2) to $HOME/.cache/pwf-sha
(or $XDG_CACHE_HOME/pwf-sha when set). This removes the shared-tmp poisoning surface. The
move is silent: a warm v2 cache under /tmp/pwf-sha is never read by v3, so the first session
after upgrade rehashes every attested plan once. That is the correct behavior (no stale reads),
and the cache repopulates immediately. On a large collection of attested plans on slow Windows
Git Bash, that first rehash can show as a one-time per-turn latency bump; subsequent sessions are
back to cache speed. No action is needed, and the old /tmp/pwf-sha directory can be deleted.
# 1. Start a gated session (writes the .mode marker, attests the plan, resets the block counter)
./scripts/init-session.sh --gated "my-feature"
# 2. Plan as usual
# Fill in task_plan.md (or start from templates/task_plan_autonomous.md), set phase statuses,
# and work. The gate holds the turn while a phase is in_progress, up to the block cap.
For autonomous mode, swap --gated for --autonomous. To return to plain v2 behavior, start a
session with no flag (no .mode file is written).
The completion gate is host-aware: not every host can hard-block a stop. The tiers below summarize what each host enforces. In every tier the plan file on disk is still the shared, durable state; only the gate's enforcement strength differs.
| Tier | Mechanism | Hosts |
|---|---|---|
| Hard block | decision:block / exit 2 holds the turn | Claude Code, Codex CLI, OpenAI Codex API, Continue.dev |
| Follow-up inject | continuation via an injected follow-up message plus the host's own counter | Cursor, Pi, Kiro |
| Notify only | a system message is shown, no enforcement | OpenCode, Gemini CLI, and the remaining adapters |
On hard-block hosts, gated mode enforces the gate. On follow-up hosts, the gate becomes a follow-up message capped by a counter (Pi's AUTO_CONTINUE_LIMIT is the reference). On notify-only hosts, gated mode degrades to a non-blocking notice; autonomous mode still works because it needs no gate.
OpenCode has no Stop-hook re-activation. The upstream request (issue #12472) is open and unimplemented, so OpenCode cannot enforce the completion gate at all. On OpenCode the gate is a system message only. Autonomous mode and the run-ledger work on OpenCode because they do not depend on blocking the stop; only the gate's enforcement is unavailable until upstream ships it.
None. v3.0.0 is fully backward compatible. Default behavior with no mode marker is exactly v2.43 semantics.
Open an issue: https://github.com/OthmanAdi/planning-with-files/issues