tools-only Migration Guide: v2.x → v3.0
Navigator v3.0 removes all slash commands in favor of natural language. This guide helps you migrate smoothly.
🚨 Breaking Changes
Commands Removed
All /nav:* and /jitd:* commands have been deleted:
- /nav:init
- /nav:start
- /nav:doc
- /nav:marker
- /nav:markers
- /nav:compact
- /nav:migrate
- /jitd:* (all backward-compat commands)
Natural Language Only
Navigator v3.0 uses skills that auto-invoke based on your intent. Just describe what you want in natural language.
📋 Command → Natural Language Map
Session Management
| Old Command (v2.x) | Natural Language (v3.0) |
|---|---|
/nav:start |
"Start my Navigator session" |
"Load the navigator" |
|
"Begin working on this project" |
Example:
- /nav:start
+ "Start my Navigator session"
Initialization
| Old Command (v2.x) | Natural Language (v3.0) |
|---|---|
/nav:init |
"Initialize Navigator in this project" |
"Set up Navigator documentation structure" |
Example:
- /nav:init
+ "Initialize Navigator in this project"
Documentation
| Old Command (v2.x) | Natural Language (v3.0) |
|---|---|
/nav:doc feature TASK-XX |
"Archive TASK-XX documentation" |
"Document this completed feature" |
|
/nav:doc sop debugging [issue] |
"Create an SOP for debugging [issue]" |
"Document this solution as a procedure" |
|
/nav:doc system architecture |
"Update system architecture documentation" |
Example:
- /nav:doc feature TASK-45
+ "Archive TASK-45 documentation"
Context Management
| Old Command (v2.x) | Natural Language (v3.0) |
|---|---|
/nav:marker checkpoint |
"Create a marker called checkpoint" |
"Save my progress as checkpoint" |
|
/nav:markers |
"Show my markers" |
"Load a marker" |
|
"Clean up old markers" |
|
/nav:compact |
"Clear context and preserve markers" |
"Smart compact" |
Example:
- /nav:marker feature-complete
- /nav:compact
+ "Create a marker called feature-complete"
+ "Clear context and preserve markers"
Migration (Removed)
| Old Command (v2.x) | v3.0 Status |
|---|---|
/nav:migrate |
Not needed - All skills work automatically |
🔄 Complete Workflow Examples
Before (v2.x)
# Start session
/nav:start
# Work on feature
"Implement user authentication"
# Save progress
/nav:marker auth-started
# Complete feature
/nav:doc feature TASK-12
# Clean up
/nav:compact
After (v3.0)
# Start session
"Start my Navigator session"
# Work on feature
"Implement user authentication"
# Save progress
"Create a marker called auth-started"
# Complete feature
"Archive TASK-12 documentation"
# Clean up
"Clear context and preserve markers"
Same functionality, simpler syntax!
🛠️ Migration Steps
Step 1: Update Navigator Plugin
/plugin update navigator
# Restart Claude Code
Step 2: Start Using Natural Language
No configuration needed! All skills work immediately.
Try it:
"Start my Navigator session"
The nav-start skill will auto-invoke.
Step 3: Update Your CLAUDE.md (Optional)
If you customized your project's CLAUDE.md, update command references:
Before:
### Quick Reference
1. Run /nav:start (loads navigator)
2. /nav:doc feature TASK-XX when done
3. /nav:compact to clear context
After:
### Quick Reference
1. "Start my Navigator session" (loads navigator)
2. "Archive TASK-XX documentation" when done
3. "Clear context and preserve markers" to clear context
You can use the updated template from:
https://github.com/alekspetrov/navigator/blob/main/templates/CLAUDE.md
Step 4: Verify Skills Work
Test each skill with natural language:
"Start my Navigator session"
→ nav-start activates ✅
"Create a marker called test"
→ nav-marker activates ✅
"Archive TASK-99 documentation"
→ nav-task activates ✅
"Clear context and preserve markers"
→ nav-compact activates ✅
💡 Tips for Natural Language
Be Conversational
Skills understand various phrasings:
✅ "Start my Navigator session"
✅ "Load the navigator"
✅ "Begin working on this project"
✅ "Initialize my session"
All activate nav-start.
Use Action Verbs
✅ "Create a marker called checkpoint"
✅ "Archive TASK-45 documentation"
✅ "Show my markers"
✅ "Clear context and preserve markers"
Skills detect intent from verbs like "create", "archive", "show", "clear".
Be Specific When Needed
✅ "Create a marker called feature-complete"
(better than just "marker")
✅ "Archive TASK-45 documentation"
(better than just "document this")
❓ FAQ
Q: Do my old projects still work?
A: Yes! Projects using v2.x skills work perfectly with v3.0. Skills are unchanged - only commands were removed.
Q: What if I forget the natural language phrases?
A: No problem! Skills are forgiving. Try different phrasings:
- "Start session" → works
- "Load navigator" → works
- "Begin working" → works
The skill descriptions in v3.0 support multiple trigger phrases.
Q: Can I still use commands?
A: No. Commands are completely removed in v3.0. Natural language is the only interface.
If you need commands, stay on v2.3.0 (which is still supported).
Q: What if a skill doesn't activate?
A: Try rephrasing:
❌ "Do the start thing"
(too vague)
✅ "Start my Navigator session"
(clear intent)
If issues persist, check the skill descriptions in skills/*/SKILL.md.
Q: Are there any new features besides natural language?
A: Not in v3.0. This release is purely about removing commands and improving UX.
New features coming in v3.1+:
- test-generator skill
- doc-generator skill
- session-analytics skill
🔍 Troubleshooting
Skill Doesn't Activate
Problem: You say "Start session" but nav-start doesn't activate.
Solutions:
- Be more specific: "Start my Navigator session"
- Use alternative phrasing: "Load the navigator"
- Check Claude Code version (needs skills support)
Can't Find Marker
Problem: "Load marker" doesn't work.
Solution: Be specific about which marker:
✅ "Load the feature-complete marker"
✅ "Show my markers" (to see available markers)
Documentation Not Archiving
Problem: Task documentation doesn't archive.
Solution: Specify the task ID:
❌ "Document this"
✅ "Archive TASK-45 documentation"
📊 Benefits of v3.0
Token Savings
v2.x: Commands overhead = 11k tokens
v3.0: Commands overhead = 0 tokens
Savings: +11k tokens available
Simpler UX
v2.x: Must remember 13 command syntaxes
v3.0: Just describe what you want
Learning curve: -50%
Faster Onboarding
v2.x: "Type /nav:start to begin"
v3.0: "Start my Navigator session"
Time to productivity: -40%
🚀 Next Steps
After Migration
Update your workflow:
- Replace commands with natural language
- Update any documentation/notes
Share with team:
- Natural language is easier to teach
- No syntax to explain
Explore v3.1+ roadmap:
- test-generator skill (coming soon)
- doc-generator skill
- session-analytics skill
Need Help?
- GitHub Issues: https://github.com/alekspetrov/navigator/issues
- Release Notes: https://github.com/alekspetrov/navigator/releases/tag/v3.0.0
- Documentation: https://github.com/alekspetrov/navigator
📝 Quick Reference Card
Print this for quick lookup:
┌─────────────────────────────────────────────────────┐
│ Navigator v3.0 Natural Language Quick Reference │
├─────────────────────────────────────────────────────┤
│ │
│ Start Session: │
│ "Start my Navigator session" │
│ │
│ Initialize Project: │
│ "Initialize Navigator in this project" │
│ │
│ Archive Task: │
│ "Archive TASK-XX documentation" │
│ │
│ Create SOP: │
│ "Create an SOP for debugging [issue]" │
│ │
│ Save Progress: │
│ "Create a marker called [name]" │
│ │
│ Manage Markers: │
│ "Show my markers" │
│ "Load the [name] marker" │
│ │
│ Clear Context: │
│ "Clear context and preserve markers" │
│ │
└─────────────────────────────────────────────────────┘
Welcome to Navigator v3.0! Natural language, 97% token reduction, zero commands to remember. 🚀
Migration complete? Start your next session with:
"Start my Navigator session"