Path D · Migration · ~3-5 hours Camino D · Migración · ~3-5 horas

Migrate to a New Stack Migra a un Nuevo Stack

You're moving an existing system to a new stack, platform, or modernized architecture. Done naively, you reproduce every wart. Done well, you drop unused features, modernize, add NFRs that were missing. This path is the guided version — a three-stage flow: audit the source, refine through a structured conversation, bootstrap the target. Estás moviendo un sistema existente a un nuevo stack, plataforma, o arquitectura modernizada. Hecho ingenuamente, reproduces cada verruga. Hecho bien, descartas features no usadas, modernizas, agregas NFRs que faltaban. Este camino es la versión guiada — un flujo de tres etapas: auditar el origen, refinar a través de una conversación estructurada, arrancar el destino.

(For in-place dependency or framework-version upgrades — same repo, same architecture, just newer versions — use Path B's audit + remediation flow instead. This path is for cross-stack moves where the target is a separate codebase.) (Para upgrades in-place de dependencias o versión de framework — mismo repo, misma arquitectura, solo versiones más nuevas — usa el flujo de auditoría + remediación del Camino B. Este camino es para moves entre stacks donde el destino es una base de código separada.)

The Migration Flow El Flujo de Migración

~3-5 hours · existing project → new project ~3-5 horas · proyecto existente → proyecto nuevo
01
Open your AI assistant. You'll need both repos available — the existing source system and an empty target folder for the new system. Abre tu asistente de IA. Vas a necesitar ambos repos disponibles — el sistema origen existente y una carpeta destino vacía para el sistema nuevo.
02
Branch the source repo — before any audit. The migration audit lands in the source repo as artifacts (specs, ADRs, decisions). Even though no source code is being modified, those artifacts go on a branch so they can be reviewed before merging back. Crea rama en el repo origen — antes de cualquier auditoría. La auditoría de migración aterriza en el repo origen como artefactos (specs, ADRs, decisiones). Aunque no se modifique código fuente, esos artefactos van en una rama para poder revisarse antes de mergear de regreso.
With PragmaWorks tools Con las herramientas de PragmaWorks

The migration tool branches automatically. If you want to confirm before any change: La herramienta de migración crea la rama automáticamente. Si quieres confirmar antes de cualquier cambio:

OptionalOpcionalBefore any analysis, create a branch named migration-audit in the source repo using git CLI. Confirm the branch is active. Do not touch main in the source repo during this session.Antes de cualquier análisis, crea una rama llamada migration-audit en el repo origen usando git CLI. Confirma que la rama esté activa. No toques main en el repo origen durante esta sesión.
Pure GS (no tools) GS puro (sin herramientas)

Same as Path B step 2 — paste a branch-and-stay-off-main commitment before any analysis starts. See there for the full template. Igual que el paso 2 del Camino B — pega un compromiso de crear rama y quedarse fuera de main antes de que empiece cualquier análisis. Ver ahí la plantilla completa.

03
Start the migration. Three stages: (1) audit the source and extract a stack-independent specification; (2) refinement conversation; (3) bootstrap the target folder with the refined spec under GS discipline. Inicia la migración. Tres etapas: (1) audita el origen y extrae una especificación independiente de stack; (2) conversación de refinamiento; (3) arranca la carpeta destino con la spec refinada bajo disciplina GS.
With PragmaWorks tools Con las herramientas de PragmaWorks
Paste thisPega estoUse pragmaworks to migrate this project to a new stack. The source system is the current folder (on the migration-audit branch). The target folder is at: [absolute path to empty folder]. Find pragmaworks on npm, install what you need. Run the migration in three stages: (1) audit the source and extract a stack-independent specification; (2) walk me through a refinement conversation — what features to drop, what to modernize, what NFRs to add, what tech stack to target; (3) bootstrap the target folder with the refined specification under GS discipline. Pause between stages so I can review.Usa pragmaworks para migrar este proyecto a un nuevo stack. El sistema origen es la carpeta actual (en la rama migration-audit). La carpeta destino está en: [ruta absoluta a carpeta vacía]. Busca pragmaworks en npm, instala lo que necesites. Corre la migración en tres etapas: (1) audita el origen y extrae una especificación independiente de stack; (2) llévame por una conversación de refinamiento — qué features descartar, qué modernizar, qué NFRs agregar, a qué stack tecnológico apuntar; (3) arranca la carpeta destino con la especificación refinada bajo disciplina GS. Pausa entre etapas para que pueda revisar.
Pure GS (no tools) GS puro (sin herramientas)

Same three-stage flow, more explicit. The pure-GS version names the artifacts because no tool is producing them by default: El mismo flujo de tres etapas, más explícito. La versión GS puro nombra los artefactos porque ninguna herramienta los produce por default:

Paste thisPega estoMigrate this project to a new stack. The source system is the current folder (on the migration-audit branch). The target folder is at: [absolute path to empty folder]. Run in three stages, pausing between each so I can review: STAGE 1 — Source audit (~30 min) Read the source codebase. Produce a stack-independent specification at source/reports/migration-spec.md. Cover: behavioral contracts (what each endpoint / use case does), data model (entities, relationships), integration points (external systems, APIs, queues), use cases in UC-NNN form with pre/post-conditions, NFRs (performance, security, regulatory). Keep framework-specific notes separate in migration-spec-impl-notes.md — the primary spec should be portable. STAGE 2 — Refinement (~1 hour, conversational) Walk me through five passes: 1. Feature triage — for each feature: keep / drop / modernize. 2. Tech stack decision — bundled (language + framework + DB + deployment), not piecemeal. 3. NFR additions — logging, rate limits, encryption, audit trail, anything missing in the source. 4. Modernization opportunities — polling → WebSocket, homegrown queue → managed, etc. 5. What stays the same — API contracts, schemas, regulated business logic that cannot drift. Propose defaults; I override what I want. Write the refined spec to source/reports/migration-spec-refined.md. STAGE 3 — Bootstrap target (~1-3 hours) In the target folder, set up GS discipline from scratch (see Path A's pure-GS step 3 for the layout: docs/manifest.yaml, the doc directories, the hooks, the CI workflow). Then generate code from the refined spec under that discipline. Pause and ask before any decision that contradicts the refined spec.Migra este proyecto a un nuevo stack. El sistema origen es la carpeta actual (en la rama migration-audit). La carpeta destino está en: [ruta absoluta a carpeta vacía]. Corre en tres etapas, pausando entre cada una para que pueda revisar: ETAPA 1 — Auditoría de origen (~30 min) Lee la base de código origen. Produce una especificación independiente de stack en source/reports/migration-spec.md. Cubre: contratos de comportamiento (qué hace cada endpoint / caso de uso), modelo de datos (entidades, relaciones), puntos de integración (sistemas externos, APIs, queues), casos de uso en forma UC-NNN con pre/post-condiciones, NFRs (performance, seguridad, regulatorios). Mantén las notas específicas del framework separadas en migration-spec-impl-notes.md — la spec primaria debe ser portable. ETAPA 2 — Refinamiento (~1 hora, conversacional) Llévame por cinco pasadas: 1. Triage de features — para cada feature: mantener / descartar / modernizar. 2. Decisión de stack — integral (lenguaje + framework + DB + deployment), no por piezas. 3. Adiciones de NFR — logging, rate limits, encriptación, audit trail, lo que falte en el origen. 4. Oportunidades de modernización — polling → WebSocket, queue casero → managed, etc. 5. Qué se queda igual — contratos de API, schemas, lógica de negocio regulada que no puede derivar. Propón defaults; yo sobreescribo lo que quiera. Escribe la spec refinada a source/reports/migration-spec-refined.md. ETAPA 3 — Arranque del destino (~1-3 horas) En la carpeta destino, configura disciplina GS desde cero (ver el paso 3 GS puro del Camino A para el layout: docs/manifest.yaml, los directorios de docs, los hooks, el workflow de CI). Después genera código desde la spec refinada bajo esa disciplina. Pausa y pregunta antes de cualquier decisión que contradiga la spec refinada.
04
Stage 1 — Source audit (~30 min). The AI extracts what the source system actually does into a stack-independent spec. Behavioral contracts, data models, integration points, use cases. Framework-specific implementation notes are separate from the primary spec. Etapa 1 — Auditoría de origen (~30 min). La IA extrae lo que el sistema origen realmente hace en una spec independiente de stack. Contratos de comportamiento, modelos de datos, puntos de integración, casos de uso. Las notas de implementación específicas del framework están separadas de la spec primaria.
05
Stage 2 — Refinement conversation (~1 hour). The AI walks you through five passes: Etapa 2 — Conversación de refinamiento (~1 hora). La IA te lleva por cinco pasadas:
  • Feature triage — for each feature in the source: keep, drop, modernize? Triage de features — para cada feature en el origen: ¿mantener, descartar, modernizar?
  • Tech stack decision — bundled choice, not piecemeal Decisión de stack tecnológico — elección integral, no por piezas
  • NFR additions — logging, rate limits, encryption, audit trail Adiciones de NFR — logging, rate limits, encriptación, audit trail
  • Modernization opportunities — polling → WebSocket, homegrown queue → managed, etc. Oportunidades de modernización — polling → WebSocket, queue casero → managed, etc.
  • What stays the same — preserved API contracts, schemas, regulated logic Qué se queda igual — contratos de API preservados, schemas, lógica regulada

The AI proposes defaults for each. You override what you want. Don't re-confirm the defaults — keep moving. La IA propone defaults para cada uno. Tú sobre-escribes lo que quieras. No re-confirmes los defaults — sigue avanzando.

06
Stage 3 — Bootstrap the target (~1-3 hours). The refined spec lands in the target folder. Cascade is set up tailored to the chosen target stack (or set up by convention if pure-GS). The AI generates code under that discipline. Etapa 3 — Arranque del destino (~1-3 horas). La spec refinada aterriza en la carpeta destino. La cascade se configura ajustada al stack destino elegido (o por convención si es GS puro). La IA genera código bajo esa disciplina.
07
Verify parity. You now have the new system. Use the harness from Path A's step 6 to drive the new system through the source system's behavioral contracts. Anything that doesn't match is a refinement decision to revisit, not a bug to chase. Verifica paridad. Ahora tienes el sistema nuevo. Usa el harness del paso 6 del Camino A para manejar el sistema nuevo a través de los contratos de comportamiento del sistema origen. Cualquier cosa que no coincida es una decisión de refinamiento para revisitar, no un bug para perseguir.

If you want a literal port (preserve every wart, change only the stack), say so in step 2 and the AI will skip the refinement conversation entirely. If you want help during the refinement (regulated systems, complex business logic), the Concierge engagement handles the refinement conversation as part of the work. Si quieres un port literal (preserva cada verruga, cambia solo el stack), dilo en el paso 2 y la IA se saltará la conversación de refinamiento por completo. Si quieres ayuda durante el refinamiento (sistemas regulados, lógica de negocio compleja), el engagement de Concierge maneja la conversación de refinamiento como parte del trabajo.

What you'll have at the end Qué tendrás al final

Path D — Migration Camino D — Migración

Path D — Migration Camino D — Migración

Path A · New Project Camino A · Proyecto Nuevo
Greenfield → Greenfield →
Spec → cascade → sentinel → harness → build, from an empty folder Spec → cascada → sentinel → harness → construir, desde carpeta vacía
Path B · Existing Project Camino B · Proyecto Existente
Brownfield → Brownfield →
Audit → spec from code → sentinel → harness → remediation Auditoría → spec desde código → sentinel → harness → remediación
Diagnose Diagnóstico
Diagnose → Diagnóstico →
Score an existing codebase on all 7 GS properties Puntúa una base de código existente en las 7 propiedades GS
All Paths Todos los Caminos
Developer Cookbook → Recetario →
Every path in one place, plus the GS Audit Report Todos los caminos en un lugar, más el Reporte de Auditoría GS