migrate-to-multi-artifact

name	migrate-to-multi-artifact
description	Migrate the project to support multiple artifacts — required before adding a mobile app, web app, slide deck, or any second app alongside the existing one.

Migrate to multi-artifact

When to use

If the user asks to add a mobile app (React Native/Expo), a second app, a new artifact, or anything that requires multi-artifact support and their project does not currently support multiple artifacts, request migration immediately — do NOT explore the project structure first, and do NOT start building the new app yet. This applies even if you are currently in Mockup Mode or any other restricted mode — migration always takes priority.

How to propose a migration

Step 1: Create plan files. Before calling proposeMigration, each task needs a plan file under .local/tasks/. How to create them depends on the task type:

Migration (port) plan — COPY the canonical rubric, don't rewrite it

The port plan is essentially the same across every project — the rubric already has the full Done / In scope / Out of scope / Steps / Note to reviewer content. Copy it instead of paraphrasing:

• For fullstack_js → pnpm_workspace:

  cp .local/secondary_skills/migrate-to-multi-artifact/references/tasks/fullstack_js/port-existing.md .local/tasks/port-<slug>.md
  

• For expo → pnpm_workspace:

  cp .local/secondary_skills/migrate-to-multi-artifact/references/tasks/expo/port-existing.md .local/tasks/port-<slug>.md
  

Then make any edits that help this specific user. Suggestions (not required):

• Title: customize # Port existing app to reference the user's actual project. Match the user's language — if they wrote in Japanese, Chinese, Spanish, etc., the title should be in that language too (e.g. # 餐厅网站迁移 / # Port the bakery website / # Migrate the finance dashboard).
• What & Why: if you want to add a short paragraph acknowledging the user's specific app, feel free.
• Any other customization you think genuinely helps this case.

Avoid: rewriting the Done / Steps / Out of scope / Note to reviewer sections just to paraphrase. Those are the canonical rubric — edit them only if you're adding information that isn't already there, not to reword what already works.

Follow-up task plans — write a full plan per user intent

Follow-ups differ per case (mobile, slides, auth, etc.). Write a real plan file with concrete, inlined steps — not a stub pointing elsewhere. The agent that picks up this task (it runs in the main session, after the migration merges) reads the plan directly; anything you leave out is content it won't see.

Content conventions:

