widget-migrate

What this skill does

# Widget Migration Pipeline

Migrate legacy widgets to React Router 7 + Iris design system + TypeScript.

**Estimated Time:** 15-40 minutes (depending on mode and widget complexity)
**Target Stack:** React Router 7 + Iris Design System + TypeScript (hard-coded, no questions)
**Output:** Widget specs in `docs/specs/widgets/{widget-name}/` + BMAD-compatible stories

---

## When This Skill Activates

Activate when:
- A legacy widget (V9 Velocity, V9 Viewmodel, or Osiris) needs migration to React Router 7 + Iris
- The user requests the full pipeline: resolve -> detect -> extract -> map -> generate specs + stories
- The user wants preference-complete and component-complete migration artifacts
- Output should feed directly into BMAD's `/create-story` and `/dev-story` workflows

**Trigger Phrases:**
- "Migrate this widget"
- "Widget migration"
- "Convert this widget to React"
- "Migrate to Iris"
- `/stackshift.widget-migrate v9.widgets.model-selector.responsive.v1`
- `/stackshift.widget-migrate ws-hours`

**Not supported:** GVM widgets. If the user requests GVM migration, respond: "GVM widget migration is not yet supported. Only V9 Velocity, V9 Viewmodel, and Osiris widgets are supported."

---

## Invocation

### Option A: Widget ID as Argument (Recommended)

Run from the **target platform repo** (e.g., `dealer-platform/`):

```
/stackshift.widget-migrate v9.widgets.model-selector.responsive.v1
/stackshift.widget-migrate ws-hours
/stackshift.widget-migrate v9.viewmodel.map.dynamic
```

The pipeline auto-resolves the widget source location, extracts everything, and writes output to `docs/specs/widgets/`.

### Option B: From Widget Directory (Legacy)

Navigate to the widget source directory and run:

```
cd ~/git/cms-web/htdocs/v9/widgets/model-selector/responsive/v1/
/stackshift.widget-migrate
```

Output goes to `_widget-migrate/` in the widget directory.

---

## Pipeline Overview

Step 0: Resolve + Detect -> Step 1: Extract -> Step 2: Preference Catalog -> Step 3: Iris Mapping -> Step 4: Portable Specs -> Step 5: Targeted Epics -> Step 6: Migration Report -> Step 7: Write Output

Target stack is hard-coded: React Router 7 + Iris + TypeScript. No questions about target.

---

## Three Modes

### Mode 1: YOLO (Fully Automatic)

**Time:** ~15-20 minutes
**User input:** None after initial mode selection

- Run full extraction and generation without pausing
- Resolve ambiguities with best-effort inference
- Mark uncertain items with `[AUTO - review recommended]`

**Best for:** Batch processing, quick assessment.

### Mode 2: Guided (Recommended)

**Time:** ~25-30 minutes
**User input:** 3-8 targeted questions

- Auto-extract high-confidence items
- Pause to ask targeted questions for ambiguous items only:
  - "This preference has no obvious React equivalent. Best mapping?"
  - "This component has no direct Iris match. Custom component or closest equivalent?"
  - "These 3 business rules interact. Confirm priority order?"

**Best for:** Most widget migrations. Good balance of speed and quality.

### Mode 3: Interactive

**Time:** ~30-40 minutes
**User input:** Full conversation at each step

- Present preference catalog for approval before continuing to Step 3
- Present Iris mapping for approval before continuing to Step 4
- Review each epic before finalizing Step 5

**Best for:** Complex widgets, critical business logic, maximum precision.

---

## Process

### Step 0: Resolve + Detect Widget

**If a widget ID argument is provided**, follow `operations/resolve-widget-source.md`:

1. Parse widget ID to determine type (`v9.widgets.*`, `v9.viewmodel.*`, `ws-*`)
2. Resolve filesystem path to source code
3. Validate source exists (offer to clone repo if missing)
4. Extract widget identity metadata

**If no argument** (running from widget directory), follow `operations/detect-widget-type.md`:

1. Check current directory against detection patterns
2. Classify as: `v9-velocity`, `v9-viewmodel`, or `osiris`
3. Extract widget identity (category, name, version for V9; workspace name for Osiris)
4. Validate repository access (cms-web, cms for V9)
5. If unknown: error with guidance on expected directory structure

