WorkBuddy Migration Assistant

Specific Problem Solved

When users need to change computers or perform backup and restoration, migrating personal assets of WorkBuddy domestic version faces multiple challenges. Manually copying the ~/.workbuddy/ directory can lead to incomplete data, path conflicts, or configuration errors. For instance, database files, skill configurations, and conversation histories are scattered across subdirectories, and cross-platform migration (e.g., Mac to Linux) complicates path mapping with opaque conflict handling.

How the Skill Works

This skill addresses migration issues through core capabilities:

• Separated Package Architecture: Exports two independent zip files:
• Main Package (wb-migration-{timestamp}.zip): Contains critical data like databases, skills, configs, and identity, with a small size (10-100 MB) for quick transmission.

• Artifact Package (wb-migration-{timestamp}-workspaces.zip): Includes all file materials under conversation directories (code, reports, images, etc.), optional for transfer, and its failure does not affect main package import.

• Automatic Path Mapping: Uses --auto-map to automatically handle cross-platform path differences (e.g., /Users/ to /home/), or specifies mapping rules manually via --path-map.

• Conflict Detection and Control: Previews conflict reports with dry-run before import, defaulting to merge without overwrite (preserving existing assets on the target) unless --overwrite is explicitly used. Key constraints ensure safe migration:

• Must exit WorkBuddy client before import: Avoids SQLite write lock conflicts.
• Must exclude the current migration session: Prevents zombie sessions on the target, specified via environment variables or --exclude-session-id.
• Must restart client after import: Applies configuration changes.

Applicability and Caveats

This skill is suitable for cross-machine migration scenarios, such as old Mac to new Mac, Mac to Linux, or Windows to Mac. It also supports backup restoration and multi-machine sync. However, it is not applicable for migration between domestic and overseas versions on the same machine (use other dedicated skills). Users should note:

• Asset Scope: Migrates all personal assets but excludes platform-specific binaries (e.g., binaries/), caches (e.g., app/cache/), and temporary logs (e.g., logs/), which are automatically rebuilt on the target.
• Credential Handling: Recommends using --no-credentials to exclude OAuth tokens and other credentials, as they typically expire cross-machine and require re-authorization on the target.
• Debugging Support: Loads detailed documentation via the references/ directory, such as flowcharts, command parameters, and known issues, for troubleshooting.