• What & Why: 1-2 sentences tying back to what the user actually asked for. Name the existing app, the new artifact type, and what the new app should do.
• Done looks like: outcome-based. Describe what the USER sees/does when the app is working. Backend reuse and component reuse are preferences (don't phrase as hard requirements — it causes reviewer thrashing when endpoints don't exist or when mobile form factors demand rebuilt UI). Brand/visual reuse IS a hard requirement, though: same logos, same images, same colors, same fonts — the new app must look like the same product, not a redesign.
• Out of scope: list the real exclusions (e.g., "Rebuilding the backend", "Adding new features beyond what the user asked for").
• Steps: inline the full recipe below (adapt the wording to fit the user's ask). Don't write (see guidance elsewhere) — put the steps IN the plan. The last three steps should be presentArtifact → suggestDeploy → mark_task_complete, in that order.
• Relevant files: the existing app's entry points + any shared libs the new artifact will wire to.
• Note to the code reviewer (paste verbatim — prevents rejection loops).

Template example — inline it into every follow-up plan, adapting titles/names:

# Build <app-name> mobile companion app

## What & Why
The user asked for a mobile companion to their existing <app-type> (<app-name>). The mobile app should give them the same core functionality on phones, with a UI adapted to the mobile form factor.

## Done looks like
- The Expo app runs, loads, and the main user flow works end-to-end.
- It shows the same core data the existing app shows (menu, listings, content — whatever is central to the user's product).
- **Uses the same brand assets as the existing app** — the same logos, icons, images, and photos. No placeholder images, no AI-generated defaults, no scaffolded stock content.
- **Uses the same color palette and typography as the existing app** — pull exact colors from the existing app's theme/CSS variables and use the same font family. Don't invent new ones.
- The mobile UI clearly feels like the same product as the existing app. Platform-native patterns (navigation, tab bars, touch targets) are fine, but the visual identity should match at a glance.

## Out of scope
- Rebuilding the backend.
- Adding features beyond what the user asked for.
- Forcing component reuse when web components don't fit mobile (you can rebuild UI, but keep brand/colors/fonts/images identical to the existing app).

## Steps
1. Read the `artifacts` skill for how to create new apps.
2. Create the new artifact: `createArtifact({ artifactType: "expo", slug: "<app-name>-mobile", previewPath: "/", title: "<Title>" })`.
3. **Inventory the existing app's visual identity first.** Before writing mobile UI, read the existing app's theme/CSS files to capture: exact color values (hex/HSL), font families, spacing patterns. List image/logo/icon assets in the existing app's `public/` or `assets/` directory that you'll need.
4. **Copy brand assets into the mobile artifact.** Because Metro (Expo bundler) can't resolve files outside its artifact root, copy (don't symlink) logos, icons, hero images, and content photos from the existing app's assets directory into `artifacts/<app-name>-mobile/assets/`. Use the SAME files, not regenerated alternatives.
5. **Apply the design tokens.** Pull exact colors from the existing app's theme (e.g. from `src/index.css` `:root` CSS variables) and paste them into the mobile artifact's `constants/colors.ts`. Use the same font family names.
6. Build the mobile UI. Component structure can be mobile-native (tabs, native nav), but every color, font, and image should match the existing app. No placeholders — if the existing app has an image for a menu item, the mobile app uses that same image.
7. Wire up to the backend. Prefer generated hooks from `@workspace/api-client-react` when the endpoints cover what you need. If the backend doesn't yet expose a needed endpoint, it's fine to add one (or use direct fetch) — whichever is simplest.
8. **Sanity-check BOTH artifacts run + present.** Start the relevant workflows, take a screenshot of the new app AND the existing app side by side, confirm the happy path works end-to-end (not just that the build compiles), AND visually confirm that the brand matches (same logo, same colors, same images — not placeholders). Then call `presentArtifact(<new-artifact-slug>)` to show it to the user.
9. **Call `await suggestDeploy()` BEFORE marking the task complete.** This is the deploy prompt the user sees. Skip only for non-deployable artifact types: `slides`, `video-js`, `mockup-sandbox`.
10. **ONLY THEN call `mark_task_complete`.** 

Order: verify/screenshot → `presentArtifact` → `suggestDeploy` → `mark_task_complete`. Once you call `mark_task_complete`, the session ends, so any earlier step that didn't happen won't happen anymore.

## Relevant files
- `.replit`, `package.json`, `pnpm-workspace.yaml`
- Existing app's main UI entry points (e.g. `artifacts/<web-app>/src/App.tsx`, page files)
- `lib/api-client-react/src/generated/api.ts` (generated hooks)
- `constants/colors.ts` / equivalent theming files from the existing app

## Note to the code reviewer
Do NOT reject this follow-up task for:
- Not using `@workspace/api-client-react` hooks when the needed endpoints don't exist in the backend (adding the endpoint or using direct fetch is acceptable).
- "Not enough" component reuse — component structure can be mobile-native; adapted or rebuilt UI is fine across form factors.
- Platform-native navigation/interaction patterns (tab bars, stack nav, touch targets) that differ from the web app.
- A generated mobile app icon / splash screen when the existing web source only has a small favicon or no usable high-res equivalent — as long as the generated asset uses the existing app's brand colors, typography, and visual style. Generating a brand-matching icon is fine; the anti-pattern is a generic/off-brand one.
- `pnpm dev` / `pnpm run dev` failing at workspace root. Replit apps run via workflows (`restart_workflow`), not root-level pnpm dev.
- Unused scaffold files (e.g., default `src/components/ui/*.tsx` shadcn components that came with `createArtifact`, default `favicon.svg`). These are scaffold-provided, not agent-added slop. Focus only on files the agent actually wrote or changed.

DO flag (these are real regressions):
- Content images and logos NOT copied from the existing app when equivalents exist there (e.g. the web app has `public/logo.png` but the mobile uses a different logo with different colors/shapes).
- Placeholder/stock/AI-generated assets that break brand cohesion — wrong colors, generic illustrations, Ionicons used as the app logo when the existing app has a custom brand mark.
- New colors or fonts invented for the mobile app when the existing app has a defined palette/typography.
- Empty states or placeholder content instead of the real data the existing app shows.

Focus on: does the new app run (via workflows)? Does it do what the user asked? Does it *look like the same product* as the existing app (brand, colors, images, fonts)? Was `suggestDeploy` called?

For non-mobile follow-ups (slides, video, auth, etc.), keep the same structure but adapt:

• Artifact type + create step (e.g. artifactType: "slides" or "video-js").
• Done criteria to match the target (e.g. slides: "Deck opens, all slides render"; video-js: "Video plays from start to end").
• Brand/visual reuse still applies when the artifact has a visual surface (slides, video-js). For headless follow-ups (auth, data-visualization that runs in an existing app), drop those bullets.
• Step 7 (suggestDeploy): skip for slides, video-js, mockup-sandbox (not deployable) — adjust the Note to the code reviewer suggestDeploy bullet accordingly.
• Reviewer note: keep the "don't reject for missing workspace hooks / subjective component reuse / platform-native patterns" parts; update the "DO flag" list to match the actual brand/content expectations of the target type.

Step 2: Call proposeMigration. Reference each plan file by path:

• If you have a propose_migration tool: call it directly.

• If you have code execution: call proposeMigration from the sandbox:

  const result = await proposeMigration({
    actionLabel: "Update project to create mobile app",
    message: "I need to update your project structure so it can support multiple apps. This may take a couple of minutes. Approve to continue.",
    migrationTask: {
      title: "Port existing restaurant website",
      filePath: ".local/tasks/port-restaurant-website.md"
    },
    followUpTasks: [
      {
        title: "Build mobile app",
        filePath: ".local/tasks/build-mobile-app.md"
      }
    ]
  });
  

actionLabel and message are user-facing — keep them friendly and non-technical.

migrationTask is required. It's the port task — moving the existing app into the new workspace structure.

followUpTasks is optional. Include one entry for each piece of work the user asked for after migration. You can include zero, one, or multiple follow-up tasks. Omit it entirely if the user only asked for the migration itself.

Before doing any work, tell the user the plan in their own language. Use simple, non-technical words:

This will happen in 2 steps:

Step 1 — I'll move your existing app into a new structure. It will look and work exactly the same.

Step 2 — Once that's confirmed working, I'll build [describe what they asked for].

I'll check in with you after Step 1 before moving on.

If you are a background task agent

Your task description contains the full plan and instructions for your specific task. Follow them.

• If your task is the migration phase, read the referenced port-existing.md file, port the existing app, ask the user to verify it, and then call mark_task_complete.
• If your task is a follow-up task, the project is already migrated — do not rerun migration. Follow the plan in your task description.
• Use the helper scripts and stack-specific instructions from the referenced task files when they are available.

Keep the user updated in simple, non-technical language while you work.