**Error handling:** If resolution or detection fails (repo not found, path invalid, unknown format), stop the pipeline. Do not proceed to Step 1 without a confirmed widget type and source path.

**Progress signal:** Log "Step 0 complete: Detected {widget_type} at {source_path}". Update `.stackshift-state.json` `steps_completed` array with `"resolve"` and `"detect"`.

**Detection state saved:**
```json
{
  "detection_type": "v9-velocity",
  "implementation_framework": "widget-migrate",
  "resolved_from": "argument",
  "widget_identity": {
    "category": "model-selector",
    "name": "responsive",
    "version": "v1",
    "widget_id": "v9.widgets.model-selector.responsive.v1"
  },
  "source": {
    "path": "~/git/cms-web/htdocs/v9/widgets/model-selector/responsive/v1/",
    "repo": "~/git/cms-web"
  }
}
```

### Step 1: Extract Business Logic

**Note:** The `cms-web-widget-analyzer` agent uses "Phase" for its internal stages. These are not the same as widget-migrate "Steps".

**Delegate extraction based on widget type:**

#### For V9 Velocity and V9 Viewmodel Widgets

Invoke the `cms-web-widget-analyzer` agent (defined in `agents/cms-web-widget-analyzer/AGENT.md`).

The agent performs deep analysis across 7 phases:
1. Widget Discovery & Classification
2. Widget Configuration Extraction
3. Component Dependency Tree Analysis (recursive #parse tracing)
4. Helper Object Analysis (business logic in $helper calls)
5. Conditional Logic Extraction (business rules from #if blocks)
6. Portlet Configuration Analysis (all preferences from XML)
7. Java Backend Analysis (portlet class business logic)

**Output used by subsequent steps:**
- `component-dependency-tree.md` -> feeds Step 3 (Iris mapping)
- `portlet-configuration.md` -> feeds Step 2 (preference catalog)
- `business-rules.md` -> feeds Step 4 (portable specs)
- `helper-object-usage.md` -> feeds Step 4 (portable specs)
- `java-backend-logic.md` -> feeds Step 4 (portable specs)
- `component-catalog.md` -> feeds Step 3 (Iris mapping)
- `data-flow.md` -> feeds Step 4 (portable specs)

#### For Osiris Widgets

Invoke the `stackshift:stackshift-code-analyzer:AGENT` agent with the standard StackShift reverse-engineering process.

The agent performs:
1. React/Angular component analysis
2. State management extraction
3. API integration mapping
4. Business logic identification
5. Configuration extraction (preferences from `config/prefs.json`)

**Output files (11 reverse-engineering docs in `docs/reverse-engineering/`):**
- `overview.md` -> feeds Step 6 (migration report)
- `component-catalog.md` -> feeds Step 3 (Iris mapping)
- `data-flow.md` -> feeds Step 4 (portable specs)
- `state-management.md` -> feeds Step 4 (portable specs)
- `api-integration.md` -> feeds Step 4 (portable specs)
- `business-logic.md` -> feeds Step 4 (portable specs)
- `configuration.md` -> feeds Step 2 (preference catalog)
- `error-handling.md` -> feeds Step 4 (portable specs)
- `routing.md` -> feeds Step 5 (targeted epics)
- `testing.md` -> feeds Step 6 (migration report)
- `dependencies.md` -> feeds Step 3 (Iris mapping)

**ws-scripts exclusion:** Osiris widgets depend on `ws-scripts` for build tooling, web server, testing framework, and development utilities. These are platform concerns that React Router 7 replaces. Exclude ws-scripts functionality from extraction.

**Error handling:** If the extraction agent fails or produces incomplete output (missing key files like component-catalog or business-logic), stop the pipeline. Report which output files are missing and suggest re-running extraction.

**Progress signal:** Log "Step 1 complete: Extracted {N} files from {widget_type} widget". Update `steps_completed` with `"extract"`.

### Step 2: Generate Preference Catalog

Follow the process in `operations/generate-preference-catalog.md`:

1. Extract