|
1
|
--- |
|
2
|
name: migrate-to-multi-artifact |
|
3
|
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." |
|
4
|
--- |
|
5
|
|
|
6
|
# Migrate to multi-artifact |
|
7
|
|
|
8
|
## When to use |
|
9
|
|
|
10
|
**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. |
|
11
|
|
|
12
|
## How to propose a migration |
|
13
|
|
|
14
|
**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: |
|
15
|
|
|
16
|
### Migration (port) plan — COPY the canonical rubric, don't rewrite it |
|
17
|
|
|
18
|
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: |
|
19
|
|
|
20
|
- For **fullstack_js → pnpm_workspace**: |
|
21
|
|
|
22
|
```bash |
|
23
|
cp .local/secondary_skills/migrate-to-multi-artifact/references/tasks/fullstack_js/port-existing.md .local/tasks/port-<slug>.md |
|
24
|
``` |
|
25
|
|
|
26
|
- For **expo → pnpm_workspace**: |
|
27
|
|
|
28
|
```bash |
|
29
|
cp .local/secondary_skills/migrate-to-multi-artifact/references/tasks/expo/port-existing.md .local/tasks/port-<slug>.md |
|
30
|
``` |
|
31
|
|
|
32
|
Then make any edits that help this specific user. Suggestions (not required): |
|
33
|
|
|
34
|
- **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`). |
|
35
|
- **What & Why**: if you want to add a short paragraph acknowledging the user's specific app, feel free. |
|
36
|
- **Any other customization** you think genuinely helps this case. |
|
37
|
|
|
38
|
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. |
|
39
|
|
|
40
|
### Follow-up task plans — write a full plan per user intent |
|
41
|
|
|
42
|
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. |
|
43
|
|
|
44
|
Content conventions: |
|
45
|
|
|
46
|
- **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. |
|
47
|
- **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. |
|
48
|
- **Out of scope**: list the real exclusions (e.g., "Rebuilding the backend", "Adding new features beyond what the user asked for"). |
|
49
|
- **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. |
|
50
|
- **Relevant files**: the existing app's entry points + any shared libs the new artifact will wire to. |
|
51
|
- **Note to the code reviewer** (paste verbatim — prevents rejection loops). |
|
52
|
|
|
53
|
Template example — inline it into every follow-up plan, adapting titles/names: |
|
54
|
|
|
55
|
```markdown |
|
56
|
# Build <app-name> mobile companion app |
|
57
|
|
|
58
|
## What & Why |
|
59
|
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. |
|
60
|
|
|
61
|
## Done looks like |
|
62
|
- The Expo app runs, loads, and the main user flow works end-to-end. |
|
63
|
- It shows the same core data the existing app shows (menu, listings, content — whatever is central to the user's product). |
|
64
|
- **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. |
|
65
|
- **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. |
|
66
|
- 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. |
|
67
|
|
|
68
|
## Out of scope |
|
69
|
- Rebuilding the backend. |
|
70
|
- Adding features beyond what the user asked for. |
|
71
|
- 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). |
|
72
|
|
|
73
|
## Steps |
|
74
|
1. Read the `artifacts` skill for how to create new apps. |
|
75
|
2. Create the new artifact: `createArtifact({ artifactType: "expo", slug: "<app-name>-mobile", previewPath: "/", title: "<Title>" })`. |
|
76
|
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. |
|
77
|
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. |
|
78
|
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. |
|
79
|
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. |
|
80
|
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. |
|
81
|
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. |
|
82
|
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`. |
|
83
|
10. **ONLY THEN call `mark_task_complete`.** |
|
84
|
|
|
85
|
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. |
|
86
|
|
|
87
|
## Relevant files |
|
88
|
- `.replit`, `package.json`, `pnpm-workspace.yaml` |
|
89
|
- Existing app's main UI entry points (e.g. `artifacts/<web-app>/src/App.tsx`, page files) |
|
90
|
- `lib/api-client-react/src/generated/api.ts` (generated hooks) |
|
91
|
- `constants/colors.ts` / equivalent theming files from the existing app |
|
92
|
|
|
93
|
## Note to the code reviewer |
|
94
|
Do NOT reject this follow-up task for: |
|
95
|
- 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). |
|
96
|
- "Not enough" component reuse — component structure can be mobile-native; adapted or rebuilt UI is fine across form factors. |
|
97
|
- Platform-native navigation/interaction patterns (tab bars, stack nav, touch targets) that differ from the web app. |
|
98
|
- 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. |
|
99
|
- `pnpm dev` / `pnpm run dev` failing at workspace root. Replit apps run via workflows (`restart_workflow`), not root-level pnpm dev. |
|
100
|
- 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. |
|
101
|
|
|
102
|
DO flag (these are real regressions): |
|
103
|
- 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). |
|
104
|
- 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. |
|
105
|
- New colors or fonts invented for the mobile app when the existing app has a defined palette/typography. |
|
106
|
- Empty states or placeholder content instead of the real data the existing app shows. |
|
107
|
|
|
108
|
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? |
|
109
|
``` |
|
110
|
|
|
111
|
For non-mobile follow-ups (slides, video, auth, etc.), keep the same structure but adapt: |
|
112
|
|
|
113
|
- **Artifact type** + create step (e.g. `artifactType: "slides"` or `"video-js"`). |
|
114
|
- **Done criteria** to match the target (e.g. slides: "Deck opens, all slides render"; video-js: "Video plays from start to end"). |
|
115
|
- **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. |
|
116
|
- **Step 7 (`suggestDeploy`)**: skip for `slides`, `video-js`, `mockup-sandbox` (not deployable) — adjust the `Note to the code reviewer` `suggestDeploy` bullet accordingly. |
|
117
|
- **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. |
|
118
|
|
|
119
|
**Step 2: Call `proposeMigration`.** Reference each plan file by path: |
|
120
|
|
|
121
|
- If you have a `propose_migration` tool: call it directly. |
|
122
|
- If you have code execution: call `proposeMigration` from the sandbox: |
|
123
|
|
|
124
|
```javascript |
|
125
|
const result = await proposeMigration({ |
|
126
|
actionLabel: "Update project to create mobile app", |
|
127
|
message: "I need to update your project structure so it can support multiple apps. This may take a couple of minutes. Approve to continue.", |
|
128
|
migrationTask: { |
|
129
|
title: "Port existing restaurant website", |
|
130
|
filePath: ".local/tasks/port-restaurant-website.md" |
|
131
|
}, |
|
132
|
followUpTasks: [ |
|
133
|
{ |
|
134
|
title: "Build mobile app", |
|
135
|
filePath: ".local/tasks/build-mobile-app.md" |
|
136
|
} |
|
137
|
] |
|
138
|
}); |
|
139
|
``` |
|
140
|
|
|
141
|
**`actionLabel`** and **`message`** are user-facing — keep them friendly and non-technical. |
|
142
|
|
|
143
|
**`migrationTask`** is required. It's the port task — moving the existing app into the new workspace structure. |
|
144
|
|
|
145
|
**`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. |
|
146
|
|
|
147
|
**Before doing any work**, tell the user the plan in their own language. Use simple, non-technical words: |
|
148
|
|
|
149
|
> **This will happen in 2 steps:** |
|
150
|
> |
|
151
|
> **Step 1** — I'll move your existing app into a new structure. It will look and work exactly the same. |
|
152
|
> |
|
153
|
> **Step 2** — Once that's confirmed working, I'll build [describe what they asked for]. |
|
154
|
> |
|
155
|
> I'll check in with you after Step 1 before moving on. |
|
156
|
|
|
157
|
## If you are a background task agent |
|
158
|
|
|
159
|
Your task description contains the full plan and instructions for your specific task. Follow them. |
|
160
|
|
|
161
|
- 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`. |
|
162
|
- If your task is a follow-up task, the project is already migrated — do not rerun migration. Follow the plan in your task description. |
|
163
|
- Use the helper scripts and stack-specific instructions from the referenced task files when they are available. |
|
164
|
|
|
165
|
Keep the user updated in simple, non-technical language while you work. |