Theme Update — Weaverse Pilot

Safely upgrade a Weaverse Pilot theme from its current version to a newer release. This skill walks through detection, planning, execution, and verification — never overwriting user customizations without explicit approval.

Source

Theme repo: https://github.com/Weaverse/pilot
Releases: https://github.com/Weaverse/pilot/releases
Package name:
```
@weaverse/pilot
```
Versioning:
```
YYYY.M.D
```
(e.g.,
```
2026.4.7
```
). Older: semver (
```
v8.1.0
```
)

Quick Check

bash

node skills/theme-update/scripts/check_pilot_updates.mjs
node skills/theme-update/scripts/check_pilot_updates.mjs --target v2026.4.7

Procedure

Follow these phases in order. Do NOT skip steps.

Phase 1 — Detection

Read
```
package.json
```
→ get
```
version
```
field
If
```
name
```
is not
```
@weaverse/pilot
```
, ask the user to confirm this is a Pilot-based project
Fetch releases:

bash

curl -s "https://api.github.com/repos/Weaverse/pilot/releases?per_page=50"

Identify all releases between current version and latest (or user-specified target)
Present to user:
- Current version
- Target version (latest unless specified)
- Number of intermediate releases
- Summary of key changes (features, fixes, breaking changes)

If already on latest → stop here and tell the user.

Phase 2 — Branch

bash

git checkout -b update/v{CURRENT}-to-v{TARGET}
git push -u origin update/v{CURRENT}-to-v{TARGET}

Always work on a branch. Never update on main directly.

Phase 3 — Plan

For each release in the update range (oldest to newest):

Fetch the diff between consecutive versions:

bash

# Full comparison URL
https://api.github.com/repos/Weaverse/pilot/compare/v{OLD}...v{NEW}

# Raw diff
https://github.com/Weaverse/pilot/compare/v{OLD}...v{NEW}.diff

Download the target version's source (for reference files):

bash

curl -sL "https://api.github.com/repos/Weaverse/pilot/tarball/v{TARGET}" | tar xz

Categorize every changed file into three buckets:

Auto-merge (safe to apply without asking)

```
package.json
```
version bump, dependencies

Lock files (

package-lock.json

bun.lockb

pnpm-lock.yaml

)

tsconfig.json

vite.config.ts

tailwind.config.ts

— ONLY if user hasn't customized them

New files that don't exist in user's project (additive only)
```
.github/
```
,
```
CHANGELOG.md
```
,
```
LICENSE
```

Needs review (show diff, get approval)

```
app/components/
```
— UI components user may have customized
```
app/routes/
```
— route files user may have modified
```
app/lib/
```
— utility modules

app/root.tsx

app/entry.client.tsx

app/entry.server.tsx

```
app/styles/
```
— CSS/Tailwind changes
Any file where the user has local changes (
```
git diff
```
shows modifications from Pilot base)

