2724 Task 12 V30 Skills Only 355da89e

TASK-12: v3.0 Skills-Only Migration

Status: 📋 In Progress Version: 3.0.0 Created: 2025-10-19 Type: Breaking Change (Major Version)

Executive Summary

Goal: Remove all slash commands, make Navigator 100% skills-only with natural language interface.

Impact:

• 11k token reduction (commands overhead eliminated)
• Natural language only ("Start my session" vs /nav:start)
• Cleaner architecture (no hybrid overhead)
• Breaking change (v3.0 major version bump)

Timeline: Accelerated (skip v2.5 deprecation phase)

Context

Current State (v2.3.0)

Hybrid Architecture:

• ✅ 12 skills (7 core + 5 project-specific + nav-markers)
• ⚠️ 13 commands (7 main + 6 backward-compatible)
• Both work simultaneously (no conflicts)

File Structure:

navigator/
├── commands/               # TO BE REMOVED
│   ├── init.md
│   ├── start.md
│   ├── doc.md
│   ├── marker.md
│   ├── markers.md
│   ├── compact.md
│   ├── migrate.md
│   ├── _jitd_init.md       # v1.x compat
│   ├── _jitd_start.md
│   ├── _jitd_marker.md
│   ├── _jitd_markers.md
│   ├── _jitd_compact.md
│   └── _jitd_update_doc.md
│
└── skills/                 # KEEP
    ├── nav-start/
    ├── nav-marker/
    ├── nav-markers/
    ├── nav-compact/
    ├── nav-task/
    ├── nav-sop/
    ├── nav-skill-creator/
    ├── plugin-slash-command/
    ├── frontend-component/
    ├── backend-endpoint/
    ├── database-migration/
    ├── backend-test/
    └── frontend-test/

Why Skip v2.5 Deprecation Phase?

Original Plan (TASK-07):

• v2.5: Add deprecation warnings, 6-month migration
• v3.0: Remove commands after user adoption

New Plan (Accelerated):

• v3.0: Remove commands immediately
• Users already have skills (v2.0-v2.3)
• Natural language works today

Rationale:

1. Skills work perfectly (proven in v2.0-v2.3)
2. No user complaints about natural language
3. Deprecation overhead unnecessary (skills auto-invoke)
4. Cleaner faster (skip 6-month warning period)

Implementation Plan

Phase 1: Preparation ✅ (Already Done)

Status: Complete (v2.0-v2.3)

• All core skills created (nav-start, nav-marker, etc.)
• Skills tested and working
• Auto-invocation verified
• Natural language interface proven

Phase 2: Breaking Changes (v3.0)

Step 1: Remove Commands Directory

rm -rf commands/

Step 2: Update plugin.json

{
  "name": "navigator",
  "version": "3.0.0",
  "commands": [],  // Empty - no commands
  "skills": [
    "./skills/nav-start",
    "./skills/nav-marker",
    "./skills/nav-markers",
    "./skills/nav-compact",
    "./skills/nav-task",
    "./skills/nav-sop",
    "./skills/nav-skill-creator",
    "./skills/plugin-slash-command",
    "./skills/frontend-component",
    "./skills/backend-endpoint",
    "./skills/database-migration",
    "./skills/backend-test",
    "./skills/frontend-test"
  ]
}

Step 3: Update marketplace.json

{
  "plugins": [
    {
      "id": "navigator",
      "version": "3.0.0",
      "breaking_changes": [
        "Removed all slash commands (/nav:*)",
        "Use natural language instead",
        "Skills auto-invoke based on intent"
      ]
    }
  ]
}

Step 4: Update CLAUDE.md Template

Remove all command references:

- /nav:init          # Initialize Navigator
- /nav:start         # Start session
+ "Initialize Navigator in this project"
+ "Start my Navigator session"

Update workflow examples to show natural language only.

Step 5: Update README.md

Remove slash commands section, add migration guide:

## 🚨 Breaking Change: v3.0

Navigator v3.0 removes all slash commands. Use natural language instead.

### Migration Guide

**Before (v2.x)**:

/nav:init /nav:start /nav:marker checkpoint

**After (v3.0)**:

"Initialize Navigator in this project" "Start my Navigator session" "Create a checkpoint marker"

Skills auto-invoke - no manual commands needed.

Step 6: Update Documentation

Files to update:

• .agent/DEVELOPMENT-README.md - Remove command references
• .agent/system/project-architecture.md - Skills-only architecture
• templates/CLAUDE.md - Natural language examples
• README.md - Migration guide + v3.0 announcement

Testing Plan

Manual Testing

Test 1: Init without command

User: "Initialize Navigator in this project"
Expected: nav-init skill auto-invokes
Result: [ ]

Test 2: Start without command

User: "Start my Navigator session"
Expected: nav-start skill auto-invokes
Result: [ ]

Test 3: Marker without command

User: "Create a checkpoint marker called feature-complete"
Expected: nav-marker skill auto-invokes
Result: [ ]

Test 4: Task documentation without command

User: "Archive this task documentation"
Expected: nav-task skill auto-invokes
Result: [ ]

Test 5: Compact without command

User: "Clear context but preserve markers"
Expected: nav-compact skill auto-invokes
Result: [ ]

Test in nav-test Project

cd ~/Projects/tmp/nav-test
rm -rf .agent  # Clean slate

# Test init
"Initialize Navigator in this project"
→ Should create .agent/ structure

# Test start
"Start my Navigator session"
→ Should load navigator, show stats

# Test marker
"Create a marker called test-checkpoint"
→ Should create marker file

# Test compact
"Clear context and preserve markers"
→ Should create active marker

Migration Guide for Users

For Existing Navigator Users (v2.x → v3.0)

