PAI v2.3 Migration Guide - Example migration from v1.x to v2.3

PAI-2.3-Migration-Guide.md

PAI 2.3 Migration Guide

Example migration from PAI v1.x to PAI v2.3

---

Progress Tracker

Phase 1: Prepare

• Research upstream changes
• Create migration plan
• Document plan

Phase 2: Create Fresh 2.3 Environment

• Clone upstream repo to ~/Documents/src/PAI-v2.3/
• Checkout v2.3.0 tag
• Copy release to ~/.claude-v2.3-staging/
• Backup v1.x to ~/Documents/backups/
• Revert v1.x repo settings.json to clean state
• Remove ~/.claude symlink, copy fresh v2.3
• Run install wizard (verify voice server works)
• Save vanilla baseline (e.g., ~/Documents/src/PAI-baselines/pai-2.3-vanilla)
• Set up source control (symlink pattern)
  • Create private repo for your PAI fork
  • Move ~/.claude to ~/Documents/src/PAI-v2.3-dev/.claude
  • Create symlink ~/.claude → PAI-v2.3-dev/.claude
  • Configure remotes: origin (private), fork (public), upstream (danielmiessler)
  • Initial commit: "feat: Initial PAI v2.3 vanilla baseline"
  • Push to origin/main

Phase 3: Environment Switching

• Install pai-switch script (enables toggling between v1/v2)
• Test switching between versions

Phase 3b: Personal Data Version Control

• Set up personal data repo (separate from PAI core)
  • Create private repo for personal data
  • Move MEMORY/USER/WORK to separate directory
  • Create symlinks from ~/.claude to personal data repo
  • Initial commit and push
• Copy .env from v1.x (API keys)
• Validate v2.3 in new Claude session

Phase 4: Migrate Custom Skills

• Rename skills with _ prefix (personal/work skills use _ALLCAPS convention)
• Migrate skill customizations to SKILLCUSTOMIZATIONS/ directory
• Update USE WHEN triggers in SKILL.md files

Phase 5: Migrate Configuration

• .env (API keys)
• profiles/ (any tool profiles like jira, coupa, etc.)
• hooks - kept v2.3 hooks (review for compatibility)
• CLIs migrated to bin/ directory

Phase 6: Validation

• Skills recognized (check startup banner)
• CLIs working (test each one)
• Run tests if available
• System integrity check passed
• Personal data symlinks verified

Phase 7: Cutover

• Switch to v2.3 production: update ~/.claude symlink
• Save post-migration baseline
• Verify functionality in production

---

Key Decisions

Decision	Rationale
Use staging location (~/.claude-v2.3-staging)	Keep v1.x production running during migration
Save vanilla baseline before customizing	Enable quick restore if testing breaks
Use symlink pattern for source control	Keeps full repo structure, easy to update
Separate personal data repo	Keeps sensitive data isolated from PAI core

---

Tips

1. PAI_DIR must use absolute path - The default settings.json may use ~/.claude which doesn't expand in hook execution. Change to absolute path like /Users/yourname/.claude.

2. Test in staging first - Don't overwrite your working v1.x installation until v2.3 is fully validated.

3. Save baselines - Copy your vanilla and migrated states to separate directories for easy rollback.

4. Symlink architecture - The recommended pattern:

   ~/.claude → ~/Documents/src/PAI-v2.3-dev/.claude  (your fork)
   ~/.claude/MEMORY → ~/Documents/src/pai-personal-data/MEMORY
   ~/.claude/USER → ~/Documents/src/pai-personal-data/USER
   ~/.claude/WORK → ~/Documents/src/pai-personal-data/WORK
   

5. Three remotes for contributions:

   • origin - your private fork (main working copy)
   • fork - your public fork (for PRs)
   • upstream - danielmiessler/PAI (official repo)

---

Final State Example

Source Control

Repo	Purpose
~/.claude	Your private PAI fork
pai-personal-data	Private personal data (MEMORY/USER/WORK)
pai-tooling	Optional: shared tooling/scripts

Active Symlinks

~/.claude → ~/Documents/src/PAI-v2.3-dev/.claude
~/.claude/MEMORY → pai-personal-data/MEMORY
~/.claude/USER → pai-personal-data/USER
~/.claude/WORK → pai-personal-data/WORK

Baselines Available

• pai-2.3-vanilla (clean v2.3 before customization)
• pai-2.3-migrated (with all personal skills migrated)