encore-migrate

What this skill does

# Migrate to Encore

This skill guides migrating any existing backend application to Encore, one migration unit at a time. It supports any source language or framework and targets both Encore.ts and Encore Go. A `migration-plan.md` summary file and `migration-plan/` directory of per-unit detail files are created at the Encore project root to track progress across sessions. This skill contains no Encore code examples — it delegates all Encore-specific implementation to the appropriate language-specific skills.

## Phase Detection

Before doing anything, determine which phase to enter:

- **No `migration-plan.md` exists** in the Encore project directory → Start at **Phase 1: DISCOVER**
- **`migration-plan.md` exists but no `migration-plan/` directory** → Resume at **Phase 2: PLAN** (discovery done, detail files not yet written)
- **`migration-plan/` directory exists with pending units** (any unit in the summary with status `pending` or `in progress`) → Resume at **Phase 3: MIGRATE**
- **All units in the summary are `migrated`, `skipped`, or `manual validation needed`** → Go to **Phase 4: COMPLETE**

### Resuming a Migration (Phase 3)

When `migration-plan.md` and `migration-plan/` exist with pending units:

1. Read `migration-plan.md` (summary only — do NOT read all detail files)
2. Report current status to the user — for example: "3 of 7 units migrated, next suggested: billing (all its dependencies are migrated)"
3. Ask the user what they would like to work on next, offering a suggestion based on the dependency order in the plan

## Phase 1 — Discover

### 1. Gather Information

Ask the user for:

- **Path to the source system** (the existing codebase being migrated)
- **Local URL where the source system runs** (if applicable — needed for HTTP comparison validation later)
- **Target language:** Encore.ts or Encore Go

### 2. Analyze the Source Codebase

Read the source codebase and inventory all entities:

| Category | What to look for |
|----------|-----------------|
| Services / modules / domains | Distinct bounded contexts, separate deployable units, route groupings |
| API endpoints | Method, path, handler function, request/response shapes |
| Databases | Type (Postgres, MySQL, etc.), tables, schemas, migration files |
| Pub/Sub topics and subscriptions | Topic names, publishers, subscribers, message shapes |
| Cron jobs / scheduled tasks | Schedule expressions, handler functions |
| Auth middleware / handlers | Authentication strategies, token validation, session management |
| Secrets / environment variables | All referenced env vars and secrets, noting which are sensitive |
| Existing tests | Test files, which entities they cover, test framework used |
| Frontend code | React/Vue/Angular components, static HTML, CSS, client-side JS — these are out of scope |

### 3. Identify Frontend Code

Full-stack repos and monorepos often mix backend and frontend code. The migration targets backend only — frontend code is out of scope.

**Detect frontend directories and mark them as out of scope.** Common indicators:

| Pattern | Examples |
|---------|----------|
| Dedicated frontend directories | `frontend/`, `client/`, `web/`, `app/` (when it contains React/Vue/Angular), `src/components/`, `public/` |
| Frontend config files | `next.config.js`, `vite.config.ts`, `nuxt.config.ts`, `angular.json`, `.svelte-kit/`, `remix.config.js` |
| Package dependencies | `react`, `vue`, `@angular/core`, `svelte` in `package.json` |

**Flag framework server-side code that *should* be migrated.** Some frontend frameworks embed backend logic that contains API endpoints, database queries, or server-side business logic:

| Framework | Server-side locations | What to look for |
|-----------|----------------------|-----------------|
| Next.js | `pages/api/`, `app/*/route.ts` | API route handlers — these are backend endpoints |
| Remix | `app/routes/*.tsx` (loader/action exports) | `loader` and `action` functions contain server logic |
| Nuxt | `server/api/`, `server/routes/` | Server API routes |
| SvelteKit | `src/routes/+server.ts`, `+page.server.ts` | Server endpoints and load functions |
| Astro | `src/pages/*.ts` (non-`.astro`) | API endpoints |

When framework server-side code is found, **ask the user what to do with it.** Not all server-side code should move to Encore — sometimes a thin backend layer (BFF, auth proxy, SSR data fetching) should stay in the frontend framework alongside an Encore backend.

Present the user with what was found and ask:

> "I found <N> server-side routes in your <framework> app (e.g., `pages/api/users.ts`, `app/billing/route.ts`). These contain backend logic that *could* be migrated to Encore, but some teams prefer to keep a thin server layer in their frontend framework for things like SSR data fetching or BFF proxying. Would you like to:
> 1. **Migrate all** server-side routes to Encore
> 2. **Migrate some** — I'll list them and you pick which ones move
> 3. **Keep all in <framework>** — only migrate the standalone backend code"

Based on the user's choice:

- **Migrate all:** Extract the backend logic into migration units. Leave frontend rendering code out of scope. Note in the migration plan which source files contain mixed frontend/backend code.
- **Migrate some:** Present the list of server-side routes and let the user select. Include selected routes in migration units, mark the rest as out of scope.
- **Keep all:** Mark all framework server-side code as out of scope alongside the frontend. Only standalone backend code (Express routes, standalone API servers, etc.) enters migration units.

**Report to the user:** List all detected frontend directories and the decision made about framework server-side code. Example: "I found a Next.js frontend in `app/` — the React components are out of scope. You chose to migrate 8 of the 12 API routes from `pages/api/` to Encore and keep 4 thin proxy routes in Next.js."

### 4. Group Entities into Migration Units

Group the discovered entities into migration units using these heuristics in priority order:

1. **Existing service boundaries** — If the source app already has services, modules, or packages, use those as the starting point for chunks
2. **URL path prefixes** — Group endpoints sharing a path prefix (e.g., `/users/*`, `/billing/*`)
3. **Shared database tables** — Endpoints that read/write the same tables belong together
4. **Shared types/models** — Endpoints that share request/response types or domain models

**Chunk sizing:** Aim for 5-15 endpoints per migration unit. If a group exceeds ~15 endpoints, suggest splitting it further (e.g., `users-crud` and `users-admin`). If a group has fewer than 3 endpoints, consider merging it with a related chunk.

**Cross-cutting concerns** get their own migration units: auth, secrets, and standalone infrastructure (pub/sub topics, cron jobs not tightly coupled to one service) are separate units since they follow different dependency tiers.

**For monoliths with no clear boundaries:** Fall back to URL path prefix grouping, then ask: "These groupings are based on URL paths — would you like to reorganize them by domain?"

### 5. Present the Migration Units

Present the migration units to the user as a summary table:

| Unit | Endpoints | DB Tables | Other | Complexity |
|------|-----------|-----------|-------|------------|

Include total counts (e.g., "7 migration units covering 42 endpoints, 3 databases"). For each unit, assess overall migration complexity:

- **Low** — direct Encore equivalents exist, straightforward mapping
- **Medium** — requires restructuring or has partial Encore equivalents
- **High** — no direct equivalent, needs redesign or custom solution

Offer to show the detail of any unit if the user wants to inspect what's inside before confirming.

### 6. Show Code Previews

For 2-3 representative entities (pick a mix of simple and complex from different units), show a short "before and after" preview of what the source code looks like now