You need to change: Nothing (if you use natural language) You need to stop: Using /nav:* commands (they're gone)

Command → Natural Language Map:

Skills auto-invoke - just describe what you want.

For New Users (v3.0)

No commands to learn!

Just tell Claude what you want:

• "Initialize Navigator"
• "Start my session"
• "Create a checkpoint"
• "Archive this task"

Skills automatically activate based on your intent.

Version Sync Checklist

Before v3.0 release, update ALL version references:

• .claude-plugin/plugin.json → "version": "3.0.0"
• .claude-plugin/marketplace.json → "version": "3.0.0"
• .agent/.nav-config.json → "version": "3.0.0"
• README.md line ~5 → v3.0.0
• README.md line ~8 (badge) → 3.0.0
• README.md footer → 3.0.0
• .agent/DEVELOPMENT-README.md bottom → (v3.0.0)
• Git tag → v3.0.0
• GitHub release → v3.0.0

Run audit script:

./scripts/version-audit.sh 3.0.0

Risks & Mitigation

Risk 1: Users Still Type Commands

Problem: Muscle memory - users type /nav:start Impact: Command not found error Mitigation:

• Clear error message: "Commands removed in v3.0. Use: 'Start my Navigator session'"
• Migration guide in README
• v3.0 announcement explains change

Likelihood: High (first week) Severity: Low (easy fix)

Risk 2: Skill Auto-Invocation Fails

Problem: Natural language doesn't match skill description Impact: Skill doesn't activate Mitigation:

• Comprehensive skill descriptions
• Multiple trigger phrases documented
• Test with various phrasings

Likelihood: Low (skills tested in v2.x) Severity: Medium (user confusion)

Risk 3: Breaking Change Adoption

Problem: Users refuse to upgrade to v3.0 Impact: Stuck on v2.3 forever Mitigation:

• v2.3 still works (no forced upgrade)
• Migration guide makes it easy
• Natural language is easier than commands

Likelihood: Low (upgrade is easier, not harder) Severity: Low (v2.3 is stable)

Success Metrics

Token Efficiency

• Commands overhead: 0 tokens (vs 11k in v2.x)
• Skills overhead: ~250 tokens (12 skills)
• Total documentation: <6k tokens
• Available context: >194k tokens (vs 184k in v2.x)

User Experience

• Natural language success rate: >90%
• New user onboarding: -50% time (no commands to learn)
• User satisfaction: +40% (simpler)

Code Quality

• Zero slash command files
• Clean skills-only architecture
• No hybrid overhead

Rollout Plan

Step 1: Development (This Task)

• Remove commands directory
• Update plugin.json (commands: [])
• Update all documentation
• Test in nav-test project
• Verify all skills work via natural language

Step 2: Testing (1 day)

• Test every skill with natural language
• Verify auto-invocation works
• Test in fresh project
• Confirm no regressions

Step 3: Documentation (1 day)

• Update README.md with migration guide
• Update CLAUDE.md template
• Update .agent/ docs
• Create v3.0 announcement

Step 4: Release (1 day)

• Run version audit script
• Commit: "feat!: v3.0 skills-only architecture (breaking)"
• Push to GitHub
• Tag: v3.0.0
• Create GitHub release with migration guide
• Update marketplace.json

Step 5: Community (Post-Release)

• Announce on GitHub
• Share migration guide
• Monitor for issues
• Help users migrate

Breaking Changes (v3.0.0)

BREAKING: Removed all slash commands (/nav:*)

Migration:

• Replace /nav:start with "Start my Navigator session"
• Replace /nav:init with "Initialize Navigator in this project"
• Replace /nav:marker name with "Create a marker called [name]"
• All other commands → natural language equivalents

Skills auto-invoke based on intent - no manual invocation needed.

Post-v3.0 Roadmap

What's Next After v3.0:

v3.1: Enhanced Skills

• More built-in skills (test-generator, doc-generator, config-generator)
• Improved auto-invocation accuracy
• Multi-skill coordination

v3.2: Analytics

• session-analytics skill (real-time token tracking)
• Usage metrics dashboard
• ROI proof for teams

v3.x: Platform Features

• Skill marketplace (share skills)
• Skill versioning
• Cross-project sync
• Skill dependencies

Framework skills skipped (not critical, community can generate)

Related Tasks

• TASK-07: Skills migration strategy (planning phase)
• TASK-08: Skills enhancements v2.1 (foundation)
• TASK-10: nav-skill-creator implementation (self-improving)
• TASK-11: Project-specific skills v2.3 (5 skills generated)

Notes

Why This Is the Right Move

1. Skills proven (6 months in production: v2.0-v2.3)
2. Natural language easier (no syntax to remember)
3. Cleaner architecture (no hybrid complexity)
4. 11k token savings (commands overhead gone)
5. Future-proof (skills-first is Claude's direction)

What We're NOT Doing

❌ Framework skills (React, Vue, Express, etc.)

• Reason: Not critical for v3.0
• Community can generate via nav-skill-creator
• Focus on core platform first

❌ Deprecation phase (v2.5 with warnings)

• Reason: Unnecessary delay
• Skills already work
• Users already using natural language

❌ Skill marketplace (sharing platform)

• Reason: v3.x feature (after v3.0 stable)
• Need user adoption first
• Focus on core migration

Timeline

Total Effort: 3 days

• Day 1: Remove commands, update plugin.json, update docs
• Day 2: Test thoroughly, verify auto-invocation
• Day 3: Release v3.0, announce, monitor

Target Release: 2025-10-22 (3 days from now)

Task created: 2025-10-19 Priority: High (major version) Effort: Small (3 days - cleanup work) Impact: Very High (breaking change, cleaner architecture, 11k token savings)