tools-only Upgrading to Navigator v4.0.0
From: v3.x To: v4.0.0 Compatibility: Fully backward compatible - zero breaking changes
Quick Summary
✅ Upgrade is safe - No breaking changes ✅ Auto-migration - Navigator handles everything ✅ Zero downtime - Existing projects work immediately ✅ New features - Education layer available on-demand
What's New in v4.0
Major Addition: Education Layer
v4.0 adds comprehensive learning content in .agent/learning/:
Learning Guides (4 guides):
- CONTEXT-BUDGETS.md - Token allocation strategies
- PREPROCESSING-VS-LLM.md - Right tool for the job
- PROGRESSIVE-REFINEMENT.md - Metadata → details pattern
- TOKEN-OPTIMIZATION.md - Complete strategy reference
Interactive Examples (3 exercises):
- TRY-THIS-LAZY-LOADING.md - Experience 90%+ savings
- TRY-THIS-AGENT-SEARCH.md - Agent vs manual comparison
- TRY-THIS-MARKERS.md - 97% compression practice
Decision Frameworks (3 quick refs):
- WHEN-TO-COMPACT.md - Context management flowchart
- AGENT-VS-MANUAL.md - File reading decisions
- PREPROCESSING-DECISION-TREE.md - Tool selection matrix
What Hasn't Changed
✅ All existing functionality works identically:
- Natural language interface
- Skills (nav-start, nav-marker, nav-compact, nav-task, nav-sop, nav-stats, etc.)
- Context markers
- Agents
- Session statistics
✅ Your customizations are preserved:
- CLAUDE.md modifications
- Custom skills
- Project-specific configuration
- Existing markers
Upgrade Options
Option 1: Automatic Upgrade (Recommended)
Steps:
1. Update Navigator plugin
/plugin update navigator
2. Update your project (automatic migration)
"Update my project to Navigator v4.0"
What happens:
- Navigator detects your project version
- Creates
.agent/learning/structure - Adds learning guides, examples, frameworks
- Updates DEVELOPMENT-README with learning references
- Preserves all existing content and customizations
Time: 30 seconds Manual intervention: None required
Option 2: Manual Steps (If automatic fails)
Step 1: Update Plugin
/plugin update navigator
Step 2: Verify Version
"Show Navigator version"
Expected output: 4.0.0
Step 3: Re-initialize Navigator (safe, non-destructive)
"Initialize Navigator in this project"
Navigator will:
- Add missing v4.0 content
- Skip existing files (no overwrite)
- Update references where needed
Step 4: Verify Upgrade
ls -la .agent/learning/
# Should show: CONTEXT-BUDGETS.md, PREPROCESSING-VS-LLM.md, etc.
Option 3: Fresh Installation (New projects only)
For new projects:
/plugin install navigator
"Initialize Navigator in this project"
You get v4.0 by default with all features.
Verification Checklist
After upgrade, verify:
- Plugin version: "Show Navigator version" → 4.0.0
- Learning content exists:
ls .agent/learning/shows guides - Navigator loads: "Start my Navigator session" works
- Skills work: "Create a context marker" works
- Stats work: "Show me my session statistics" works
- Existing markers preserved:
ls .context-markers/shows old markers
What to Explore First
For Teams
Goal: Onboard new developers faster
Share philosophy (30 min read):
.agent/philosophy/CONTEXT-EFFICIENCY.md.agent/philosophy/ANTI-PATTERNS.md.agent/philosophy/PATTERNS.md
Run interactive examples (40 min):
.agent/learning/examples/TRY-THIS-LAZY-LOADING.md.agent/learning/examples/TRY-THIS-AGENT-SEARCH.md.agent/learning/examples/TRY-THIS-MARKERS.md
Bookmark frameworks (ongoing reference):
.agent/learning/frameworks/folder- Quick reference during work
Result: New developers productive in 2-4 hours vs 2-3 days
For Individual Developers
Goal: Master context efficiency principles
Week 1: Read one guide per day
- Monday: CONTEXT-BUDGETS.md (8 min)
- Tuesday: PREPROCESSING-VS-LLM.md (10 min)
- Wednesday: PROGRESSIVE-REFINEMENT.md (9 min)
- Thursday: TOKEN-OPTIMIZATION.md (12 min)
- Friday: Try one interactive example (12 min)
Week 2: Apply to real work
- Use decision frameworks during development
- Check session stats after each session
- Share efficiency scores with team
Result: 70%+ efficiency scores consistently
For Managers/Tech Leads
Goal: Demonstrate ROI
Before v4.0: Collect baseline metrics
- Context crashes per day
- Session restart frequency
- Token usage estimates
After v4.0: Show improvements
- Run "Show me my session statistics" after sessions
- Screenshot efficiency reports (90%+ scores)
- Track time saved (nav-stats reports minutes)
Share results:
- "Navigator saved 42 minutes this session"
- "92% token reduction vs upfront loading"
- "3x longer sessions without restart"
Result: Clear ROI justification for team adoption
Common Questions
Q: Will my existing markers work?
A: Yes. All existing markers are preserved and work identically. No migration needed.
Q: Do I need to read all the learning content?
A: No. It's optional educational material. Your workflows continue unchanged.
Use cases for learning content:
- Onboarding new team members
- Teaching Navigator principles
- Mastering optimization strategies
- Quick reference during work
Q: What if automatic upgrade fails?
A: Use Option 2 (manual steps). Navigator's re-initialization is safe and non-destructive. It only adds missing content.
Q: Can I stay on v3.x?
A: Yes. v3.x continues to work. However:
- v4.0 adds zero breaking changes
- Learning content helps team adoption
- Education layer reduces onboarding time 80%
Recommendation: Upgrade at your next convenient maintenance window.
Q: How do I teach v4.0 to my team?
A: Three-tier approach:
Tier 1 (Everyone): 10-minute intro
- Read CONTEXT-EFFICIENCY.md philosophy
- Try TRY-THIS-LAZY-LOADING.md exercise
- Bookmark frameworks folder
Tier 2 (Power users): 1-hour deep dive
- Read all 4 learning guides
- Complete all 3 interactive examples
- Practice applying frameworks
Tier 3 (Champions): Ongoing mastery
- Study TOKEN-OPTIMIZATION.md thoroughly
- Achieve 85%+ efficiency scores
- Create team-specific patterns
Q: Does v4.0 change how I use Navigator daily?
A: No. Your daily workflow is identical:
Before v4.0:
1. "Start my Navigator session"
2. Work on features
3. "Create a context marker"
4. "Clear context and preserve marker"
After v4.0:
[Exactly the same]
Optionally:
5. "Show me my session statistics" (enhanced in v3.5.0, still works)
6. Reference .agent/learning/frameworks/ for decisions
Rollback (If Needed)
Unlikely to need, but if you want to rollback:
# Downgrade plugin
/plugin install navigator@3.2.0
# Remove v4.0 content (optional)
rm -rf .agent/learning/
# Restore DEVELOPMENT-README (if needed)
git checkout HEAD~1 .agent/DEVELOPMENT-README.md
Note: Your project continues working even without rollback. v4.0 is purely additive.
Support
Issues: https://github.com/alekspetrov/navigator/issues Discussions: https://github.com/alekspetrov/navigator/discussions Release Notes: RELEASE-NOTES-v4.0.0.md
Summary
v4.0 Upgrade:
- ✅ Zero breaking changes
- ✅ Automatic migration
- ✅ 30-second upgrade process
- ✅ All existing functionality preserved
- ✅ New education layer added
- ✅ Onboarding time reduced 80%
Action: Run /plugin update navigator and you're done.
Explore later: .agent/learning/ at your own pace.
Welcome to Navigator v4.0 - The Complete Framework!