Migration Guide: Custom Installer to Plugin

Overview

nWave supports two installation methods:

1. Custom installer (nwave-ai install) -- installs to ~/.claude/
2. Plugin -- installs to ~/.claude/plugins/cache/nwave/

Both can coexist. This guide documents how to migrate from the custom installer to the plugin.

Prerequisites

• Claude Code v1.x or later (with plugin support)
• Existing nWave custom installation (optional)

Step 1: Install the Plugin

claude plugin install nw

claude plugin install nw --marketplace https://github.com/nWave-ai/nwave-plugin

Step 2: Verify Plugin Works

Run a quick verification:

/nw-deliver "test-feature"

Verify:

• Agent discovery works (agents loaded from plugin)
• DES enforcement active (hook responses visible)
• Commands available (/nw- prefix works)

Step 3: Remove Custom Installer (Optional)

If you want to fully migrate:

nwave uninstall

This removes:

• ~/.claude/agents/nw/
• ~/.claude/commands/nw/
• ~/.claude/skills/nw/
• ~/.claude/lib/python/des/
• DES hooks from ~/.claude/settings.json

The plugin remains unaffected because it uses a completely separate directory tree.

Coexistence Notes

• Path separation: Plugin files live in ~/.claude/plugins/cache/nwave/, custom installer files in ~/.claude/agents/nw/ etc. No overlap.
• Hook isolation: Plugin hooks are in plugin/hooks/hooks.json, installer hooks in ~/.claude/settings.json. Claude Code merges them.
• Version conflicts: If both are active with different versions, Claude Code uses the plugin version. No errors, but may see duplicate agents in autocomplete.
• Recommendation: Run one installation method at a time for cleanest experience.

Verification Checklist

After migration, verify:

• /nw-deliver executes successfully
• DES enforcement blocks incorrect tool use during TDD phases
• Agent definitions are discovered (23 agents visible)
• All commands available (/nw-design, /nw-discuss, etc.)
• Skills load on demand (check agent output references skills)

Rollback

To rollback to custom installer:

1. Remove plugin: claude plugin uninstall nw
2. Reinstall custom: nwave-ai install