fimo 0.15.0 → 0.16.0-experimental.2

package/assets/skills/fimo-migration/references/workflow.md

@@ -1,194 +1,154 @@
 # Migration Workflow
 
-Use this as the phase contract for complete migrations.
-
-## Phase 0: Target Safety
-
-1. Confirm the target path.
-2. If the target path is missing, create exactly one Fimo project there.
-3. If it has `.fimo/project.json` or the legacy `.fimo.settings.json`, reuse it.
-4. If it is non-empty and not a Fimo project, stop and ask for a target path.
-5. Never overwrite user work outside generated migration folders without reading
-   the existing files first.
-
-## Phase 1: Source Intake
-
-Classify all available evidence:
-
-- published URLs and sitemap URLs
-- downloaded HTML, source repo, builder export, or static export
-- CMS CSV/XML/JSON exports
-- media folders and remote media URLs
-- forms and third-party form actions
-- redirects, locales, SEO metadata, robots/sitemap data
-- unsupported app behavior such as auth, commerce, search, members, custom JS
-
-For source-backed migrations, inspect the source/export directly with shell
-tools such as `rg`, `find`, `ls`, and targeted file reads. Treat CMS exports and
-media folders as source-of-truth evidence, then copy normalized facts into the
-canonical ledger.
-
-For URL-only migrations, run `fimo migrate <url> [dir]` and inspect
-`.fimo/migrations/current/`.
-
-Read these URL migration artifacts first when they exist:
-
-- `.fimo/migrations/current/brief.md`
-- `.fimo/migrations/current/manifest.json`
-- `.fimo/migrations/current/extracted/pages.json`
-- `.fimo/migrations/current/extracted/forms.json`
-- `.fimo/migrations/current/extracted/design-tokens.json`
-- `.fimo/migrations/current/refine/agent-prompt.md`
-- `.fimo/migrations/current/refine/pages/*.md`
-
-When default crawling misses client-rendered or lazy-loaded content, use the
-agent or harness browser tools to collect additional HTML, screenshots, and route
-notes, then merge that evidence into the migration artifacts. Import reviewed
-media, schemas, forms, and entries through the regular Fimo CLI commands.
-
-## Phase 2: Canonical Ledger
-
-Create `.fimo/migration/manifest.json` using `references/manifest.md`.
-
-If an older ledger exists under `.fimo/migrations/current/` or
-`.fimo/source-migration/`, keep it as evidence and copy normalized facts into the
-canonical ledger instead of editing unrelated history.
-
-Use the bundled script when possible:
-
-```bash
-node <this-skill>/scripts/build-canonical-manifest.mjs <project-root>
-```
-
-Pass `--fresh` only when intentionally discarding previous canonical manifest
-progress such as verified statuses, uploaded asset IDs, or notes.
-
-Every item needs one of these statuses:
-
-- `discovered`
-- `planned`
-- `generated`
-- `imported`
-- `verified`
-- `ignored`
-- `unsupported`
-- `unresolved`
-
-## Phase 3: Content Model First
-
-Before writing page code:
-
-1. Detect dynamic collections from both repeated route groups AND repeated
-   in-page blocks. A hardcoded array of 3+ structurally-identical items (cards,
-   list rows, tiles) is a collection, not static markup. Ignore locale prefixes
-   when naming collections.
-2. Map each CMS export or inferred collection to a Fimo schema or unresolved item.
-3. Preserve stable source IDs, slugs, dates, SEO, authors, categories, tags,
-   locales, and publish status.
-4. Decide which references are real. Do not invent references from vague text.
-5. Build seed/import entries with source IDs and media references preserved.
-6. Record source count and planned import count for each content type.
-
-Use `references/content.md`, including "Detecting Dynamic Collections".
-
-## Phase 4: Media And Forms
-
-Before final page wiring:
-
-1. Build a media map from local files and remote URLs.
-2. Upload or plan uploads for media referenced by pages, CMS entries, SEO, and
-   forms.
-3. Replace source media references only after upload mapping is known.
-4. Classify forms as Fimo-native, third-party integration, or unsupported.
-5. Generate `src/forms/*.json` for accepted Fimo-native forms.
-
-Use `references/media.md` and `references/forms.md`.
-
-## Phase 5: Import Payloads
-
-Before calling the migration complete, prepare the actual import path described
-in `references/import-contract.md`.
-
-Required order:
-
-1. media files
-2. schemas
-3. CMS entries with media references resolved
-4. forms
-
-Record target IDs, import counts, failures, and unresolved items in the
-canonical ledger. Generated JSON without import counts is still draft state.
-
-## Phase 6: Fimo Implementation
-
-Implement routes, schemas, forms, entries, media, redirects, translations, and
-React pages with Fimo conventions.
-
-Rules:
-
-- If no target exists, create one Fimo project. Do not create a nested Fimo app
-  inside a source repository unless the user explicitly chose that directory.
-- If a target Fimo project exists, inspect existing routes, schemas, forms, and
-  components before writing.
-- Store migration analysis artifacts under `.fimo/migration/`.
-- Use source CSS/design files as visual evidence, not as a permanent global CSS
-  dump.
-- Schema-driven media renders with Fimo media primitives, not raw source URLs.
-- CMS pages must have matching `src/schemas/*.json` before generated clients or
-  queries are used.
-- Repeated dynamic items (games, locations, posts, testimonials, pricing) render
-  from CMS collections, not hardcoded arrays. A page left with a hardcoded array
-  of collection-shaped items is an incomplete migration, not a finished one.
-- Generated `.ts` schema/form clients are not edited manually.
-- Unsupported source behavior is replaced with a Fimo-native equivalent or shown
-  as unresolved, never hidden behind broken UI.
-
-## Phase 7: Import
-
-Import only reviewed artifacts:
-
-- media assets and media map updates
-- schemas
-- forms
-- entries
-- redirects/locales when supported by the current project tooling
-
-After import, update the ledger with created IDs, uploaded asset IDs, failures,
-and counts.
-
-## Phase 8: QA Gate And Report
-
-Run `references/qa.md`. Write `.fimo/migration/migration-report.md` with:
-
-- source summary
-- route coverage
-- CMS source/import counts
-- media source/upload/reference counts
-- form coverage
-- build/runtime checks
-- visual checks
-- unresolved/unsupported items
-- exact next actions
-
-Use the bundled report script to make the QA state explicit:
-
-```bash
-node <this-skill>/scripts/write-migration-report.mjs <project-root>
-```
-
-The script exits non-zero when required coverage checks fail. That is a prompt
-to continue the migration or document the gaps, not a reason to hide the report.
-
-All checks in this phase are **local** (build, local dev, route render, visual
-comparison). Do not run `fimo deploy` / `fimo publish` to verify anything.
-
-## Phase 9: Propose Deployment
-
-Deployment is not part of the migration loop and is never run to preview or
-verify. Once Phase 8 passes:
-
-1. Do not run `fimo deploy` or `fimo publish` yourself.
-2. End by proposing it: tell the owner the migration is ready, that one
-   `fimo deploy` creates its hosted preview, and that going live requires a
-   separate explicit publish.
-3. Deploy only if the owner explicitly asks in this turn, and then only once.
+Use this as the phase contract for a complete migration. The coordinator and
+workers communicate in plain text. JSON is used only for Fimo schemas and the
+content payloads that the data-plane commands import.
+
+## Phase 0: Initialize the target
+
+1. Confirm the target path. The target is a separate directory; the source
+   checkout remains read-only evidence.
+2. Initialize or reuse exactly one linked Fimo target before workers start:
+   - URL migration: `fimo migrate init <source-url> <target-dir> --framework <framework>`
+   - link an existing project: `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
+   - create a project: `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+     Use the detected source framework for source-backed migrations. A framework
+     conversion requires an explicit user choice; URL-only and rebuild
+     migrations ask the user which framework to use. Never choose a framework by
+     copying an arbitrary `--template-root`, invent a project ID, or hand-write
+     `.fimo/project.json`.
+3. Inspect the target's real `package.json`, `.fimo/config.json`, framework config, and route
+   directories. They are the authority for paths. Do not infer an app root
+   from a skill example and do not create a second `app/` or `src/app/` tree.
+4. If the target is non-empty and not a Fimo project, stop and ask for a target
+   path; do not overlay a template on top of it.
+5. Keep source material in `.fimo/migration/source` or another explicit source
+   location. Do not copy source files over the initialized target root.
+
+Write a short `.fimo/migration/migration-plan.md` containing the source
+location, selected framework, actual target directories, worker owners, and
+known questions. Do not create `target.json`, a target manifest,
+`worker-plan.json`, `decision.json`, or JSON worker receipts for a new run. A
+URL-only Source Evidence Pack is the one exception: its versioned `index.json`
+describes observed source evidence and raw-artifact pointers, never target work
+or completion.
+
+## Phase 1: Source intake
+
+Read the source directly with `rg`, `find`, `ls`, and targeted file reads.
+Classify the available evidence:
+
+- source repository, export, downloaded HTML, or media folder;
+- CMS CSV/XML/JSON exports and public APIs;
+- forms and third-party form actions;
+- integrations and the environment-key names they need, never secret values;
+- redirects, security headers, locales, SEO, robots, sitemap, and OG behavior;
+- unsupported behavior such as auth, commerce, search, members, custom JS, or
+  provider-specific workers.
+
+For private APIs or CMSs, ask for a user-provided export or a narrowly scoped
+server-side credential. Never recover credentials from browser bundles or copy
+them into migration artifacts. Missing access blocks only that lane and becomes
+an unresolved item; never invent replacement content.
+
+For URL-only migrations, inspect the `.fimo/migrations/current/` files written
+by the URL form of `fimo migrate init` as a static seed. Do not run the legacy
+apply/refine path before observation. Then load `references/url-evidence.md`
+and run the observation crew from
+`references/workers/url-observer.md`. The crew must render, scroll, interact,
+sample motion from before navigation, normalize the observations, and write
+`.fimo/migration/source-evidence/index.json` before reconstruction begins. Do
+not copy the crawl manifest into the pack or treat fetched HTML as rendered
+truth.
+
+## Phase 2: Fan out workers
+
+For URL-only sources, the coordinator first launches the route scout,
+shared-system observer, page observers, and evidence normalizer. Reconstruction
+waits for their completeness gate. It then launches only the workers supported
+by the normalized source evidence:
+
+- **runtime**: preserve the detected framework, router, runtime, dependencies,
+  provider configuration, and environment wiring. A framework conversion needs
+  an explicit user choice.
+- **routes/SEO**: preserve one target route per source route, redirects, 404,
+  metadata, OG/social output, sitemap, robots, and other observable behavior.
+- **content planner**: discover content, labels, data sources, consumers, and
+  schemas; push schemas and prepare content payloads. It does not rewrite page
+  code or import every entry itself.
+- **locales**: configure locales and migrate translated UI-visible copy when
+  the source has it.
+- **assets/forms**: after content planning, upload every referenced media item
+  and preserve, replace, or report forms and integrations.
+
+When the user explicitly chose a framework conversion, one framework
+conversion worker replaces the runtime and routes lanes and owns all
+structural target code (see `references/workers/framework.md`). The content
+planner may read the source in parallel, but it must not convert the framework
+or rewrite page code. Follow the asset, data, and code gates in
+`references/workers.md`.
+
+The coordinator gives each worker a plain-language prompt naming its ownership,
+files, dependencies, and worker-specific reference from `references/workers/`.
+Workers may write the application inside their ownership. They do not need a
+JSON plan or receipt. If two workers need the same file, name one owner and run
+the other after it.
+
+## Phase 3: Content planning
+
+The planner follows `references/workers/content-planner.md`, plus
+`references/content.md`, `references/decision.md`, and
+`references/import-contract.md`. Its text plan and payloads must be complete
+before Phase 4; data workers must not rediscover unrelated source files.
+
+## Phase 4: Media, forms, and integrations
+
+1. Account for every planner media obligation, including schema media fields
+   and richtext/Tiptap image nodes, plus route, SEO, and form media.
+2. Upload media through Fimo and replace references only after the upload is
+   confirmed. A local `public/` copy or source URL is not an imported asset.
+3. Preserve third-party integrations unless Fimo reproduces their exact
+   user-visible behavior. Record required environment-key names only.
+4. Use a Fimo-native form only when it matches the source behavior end to end;
+   otherwise preserve the integration or report it unresolved.
+
+After every media obligation has a target mapping, patch the content payloads
+and run one data worker per schema/locale. Verify each imported batch by
+read-back before starting its content code worker. The code worker replaces
+each planned consumer in place and proves at least one real imported item
+crosses every Server-to-Client or plain-JSON boundary it uses. A build over an
+empty result is not proof. Load the active `fimo-code` framework reference for
+the exact serialization and hydration contract.
+
+## Phase 5: Framework implementation
+
+Preserve the detected source framework, router, runtime, and configuration.
+React Router/Vite stays React Router/Vite and Next.js stays Next.js. Convert to
+Next.js only after the user explicitly chooses it. An explicit conversion is a
+faithful first pass owned by the framework conversion worker: it ports the
+source's APIs, loaders, hardcoded content, integrations, and visible behavior
+into the new framework, and it must pass the framework gate in
+`references/workers/framework.md` before content code work continues. A gate
+failure is draft-only or unresolved; never fall back silently to a generic
+shell or another framework. Load the matching `fimo-code` framework and
+hosting references before integration work.
+
+Preserve the source route surface and behavior. Do not replace many pages with
+one generic static shell. Apply the matching framework reference before
+disposing of provider-specific rules; redirects, headers, feeds, metadata,
+forms, and freshness behavior are observable contracts.
+
+## Phase 6: Fan in, validate, and report
+
+Workers return the plain-text receipt defined in `references/workers.md`.
+The coordinator checks those claims against the diff, source, CLI read-back,
+build, and rendered routes. Then an independent worker follows
+`references/workers/validator.md`; a worker saying "done" is not evidence.
+
+Write `.fimo/migration/migration-report.md` with route/content/media/form/SEO
+coverage, import counts, worker timings, unresolved items, and next actions.
+Use `complete` only when required checks pass, `complete-with-unresolved` when
+the app works and every gap is explicit, and `draft-only` when import or
+verification is incomplete.
+
+All checks are local. Do not deploy or publish to verify a migration.