existing-project-migration

What this skill does

# Existing Project Migration

## Core Idea

Re-read this `SKILL.md` after every compaction before continuing work. Do not assume conversational memory is sufficient.

This skill is for tech stack migration, not product redesign.

- The customer already has an app.
- The job is to reorganize that app into the Customware stack.
- The source product's routes, workflows, labels, layout shell, page sections, section ordering, visual language, and styling should survive as a source-faithful port. The default expectation is no intentional user-facing UI or UX change.
- The runtime stack must change to the prepared Customware stack built from `template-be-setup` plus the required `client-only-spa` merge rule.

Do not treat this task like a fresh app build, a domain reinterpretation, or a chance to simplify the product into a smaller generic dashboard.
Do not encode expectations from any previous migration. This skill must work for whatever app the customer uploaded. Derive the preservation target fresh from the current imported source each time.
A customer familiar with the source app should feel they are using the same app on a new stack, not a remake.
If literal parity is blocked by a real stack constraint, a missing source artifact, or a source bug, keep the difference minimal and record it explicitly as a named deviation.

## Source Authority

The uploaded artifacts drive the migration.

Priority:

1. `.import/project/` from `projects.zip` is the primary authority for product behavior, routes, UI, workflows, integrations, and business logic.
2. `.import/database/` from `database.zip` is the primary authority for persisted entities, schema inference, and seed data when CSV rows exist.
3. `.import/domain/` and `.import/domain-source.txt` from `domain.zip` are supporting context only.
4. `.tasks/domain.md` plus org name, org description, logos, colors, and brand context are low-authority presentation context only.

Do not let org/company knowledge or `.tasks/domain.md` redefine the imported product's domain, routes, workflows, schema, or product framing. This migration intentionally does not rely on the domain skill as product authority.
While `.tasks/domain.md` may exist, treat it as effectively ignorable for product-definition decisions during migration. The real source of truth is the imported codebase in `.import/project/` plus the imported database files in `.import/database/`. Use domain material only if it helps clarify minor presentation context and never let it outrank source code or source data.

## Fixed Target Stack

Migrate into the prepared Customware full-stack target:

- Vite
- React Router
- TypeScript
- Zod
- Node
- Hono
- tRPC
- SQLite via `better-sqlite3`
- Drizzle ORM and migrations

Do not preserve the uploaded source app's original runtime stack.

## Required Phase References

Read the exact files for the active task before doing work.

- `Migration build`
  - `.agents/skills/existing-project-migration/references/phase-1/overview.md`
  - `.agents/skills/existing-project-migration/references/phase-1/artifacts.md`
  - `.agents/skills/existing-project-migration/references/phase-1/grading.md`
- `Migration verify`
  - `.agents/skills/existing-project-migration/references/phase-2/overview.md`
  - `.agents/skills/existing-project-migration/references/phase-2/artifacts.md`
  - `.agents/skills/existing-project-migration/references/phase-2/grading.md`

If the task text is unclear, read both phase overview files first, determine which phase is active, then load the matching artifact and grading references.

## Critical Migration Invariant

These are hard rules.

- This is a stack migration. Preserve the source product; replace the runtime foundation.
- Preserve the imported app's visible route map, route paths, navigation labels, page hierarchy, headings, page sections, section ordering, section styling, control surfaces, workflows, typography, theme tokens, and logo usage. Default assumption: zero intentional user-facing change.
- Preserve the imported app's actual screen archetypes and concrete page contracts from source. If the source page is a calendar, keep it calendar-first. If it is a dense table workspace, keep that structure. If it is a real config form, keep the same form-driven surface. Do not swap one screen archetype for another just because it covers a similar business area.
- Treat the imported frontend as the visual and information-architecture authority, and treat the source route/page files as translation targets. Read the active router/bootstrap, layout/navigation files, theme/root CSS files, key assets, and representative page files before deciding UI direction.
- Port the source page structure and styling tokens directly. Do not paraphrase the source UI into new summaries, helper text, explanatory panels, or generic product copy.
- Before any interactive verification pass, run a pre-interactive fidelity review directly against the source frontend code, migrated code, and any available source screenshots. Confirm the shared shell plus every source-visible screen still contains the expected layout blocks, named sections, section order, headings, labels, controls, actions, tables, charts, forms, tabs, and style direction before opening the browser.
- For each source-visible screen, extract the exact screen contract before implementation or grading. That contract must include exact button labels, tab labels, filter labels, section titles, table columns, key actions, named sections, and section order taken from the source app.
- Treat code-visible omissions as failures before interactive QA. If the source code clearly shows a sidebar, navigation section, header, tab strip, table header, filter row, form block, chart block, action cluster, or other visible section and the migrated code does not preserve it, the phase is still open even if the page can technically render.
- If any extracted exact contract item is missing, renamed, reordered, restyled beyond recognition, or replaced with a different surface without an explicit blocker, that grading pass fails. Use those failed exact items as the mandatory next-fix queue and keep iterating until the screen passes.
- When a user-noticeable UI difference is truly unavoidable, keep it minimal and log it explicitly in `migration-plan.json`, `migration-review.md`, and `migration-open-gaps.md`. Unrecorded drift is a fail.
- Do not invent migration-themed copy such as `Imported App Migration`, `Migration slice`, or any similar framing.
- No user-facing copy may mention imported, migrated, source, preserved, phase, CSV, seed, staging, readiness, review, or any equivalent provenance narrative unless the source app itself used that language.
- Do not collapse the imported app into a narrow vertical slice just because the CSV exports cover only part of the data model.
- Do not replace source-visible pages with generic hero cards, placeholder dashboards, filler prose, summary cards, readiness panels, or generic review/status shells.
- Interactive verification is always from the end-user perspective. Start from the first user-visible page on the actual review or preview host when that host exists, usually `/` while unauthenticated.
- Interactive verification must prove visible parity, not just DOM existence. A route counts as covered only when the expected shell, layout blocks, and key controls are visibly rendered on screen and at least one basic page-native action works. Hidden text, detached UI, or merely attached DOM nodes do not count as success.
- Phase 1 verification is exhaustive interactive QA, not broad automated suite authoring. Visit every available migrated page route from the user perspective, exercise at least one basic page-native action on each route, and cover common flows such as login, sign-out, navigation, search, filter, tabs, forms, detail views, and integration or configuration actions where those surfaces exist.
- Automated unit tests and end-to-end suites belong prima