Abyss v2 Migration Orchestrator

Orchestrates upgrading from Abyss Design System v1 to v2.

Checklist-driven workflow

Copy this checklist and check off each item as you complete it:

Migration Progress:
- [ ] Step 1: Run detection script (platform, version, latest v1 check)
- [ ] Step 2: Run scan script (tokens, component imports)
- [ ] Step 3: Install required child skills
- [ ] Step 4: Present findings to user (see references/detection-logic.md)
- [ ] Step 5: Determine migration sequence (see references/sequence-logic.md)
- [ ] Step 6: If v1.x.x, present two-path choice (see references/migration-paths.md)
- [ ] Step 7: Get user confirmation
- [ ] Step 8: Execute skills in sequence (see references/execution-workflow.md)
- [ ] Step 9: Final verification - build, test, commit

What this skill does

1. Auto-detects platform (web/mobile/both) and package versions
2. Verifies you are on latest v1 before migration (if on v1.x.x)
3. Scans for legacy tokens, component token overrides, and component usage
4. Recommends the optimal migration sequence
5. Executes specialized child skills in the right order

When to use

Invoke this orchestrator when:

• User asks to "migrate to Abyss v2"
• User asks to "run v2 migration"
• User wants to know "what migration work is needed"
• User is starting a v1 to v2 upgrade

Do NOT invoke if:

• User asks about a specific migration tool (invoke that tool directly)
• User has documentation questions (use abyss-documentation skill)
• Migration is already complete

Skill dependencies

This orchestrator installs child skills on-demand:

• abyss-v2-migration-web - Component migrations (web)
• abyss-v2-migration-mobile - Component migrations (mobile)
• abyss-v2-legacy-tokens - Legacy token detection and migration
• abyss-v2-component-tokens-web - Component token override codemod

Skills are installed via git sparse-checkout to the same directory as this orchestrator.

What gets auto-detected

1. Component usage

• Greps for @uhg-abyss/web or @uhg-abyss/mobile imports
• On v1.x.x: Need V1 to V2 migration
• On v2.x.x: Need import normalization

2. Component token overrides

• Greps createTheme() calls for v1 token patterns (e.g., accordionV2-borderWidth-*)
• Action: Invokes abyss-v2-component-tokens-web codemod if detected AND on v2.x.x

3. Legacy tokens

• Greps src/ for legacy token names ($primary1, $bold, $md, etc.)
• Action: Invokes abyss-v2-legacy-tokens skill if detected AND on v2.x.x

---

Orchestration steps

Step 1: Detect platform and version

Run from the directory containing package.json and src/:

bash scripts/detect-platform-version.sh

Outputs: PLATFORM, WEB_VERSION, MOBILE_VERSION, and latest v1 check if applicable.

If not on latest v1, present this warning:

WARNING: Not on Latest V1 Version

STRONGLY RECOMMENDED: Upgrade before proceeding:

npm install @uhg-abyss/web@^1    # for web
npm install @uhg-abyss/mobile@^1  # for mobile

Why: V2 components were pre-released in v1. Latest v1 ensures all V2 components are available.

1. Stop here and upgrade to latest v1 first (recommended)
2. Proceed anyway (some V2 components may not be available)

Step 2: Scan for migration needs

bash scripts/scan-migration-needs.sh $PLATFORM

Outputs: TOKEN_COUNT, COMPONENT_TOKEN_COUNT, COMPONENT_IMPORT_COUNT

Step 3: Install required skills

BRANCH="main" bash scripts/install-skills.sh

If installation fails, present manual install commands:

Could not install required skills automatically

Install manually using:

npx @uhg-abyss/cli skills add <skill-name>

Once installed, say "continue" and I will resume.

Do NOT proceed until all required skills are installed.

Step 4: Present findings

Read references/detection-logic.md for the detection results template and status logic.

Present a clear summary of:

• Platform and versions detected
• Component migration needs (YES/NO)
• Legacy token needs (YES/DETECTED/NO)
• Component token override needs (YES/DETECTED/NO/N/A)
• Recommended migration sequence

Step 5: Determine migration sequence

Read references/sequence-logic.md for the skill invocation order logic.

Critical rule: Components ALWAYS migrate before tokens.

Sequence order:

1. abyss-v2-migration-web / abyss-v2-migration-mobile (if components detected)
2. abyss-v2-component-tokens-web (if web + component tokens detected)
3. abyss-v2-legacy-tokens (if legacy tokens detected)

Step 6: Handle v1.x.x special case

If on v1.x.x, present two migration paths. Read references/migration-paths.md for the full template.

Path A (Gradual): Stay on v1.x.x, migrate incrementally, upgrade when done. Recommended.

Path B (Fast): Upgrade to v2.x.x immediately, run all migrations at once. Riskier.

Wait for user to choose: gradual, upgrade, help, or cancel.

Step 7: Get user confirmation

Would you like me to proceed with this migration sequence? (yes/no)

- Type 'yes' to execute all skills in sequence
- Type 'custom' to select specific skills
- Type 'no' to cancel

Step 8: Execute skills

Read references/execution-workflow.md for detailed execution steps.

For each skill in the sequence:

1. Inform user which skill is being invoked
2. Read the child skill's SKILL.md from $SKILL_DIR/<skill-name>/SKILL.md
3. Follow the child skill's workflow
4. Verify completion
5. If verification fails, pause and ask user for guidance

Step 9: Final verification

## Migration Complete!

Please verify the migration:

1. Build your project and check for compile errors
2. Run your tests to catch regressions
3. Start the app and spot-check key pages/screens
4. Commit your changes when satisfied

---

Related skills

• abyss-v2-legacy-tokens - Detect and migrate legacy tokens
• abyss-v2-component-tokens-web - Transform component token names
• abyss-v2-migration-web - Web component migration
• abyss-v2-migration-mobile - Mobile component migration

Support

• Documentation: Abyss v2 Migration Guide

Error handling

When encountering errors during orchestration:

1. Diagnose - Check which skill failed, review error messages, verify package versions
2. Recover - Retry with adjusted parameters, skip optional steps, or run skills individually
3. Report - If unable to resolve, see references/error-handling.md for the issue template

Skill feedback

If user says "Report skill issue" or "This isn't working, help me report it":

1. Read references/feedback.md and follow its workflow