Skip (mention but don't touch)

Files the user deleted (they removed the feature intentionally)
Files in directories the user reorganized
```
.env
```
,
```
.env.example
```
— never overwrite environment files

Present the plan in a clear table:

## Update Plan: v2026.3.23 → v2026.4.7

### Auto-merge (3 files)
✅ package.json — version + dependency bumps
✅ bun.lockb — lock file update
✅ app/lib/utils.ts — new helper function added

### Needs Review (5 files)
⚠️  app/components/Header.tsx — Pilot added shopify-account web component
    Your version: custom mega menu logic
    Pilot change: replaced AccountButton with <shopify-account>
    → Recommend: keep your mega menu, add shopify-account separately

⚠️  app/routes/_index.tsx — performance improvements
    Your version: added custom hero section
    Pilot change: caching + skeleton loading
    → Recommend: apply caching, keep your hero

### New Files (2 files)
➕ app/components/ScrollReveal.tsx — new scroll animation component
➕ app/lib/reviews.ts — extracted reviews API

### Skipped (1 file)
⏭️  app/components/CombinedListings.tsx — you deleted this file

Wait for user confirmation before proceeding. Ask:

"Review the plan above. Approve to continue, or tell me which files to handle differently."

Phase 4 — Execute

Apply changes in order, one release at a time if multi-version jump:

4a. Auto-merge files

bash

# Copy new file from Pilot source
cp /tmp/pilot-reference/{FILE_PATH} {FILE_PATH}

# Or apply targeted patch
git apply --3way <patch-file>

After each auto-merge, verify with

git diff --stat

4b. Needs-review files

For each file:

Show a three-way comparison:
- Pilot at user's version (baseline)
- Pilot at target version (their changes)
- User's current file (local modifications)
Identify what the user changed vs what Pilot changed:
- User-only changes → preserve
- Pilot-only changes → apply
- Overlapping changes → flag conflict
For conflicts, present options:
- Accept Pilot's version (lose user customization)
- Keep user's version (skip Pilot improvement)
- Manual merge (show both, let user edit)
- Smart merge (try to combine both — only if non-overlapping regions)
Wait for user decision on each conflict before proceeding.

4c. Commit per release

bash

git add -A
git commit -m "chore: update Pilot v{OLD} → v{NEW}

- [list key changes applied]
- [list files with manual merge decisions]
"

If doing multi-version jump, repeat for each intermediate release.

Phase 5 — Verify

After all changes applied:

bash

# 1. Install dependencies
bun install  # or npm install / pnpm install based on lockfile

# 2. TypeScript check
bun run typecheck

# 3. Build check
bun run build

If build fails:

List the errors
Analyze root cause (dependency mismatch? breaking change missed?)
Propose fixes
Apply fixes with user approval
Re-run build

If build succeeds:

Run
```
bun run dev
```
briefly to check no runtime errors
Summarize all changes made
List any manual follow-up steps:
- New features that need configuration
- Breaking changes requiring code updates in customized files
- Deprecated patterns to migrate later

Phase 6 — Finalize

Present final summary:

## Update Complete: v2026.3.23 → v2026.4.7

✅ 12 files auto-merged
✅ 5 files reviewed and merged
✅ 2 new files added
✅ Build passes
✅ TypeCheck passes

### New features available
- Shopify Account Web Component (<shopify-account>)
- Vite chunk splitting for better caching
- ScrollReveal component for animations

### Manual follow-up (optional)
- Configure shopify-account in your Header if you want native sign-in
- Review ScrollReveal component for use in custom sections

### Rollback
git checkout main
git branch -D update/v2026.3.23-to-v2026.4.7

Ask user: "Ready to merge into main?"

bash

# If approved
git checkout main
git merge update/v{CURRENT}-to-v{TARGET}
git push origin main

Safety Rules

Always branch first — never update on main directly
Never overwrite without asking — every file that could have user changes needs review
Commit per release — easy to bisect if something breaks
Build must pass — don't declare success until
```
typecheck
```
+
```
build
```
both pass
Offer rollback — always tell user how to undo the whole update
Respect user deletions — if they removed a file, don't re-add it without asking

Common Pitfalls

Version format: package.json has no
```
v
```
prefix (
```
2026.4.7
```
), GitHub tags have
```
v
```
prefix (
```
v2026.4.7
```
). Always normalize.
Lock files: After updating
```
package.json
```
, MUST run the correct package manager (check which lockfile exists)
Custom components: User components not in original Pilot are always preserved — never delete or move them
Route structure: If user reorganized routes, don't force Pilot's structure — apply route logic changes to user's structure instead
CSS conflicts: Pilot may change Tailwind classes or base styles — these need careful merge to avoid breaking user styling

theme-update

NPX Install

Tags

SKILL.md Content

Theme Update — Weaverse Pilot

Source

Quick Check

Procedure

Phase 1 — Detection

Phase 2 — Branch

Phase 3 — Plan

Auto-merge (safe to apply without asking)

Needs review (show diff, get approval)

Skip (mention but don't touch)

Phase 4 — Execute

4a. Auto-merge files

4b. Needs-review files

4c. Commit per release

Phase 5 — Verify

Phase 6 — Finalize

Safety Rules

Common Pitfalls