project-migrate

Migration between projects

Document a migration between two projects in three steps:

1. Discovery (discovery.md): infer the technology stack of both projects and map the equivalences between source and target.
2. Validation preparation (validation.md + folder validation/): from the Golden Master Testing opportunities of the discovery, prepare the validation cases and gather their inputs (reference inputs/outputs).
3. Plan (plan.md): from the discovery and the validation, define the current state, the proposed change, the Golden Master validation and the implementation plan.

The user indicates what is going to be migrated and from which source project to which target project. All files are generated inside the migration folder in the target project.

The flow is sequential and with gates: do not advance to the next step while the document of the previous step is not in Ready.

When the plan ends, this skill offers to continue with the implementation: if the user accepts and the plan.md is in Ready, it does handoff to the skill work-implement (see "Continue with the implementation" in references/flow.md).

The detailed procedure of the three steps, the detail of the fragmented target and the handoff live in references/flow.md. Here the summary and the pointers remain.

Language resolution

The language of the generated documents (discovery.md, validation.md, plan.md) and of the messages to the user is decided in this order; stop at the first step that applies:

1. If a user language preference exists in the session context, use it.
2. If not, use the language of the user's message and ask the user whether they want to persist their language preference in memory.
3. If it cannot be inferred, ask the user which language they prefer and, after their answer, ask whether they want to persist their language preference in memory; do not decide the language on your own.

Migration folder structure

Each migration lives in <destino>/docs/specs/migrations/MG-XXX-{slug}/:

docs/specs/migrations/
└── MG-XXX-{slug}/
    ├── discovery.md    # Paso 1
    ├── validation.md   # Paso 2
    ├── validation/     # recursos de validación (JSON, imágenes, Mermaid, …)
    └── plan.md         # Paso 3

Inputs you need from the user

1. What is going to be migrated (a module, a feature, dependencies, the whole project, etc.).
2. Source project and target project(s): ideally the paths to the repos/folders. The target can be one or several projects (e.g., a monolith that is split into several services). If you are only given descriptions, work with that information, but record the assumptions.

If any of these data are missing, ask for them briefly before continuing. Do not invent paths or stacks.

Single destination vs. fragmented destination

• Single destination: run the flow only once and generate discovery.md, validation.md (with its folder validation/) and plan.md in that destination project.
• Fragmented destination (the source is split across several destination projects): each destination project must have its own migration folder with its discovery.md, validation.md and plan.md scoped to the portion of the source it receives. Use the same MG-XXX-{slug} in all projects (calculate XXX as the next free sequential number considering the highest number among all the docs/specs/migrations/ involved). Full details in references/flow.md.

When the destination is fragmented, "the destination" refers to each destination project.

Summary of the three steps

The detailed procedure for each step is in references/flow.md. Each document is generated by copying its template from assets/ and renaming it; the template indicates how to fill it in.

1. Discovery (discovery.md) — template assets/discovery-template.md. Infer the stack of both projects (with version), calculate the ID MG-XXX, create the folder MG-XXX-{slug}/ and build:

   • The technology mapping (Element, Source, Destination, Equivalence).
   • The existing verification strategy and the source environment (test URL for the Chrome MCP).
   • The opportunities for Golden Master Testing and the risks.

   The Equivalence column classifies each row:

   Equivalence	Meaning
   Direct	A nearly 1:1 replacement exists
   Adaptation	A replacement exists but requires changes
   Redesign	No direct replacement exists; it must be redesigned
   Remove	It is no longer necessary in the destination
   Pending	Not yet decided

2. Validation preparation (validation.md) — template assets/validation-template.md. It only starts with the discovery in Ready. For each case/opportunity follow references/golden-master-testing.md: create the cases, obtain their reference inputs/outputs (reusing artifacts from the source or capturing its output) and save the resources in the folder validation/.

3. Plan (plan.md) — template assets/plan-template.md. It is only created with the discovery and the validation in Ready. It contains the current state (source file tree), the proposed change (destination file tree), Golden Master validation tests and an implementation plan in phases with an incremental strategy of references/migration-strategies.md.

Common header of the three: fixed title, Estado, Fecha (YYYY-MM-DD), Proyecto origen/Proyecto destino; validation.md and plan.md link to the discovery with [discovery.md](./discovery.md).

States

There are two state levels distinct: that of the document and, within validation.md, that of each case.

Document (Draft / Ready) — controls the flow gates:

• discovery.md → Ready if there are no pending items in Notas and no element remains in equivalence Pending; otherwise, Draft.
• validation.md → Ready if there are no cases in Pendiente nor pending items in Notas; otherwise, Draft.
• plan.md → Draft as long as it has incomplete or pending sections in Notas; Ready when it is complete and ready to be executed.

Validation is not prepared nor planned if the discovery is not in Ready, and the plan is not created until discovery and validation are both in Ready.

Per case (within validation.md) — different from the document state:

• Pendiente: the case is missing inputs (reference inputs or outputs).
• Listo: the case has all its inputs / golden master ready.

(work-implement checks the cases in Pendiente before implementing.)

Reference map

• references/flow.md: detailed procedure of the three steps, detail of the fragmented destination, "Result" section and "Continue with the implementation" (handoff to work-implement).
• references/golden-master-testing.md: procedure for preparing Golden Master Testing cases (Step 2).
• references/migration-strategies.md: incremental migration strategies for the implementation plan (Step 3).
• assets/discovery-template.md, assets/validation-template.md, assets/plan-template.md: templates for each document with their filling instructions.