Workspace Migration Skill

A Claude Code skill for migrating code between projects, refactoring directory structures, moving files with dependency updates, and reorganizing workspace layouts while preserving import paths and references.

When to Use This Skill

Choose this skill when:

• Moving code between repositories or projects
• Reorganizing directory structure (e.g., flat to feature-based)
• Extracting modules into separate packages
• Merging multiple projects into a monorepo
• Renaming files and updating all import references
• Splitting a monolith into multiple services

Consider alternatives when:

• You need to move a single file (just move it and fix imports)
• You need git history preservation (use git filter-repo)
• You need dependency migration (use a dependency management skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add move-workspace

# Reorganize project structure
claude "reorganize src/ from flat structure to feature-based modules"

# Move code between projects
claude "extract the auth module from this project into a separate package"

Copy
# Common move operations
# Move file and update imports
git mv src/utils/auth.ts src/features/auth/utils.ts
# Then update all import references across the codebase

# Reorganize directory structure
# src/components/UserList.tsx → src/features/users/components/UserList.tsx
# src/services/userService.ts → src/features/users/services/userService.ts
# src/types/user.ts → src/features/users/types.ts

Core Concepts

Migration Patterns

Pattern	From	To	Complexity
File Rename	auth.ts	authentication.ts	Low
Directory Move	src/utils/	src/lib/	Medium
Feature Grouping	Flat src/	src/features/*/	High
Package Extract	Monolith module	packages/auth/	High
Monorepo Merge	Multiple repos	apps/ + packages/	Very High

Import Update Strategy

Copy
// Before: Flat structure
import { authService } from '../services/authService';
import { UserType } from '../types/user';
import { AuthForm } from '../components/AuthForm';

// After: Feature-based structure
import { authService } from '@/features/auth/services/authService';
import { UserType } from '@/features/auth/types';
import { AuthForm } from '@/features/auth/components/AuthForm';

// Use path aliases in tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/features/*": ["./src/features/*"]
    }
  }
}

Monorepo Migration

# Before: Separate repos
repo-frontend/
repo-backend/
repo-shared/

# After: Monorepo with Turborepo
monorepo/
├── apps/
│   ├── frontend/
│   └── backend/
├── packages/
│   └── shared/
├── turbo.json
└── package.json

Configuration

Parameter	Type	Default	Description
update_imports	boolean	true	Auto-update import paths after moves
update_tests	boolean	true	Update test file imports and paths
preserve_git_history	boolean	true	Use git mv for history preservation
dry_run	boolean	false	Preview changes without applying
path_aliases	boolean	true	Use tsconfig path aliases
backup	boolean	true	Create backup before large moves

Best Practices

1. Make one move at a time and verify — move one file or directory, update imports, run tests, and commit before moving the next; this makes it easy to bisect issues.

2. Use git mv to preserve file history — git mv tells git that a file was renamed, preserving blame history; regular mv + git add may be detected as delete+create.

3. Set up path aliases before reorganizing — configure @/ aliases in tsconfig.json so imports reference the alias rather than relative paths; this makes future moves easier since only the alias mapping needs to change.

4. Update all references in a single pass — use find-and-replace across the codebase to update import paths, test paths, configuration references, and documentation links in one operation.

5. Run the full test suite after each move — moved files may have implicit dependencies (shared state, import order, environment setup) that only surface when tests run.

Common Issues

Circular dependencies emerge after reorganization — Moving files can expose circular imports that were hidden by the previous structure. Use a tool like madge to detect circular dependencies and restructure to break cycles.

Build fails after move despite correct imports — Build tool caches (webpack, Next.js) may hold stale references. Clear .next/, dist/, and node_modules/.cache/ after reorganization.

Git shows file as deleted and created instead of moved — If too much content changes alongside the move, git can't detect the rename. Make the move in a separate commit without content changes, then modify the content in the next commit.