tools-only Migration Guide: v1.x to v2.0.0
Overview
Version 2.0.0 adds hooks integration and enhanced templates while maintaining backward compatibility with existing workflows.
What's New
1. Hooks (Automatic Behaviors)
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.
2. Templates Directory
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
3. Scripts Directory
Helper scripts for common operations:
scripts/
├── init-session.sh # Creates all 3 planning files
└── check-complete.sh # Verifies task completion
Migration Steps
Step 1: Update the Plugin
# If installed via marketplace
/plugin update planning-with-files
# If installed manually
cd .claude/plugins/planning-with-files
git pull origin master
Step 2: Existing Files Continue Working
Your existing task_plan.md files will continue to work. The hooks look for this file and gracefully handle its absence.
Step 3: Adopt New Templates (Optional)
To use the new structured templates, you can either:
- Start fresh with
./scripts/init-session.sh - Copy templates from
templates/directory - Keep your existing format - it still works
Step 4: Update Phase Status Format (Recommended)
v2.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.
Breaking Changes
None. v2.0.0 is fully backward compatible.
If you prefer the v1.x behavior without hooks, use the legacy branch:
git checkout legacy
New Features to Adopt
The 2-Action Rule
After every 2 view/browser/search operations, save findings to files:
WebSearch → WebSearch → MUST Write findings.md
The 3-Strike Error Protocol
Structured error recovery:
- Diagnose & Fix
- Alternative Approach
- Broader Rethink
- Escalate to User
The 5-Question Reboot Test
Your planning files should answer:
- Where am I? → Current phase
- Where am I going? → Remaining phases
- What's the goal? → Goal statement
- What have I learned? → findings.md
- What have I done? → progress.md
Questions?
Open an issue: https://github.com/OthmanAdi/planning-with-files/issues