LedgerHQ/lumen / .claude/skills/lumen-consumer-upgrade
lumen-consumer-upgrade
VerifiedUpgrade a consumer repo to the latest Lumen: audit the gap, bump every `@ledgerhq/lumen-*` package, apply each migration crossed, verify, and open the PR. Run from the consumer repo's root, only when asked to upgrade or audit Lumen there.
lumen-consumer-upgrade
Run from the consumer repo's root. Two phases with a stop between them: the audit changes nothing, and the upgrade starts only once a human has read the audit.
What changed between two versions comes from two sources, used together. Never infer it from memory.
- references/breaking-changes.md: the catalog. Every migration, with its versions, detection, fix and kind.
- scripts/lumen-api-diff.mjs: the mechanical diff between two published versions. It catches removals the catalog missed (exports, files, tokens), but not behavior.
1. Audit (read-only)
-
Map the repo. Find every
package.jsonthat declares a Lumen package (monorepos: all workspaces, plus pnpm catalogs). Include retired and renamed packages listed in the catalog's Setup section. Note the package manager. -
Installed versions come from the lockfile, not the ranges in
package.json. -
Target versions:
npm view @ledgerhq/<pkg> versionfor each. Packages that pin each other as peers (check theirpeerDependencies) move together. -
Select rows with the catalog's "Which rows apply" rule. List skipped ids in one line. If a selected row's fix says Stop, report it and stop.
-
Run each selected row's detection. Record
file:linehits. A row with no hits is listed as "checked, not used". Never skip a row because it looks unlikely. -
Diff each package between its installed and target versions:
node <this skill>/scripts/lumen-api-diff.mjs @ledgerhq/<pkg> <installed> <target>The script resolves
typescriptfrom the working directory. If the repo's dependencies aren't installed, run it from a scratch folder that hastypescriptinstalled.Grep the app for every removed export, file,
var(--token)and class pattern. A hit no row explains goes under "Uncatalogued". -
Write the audit with references/audit-template.md, then stop: ask for the judgment calls and whether to proceed. Print the audit in your reply first: the user must be able to read it before answering.
2. Upgrade
One branch and one PR per repo. Apply in this order. Each step leaves the repo building.
-
Repo conventions, before the first branch or commit. The consumer's rules beat this skill's templates. Read its
CONTRIBUTING.md,AGENTS.mdand.github/workflows(PR-title, branch-name and release-marker validators), and note:- Branch name: match the validator's regex exactly (e.g.
chore/no-issue-upgrade-lumen-<version>, notchore/upgrade-lumen-…). A pushed branch can't be renamed under an open PR, so get it right first. - Commit and PR title format (e.g. gitmoji + scope + ticket): it overrides the title in the PR template. Test your title against the regex.
- Release intent: if the diff touches a published package, add what the
repo requires (
.nx/version-plans/,.changeset/, a label) in the same PR, following an existing file's format. If the consumer is itself published and releases from itspackage.jsonversion(no marker files), bump it in the same PR or nothing ships. A dependency-only upgrade is apatch; useminoronly if the user asks or the repo's history does. - Toolchain: the pinned Node/package manager (
.prototools,.nvmrc,packageManager). If it isn't installed, say so up front and list which checks ran under a different version.
- Branch name: match the validator's regex exactly (e.g.
-
Setup rows first: they change packages or build setup that later steps depend on.
-
Bump every Lumen package to its target and reinstall.
-
🔊 Loud rows: fix every Lumen typecheck error with its row's fix. The typecheck is the checklist: keep going until it's clean.
-
🔇 Silent rows: fix every audit hit. These produce no error.
-
⚖️ Judgment rows: apply only confirmed choices. Never pick a size, color or behavior silently. If unconfirmed, use the row's default and list it in the PR.
-
♻️ Replacement rows: Lumen now provides something the app built itself. For each local version the detection found:
- If it does nothing beyond Lumen's (the row says what to check), point it at Lumen's export so call sites stay untouched. Delete it only when nothing else lives in that file.
- If it adds behavior of its own, keep it and flag it in the PR for the owning team.
- Remove dependencies the local version needed only once nothing imports them.
♻️ steps inside other rows' fixes follow the same rule, applied with their row.
-
👁 Visual rows: no code change. List each affected screen in the PR.
Bump packages the repo already uses. Don't add new Lumen packages in this PR: list them as follow-ups.
3. Verify
- Install, typecheck, lint, test and build pass. A failure that also exists on the base branch is reported as pre-existing, not fixed.
- Re-run every applied row's detection and every pattern from the diff.
- Patterns matching the old API (a removed name, value, class, token or file): zero hits.
- Patterns matching call sites (
<Avatar\b…) still match after a correct fix: check each hit against the fix and list it as reviewed.
- Open the screens listed under 👁 in the running app. If you can't run it, say so in the PR.
4. PR
Use references/pr-template.md for the body. Cite the row id behind every change. The branch name, PR title and release marker follow step 0, not the template.
Committing and pushing may need credentials the agent can't reach (commit signing, GitHub login). Check early with a dry run, and if blocked, hand the user the exact commands instead of retrying around it.
Rules
- Scope: the upgrade only. Other findings go under "Follow-ups", not in the diff.
- Lumen gaps: if a fix needs something Lumen doesn't have, don't hand-roll it. List it under "Lumen gaps".
- No guessing: if a row's fix doesn't fit a call site, leave it, explain why in the PR, and ask.
- The published code wins over release notes and catalog text when they
disagree. Check the
distof both versions. - Catalog drift: never edit the catalog during an audit or upgrade. Once the PR is open, turn each "Uncatalogued" finding into a row in a separate Lumen PR.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |