diff --git a/docs/superpowers/specs/2026-04-02-xlibre-updater-design.md b/docs/superpowers/specs/2026-04-02-xlibre-updater-design.md
new file mode 100644
index 0000000..3a2ecf3
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-02-xlibre-updater-design.md
@@ -0,0 +1,57 @@
+# XLibre Updater Design
+
+## Goal
+Add a repository-managed workflow for updating and building the Stormux XLibre package set in the correct dependency order, while keeping `xlibre-video-dummy-with-vt` manually maintained and reviewed against upstream `xlibre-video-dummy`.
+
+## Scope
+This design covers:
+- correcting the package build order in `scripts/upgrade-xlibre.sh`
+- reviewing and updating `scripts/xlibre-video-dummy-with-vt/PKGBUILD`
+- regenerating `.SRCINFO` after PKGBUILD changes
+
+This design does not automate AUR publication or rewrite the downstream package from upstream sources.
+
+## Current State
+The updater script currently builds packages in an order that does not match the XLibre dependency chain. `xlibre-video-dummy-with-vt` is also version-skewed relative to the current AUR `xlibre-video-dummy` package and needs a manual rebase of relevant packaging changes.
+
+## Dependency Order
+The package build order will be:
+
+1. `xlibre-xserver-common`
+2. `xlibre-xserver-devel`
+3. `xlibre-input-libinput`
+4. `xlibre-xserver`
+5. `xlibre-video-fbdev`
+6. `xlibre-video-dummy-with-vt`
+
+This order reflects current AUR dependencies: `xlibre-xserver` requires `xlibre-xserver-common` and `xlibre-input-libinput`, while the input and video driver packages require `xlibre-xserver-devel` to build.
+
+## Downstream Package Policy
+`xlibre-video-dummy-with-vt` remains a separate, manually maintained package because it has a different maintainer and should not be auto-derived from the upstream AUR package.
+
+The maintenance rule is:
+- treat AUR `xlibre-video-dummy` as the packaging baseline
+- manually port relevant upstream PKGBUILD changes into `xlibre-video-dummy-with-vt`
+- keep only the intentional downstream delta needed for VT behavior
+
+## Implementation Shape
+`scripts/upgrade-xlibre.sh` will continue cloning packages from AUR and building them locally, but with the corrected order.
+
+`scripts/xlibre-video-dummy-with-vt/PKGBUILD` will be updated to match the current upstream package structure where appropriate:
+- current version and release
+- current `depends` and `makedepends`
+- current build flags and source layout
+- regenerated checksums
+
+The VT-specific patch remains the only behavioral divergence.
+
+## Error Handling
+The script should fail fast on clone or build errors and stop rather than continuing with a broken package chain. Because package order is intentional, partial success should be considered incomplete.
+
+## Verification
+Verification will be task-focused:
+- confirm the updater script contains the corrected package order
+- compare the downstream PKGBUILD against current upstream `xlibre-video-dummy`
+- regenerate and verify `.SRCINFO`
+- run `shellcheck` on the updater script
+- run `makepkg --printsrcinfo` in the downstream package directory