| name | agent-ops-migrate |
| description | Migrate a project into another, ensuring functionality and validating complete content transfer. Use for monorepo consolidation, template upgrades, or codebase mergers. |
| category | extended |
| invokes | ["agent-ops-project-sections","agent-ops-baseline","agent-ops-validation","agent-ops-interview"] |
| invoked_by | ["User request"] |
| state_files | {"read":["focus.md","constitution.md","baseline.md"],"write":["focus.md"]} |
Project Migration Workflow
Purpose
Migrate code, configuration, and content from a source project into a target project while:
- Ensuring the target project works after migration
- Validating all content has been transferred
- Handling conflicts and incompatibilities
- Providing rollback capability if issues arise
When to Use
- Consolidating multiple projects into a monorepo
- Upgrading from an old project template to a new one
- Merging two codebases
- Moving functionality between projects
- Adopting a new framework while preserving logic
Migration Types
| Type | Description | Complexity |
|---|
| Full merge | Entire source → target | High |
| Selective | Specific modules/features only | Medium |
| Template upgrade | Apply new template, preserve custom code | Medium |
| Framework migration | Change underlying framework | High |
| Monorepo consolidation | Multiple repos → single repo | High |
Procedure
Phase 1: Pre-Migration Analysis
-
Scan source project using agent-ops-project-sections:
- Identify all sections and their dependencies
- Map file structure
- Identify configuration files
- Note external dependencies
-
Scan target project (if exists):
- Identify existing structure
- Note potential conflicts
- Check compatibility
-
Create migration manifest:
migration:
source: /path/to/source
target: /path/to/target
type: full_merge | selective | template_upgrade
sections:
- name: api
source_path: src/api/
target_path: src/api/
action: copy | merge | skip
- name: config
source_path: config/
target_path: config/
action: merge
conflicts: [.env, settings.py]
Phase 2: Dependency Analysis
-
Compare dependency files:
package.json vs package.jsonpyproject.toml vs pyproject.toml*.csproj vs *.csproj
-
Identify conflicts:
- Version mismatches
- Incompatible packages
- Missing dependencies
-
Create dependency resolution plan:
## Dependency Conflicts
| Package | Source Ver | Target Ver | Resolution |
|---------|------------|------------|------------|
| lodash | 4.17.21 | 4.17.15 | Use source (newer) |
| react | 17.0.2 | 18.2.0 | Use target (newer) |
| custom-lib | 1.0.0 | — | Add to target |
Phase 3: Conflict Resolution
For each identified conflict:
-
File conflicts (same path, different content):
- Compare files
- Determine merge strategy: source wins / target wins / manual merge
- Create backup of target version
-
Naming conflicts:
- Rename with prefix/suffix
- Update all references
-
Configuration conflicts:
- Merge non-overlapping settings
- Flag overlapping settings for user decision
Present conflicts to user:
## Migration Conflicts Detected
### File Conflicts (3)
1. `src/config.ts` — Different database settings
→ [S]ource / [T]arget / [M]erge manually
2. `package.json` — Different scripts
→ [S]ource / [T]arget / [M]erge manually
3. `.env.example` — Different variables
→ [S]ource / [T]arget / [M]erge manually
### Dependency Conflicts (2)
1. lodash: 4.17.21 (source) vs 4.17.15 (target)
→ Using source version (newer)
2. typescript: 4.9.5 (source) vs 5.0.0 (target)
→ Using target version (newer)
Proceed with these resolutions? [Y]es / [E]dit / [C]ancel
Phase 4: Baseline Capture
Before any migration:
-
Capture target baseline (if target exists):
- Run build
- Run tests
- Record state
-
Document pre-migration state:
## Pre-Migration Baseline
Target: /path/to/target
Date: YYYY-MM-DD
- Build: ✅ passing
- Tests: 142 passing, 0 failing
- Lint: 0 errors
Backup: .migration-backup/
Phase 5: Execute Migration
Execute in order, with validation checkpoints:
-
Create backup:
cp -r target/ .migration-backup/target-YYYYMMDD-HHMMSS/
-
Copy/merge files per manifest:
- Track each file operation
- Log any errors
-
Update imports/references:
- Find and replace import paths
- Update configuration references
-
Merge dependencies:
- Combine dependency files
- Resolve versions per plan
-
Run build (checkpoint):
- If fails: diagnose, fix, or rollback
-
Run tests (checkpoint):
- If fails: diagnose, fix, or rollback
Phase 6: Validation
-
Content validation:
- Compare file counts source vs copied
- Verify critical files present
- Check for orphaned references
-
Functionality validation:
- Build passes
- Tests pass (or expected failures documented)
- Lint passes (or expected issues documented)
-
Generate migration report:
## Migration Report
### Summary
- Files copied: 127
- Files merged: 8
- Files skipped: 3 (test fixtures)
- Conflicts resolved: 5
### Build Status
- Before: ✅ (142 tests)
- After: ✅ (189 tests)
### New Dependencies Added
- lodash@4.17.21
- custom-lib@1.0.0
### Manual Follow-ups Required
- [ ] Review merged config in src/config.ts
- [ ] Update CI/CD pipeline for new structure
- [ ] Update documentation
Phase 7: Rollback (if needed)
If migration fails validation:
-
Restore from backup:
rm -rf target/
mv .migration-backup/target-YYYYMMDD-HHMMSS/ target/
-
Document failure:
## Migration Rollback
Reason: Test failures in auth module
Restored: target/ from backup
Issues to resolve before retry:
- [ ] Incompatible auth library versions
- [ ] Missing environment variables
-
Create issues for blocking problems
Migration Manifest Schema
migration:
source: string
target: string
type: full_merge | selective | template_upgrade | framework
created: YYYY-MM-DD
backup:
enabled: true
path: .migration-backup/
sections:
- name: string
source_path: string
target_path: string
action: copy | merge | skip | transform
transform_script: string
dependencies:
strategy: source_wins | target_wins | newest | manual
overrides:
- package: string
version: string
Completion Criteria
Anti-patterns (avoid)
- ❌ Migrating without backup
- ❌ Ignoring test failures
- ❌ Overwriting target files without merge consideration
- ❌ Skipping dependency conflict resolution
- ❌ Not validating after migration
- ❌ Migrating to production without staging test
Examples
Example 1: Monorepo Consolidation
Scenario: Merge auth-service and user-service into platform monorepo.
Migration: Monorepo Consolidation
Source 1: /repos/auth-service → platform/services/auth/
Source 2: /repos/user-service → platform/services/user/
Shared dependencies moved to: platform/packages/shared/
Result:
platform/
├── services/
│ ├── auth/ # from auth-service
│ └── user/ # from user-service
├── packages/
│ └── shared/ # common code extracted
└── package.json # workspace config
Example 2: Template Upgrade
Scenario: Upgrade project from old create-react-app to Vite template.
Migration: Template Upgrade (CRA → Vite)
Preserve:
- src/components/
- src/hooks/
- src/services/
- Custom configurations
Replace:
- Build system (webpack → vite)
- Config files (react-scripts → vite.config.ts)
- Entry point structure
Transform:
- Import aliases
- Environment variable prefix (REACT_APP_ → VITE_)
