android-update-deps

name	android-update-deps
description	Reviews and safely updates the dependencies of an Android project (Android Studio; Kotlin/Gradle) that uses a Gradle version catalog. Detects available updates with the ben-manes gradle-versions-plugin, checks JitPack libraries by hand (the plugin's blind spot), assesses risk, and — only after explicit confirmation — edits libs.versions.toml, verifies with an Android build (:app:assembleDebug), commits locally, and in a separate commit adapts the existing code to the new APIs. Use this whenever the user wants to update, review, or bump dependencies in an Android app, asks "what's outdated", mentions libs.versions.toml / version catalog / AGP / Compose BOM upgrades, or runs /android-update-deps — in English or Spanish ("actualiza/revisa las dependencias", "qué hay desactualizado").
license	MIT
compatibility	Requires an Android/Kotlin Gradle project (ideally with a version catalog), the ben-manes gradle-versions-plugin, and the Android SDK.
metadata	{"author":"alvarose","version":"1.2.0"}

android-update-deps — controlled dependency review & update

A fixed, repeatable procedure to keep an Android (Kotlin/Gradle) project's dependencies current.

Communicate in the language the user is writing in (default English; mirror Spanish or any other language they use). Never apply a change without explicit confirmation — this workflow is gated on purpose (step 5). Bumping dependencies silently is how a working build breaks.

Commands: examples use ./gradlew (Unix/macOS/Git Bash). On Windows PowerShell use .\gradlew.bat. If a Bash/shell terminal is available, run them there so ./gradlew works on any OS.

Discovery (do this first in a new repo)

This skill is generic; every repo differs. Before touching anything, learn the project's shape:

1. Locate the version catalog — usually gradle/libs.versions.toml. If it doesn't exist, versions may be inline in the build.gradle.kts files; say so — those files become the edit target.
2. Confirm the detection tool. Check whether ben-manes/gradle-versions-plugin is applied (grep for dependencyUpdates / com.github.ben-manes.versions in the build.gradle.kts). If it is not applied, offer to add it temporarily. When you do, use its latest stable version (look it up on the Gradle Plugin Portal / the plugin's releases) — a dependency-update tool shouldn't introduce an outdated dependency; it only needs 0.52.0+ to run on Gradle 9. Configure it so the rest of this flow works: outputFormatter = "json,plain" (the aggregate script reads report.json, not .txt), gradleReleaseChannel = "current" (surfaces the wrapper update — see the gradle section note below), and a rejectVersionIf { } that skips pre-releases. Revert this change once you have the report — it's a detection aid, not part of the update.
3. List JitPack dependencies (com.github.* in the catalog) up front — they are the plugin's blind spot and must be checked by hand (step 1b, details in references/reference.md).
4. Map coupled version blocks. Inspect [versions] and [libraries] for shared version.refs and BOMs, and build the project's coupling table — see references/reference.md. General rule: any set of artifacts sharing a version.ref or governed by a BOM is a single item.
5. Find the Android SDK, the JDK/compileSdk baseline, and the wrapper. The Android SDK path comes from the repo's own local.properties (sdk.dir=…) — it is per-machine and git-ignored, not ANDROID_HOME. If local.properties is missing, the build can't run until it exists (see step 1). The JDK/compileSdk baseline lives in the convention plugins (, wired via in ) or in the module ; the Gradle wrapper is in .

If the repo has an AGENTS.md, CLAUDE.md, GEMINI.md, or .docs/ with build conventions, read it: it may pin where versions live and which libs are coupled.

Key facts for a catalog-based project:

• With convention plugins, module build.gradle.kts files declare no versions — the catalog is the single edit target.
• On Gradle 9+, dependencyUpdates must run without parallelism or it only scans the root module (--no-parallel). Each project writes build/dependencyUpdates/report.json.
• The Gradle wrapper is not in the catalog — bump it in gradle/wrapper/gradle-wrapper.properties, preferably via ./gradlew wrapper --gradle-version=X. Its available version isn't in the report's outdated bucket either: ben-manes reports it in a separate gradle section (only when gradleReleaseChannel = "current" is set), which scripts/aggregate-updates.py surfaces for you. Treat it as its own item with its own confirmation (bump it alongside AGP when an AGP upgrade requires it).

Procedure

1. Detect

Run ./gradlew dependencyUpdates --no-parallel (resolves network dependencies: may be slow, use a wide timeout). If it fails for missing local files, flag it — that's environment setup, not a dependency problem. The most common case is SDK location not found: the repo just needs a local.properties with sdk.dir=<path-to-Android-SDK> (git-ignored, per-machine). Others: keystore.properties, google-services.json.

If the plugin itself fails to run — a ben-manes × Gradle incompatibility, e.g. a ConcurrentModificationException or a removed-API error on a newer Gradle (not a problem with the project): try a newer ben-manes version and make sure you passed --no-parallel. If it still won't run, don't get stuck — fall back to manual metadata detection. The JitPack procedure (references/reference.md) generalizes to any artifact: read each catalog dependency's maven-metadata.xml from its repository (Maven Central, Google's Maven repo, etc.) for the latest stable release and compare with the catalog. Slower, but it unblocks detection without the plugin — then revert any plugin you added temporarily.

Prefer the plugin to reject pre-releases (alpha/beta/RC/SNAPSHOT) via rejectVersionIf; if it doesn't, filter unstable candidates yourself in step 3.

1b. Detect sources the plugin doesn't track (JitPack)

The step-1 report never includes JitPack libs (com.github.*) — they land in unresolved. Check them by hand following references/reference.md (build the metadata URL, read <release>, compare with the catalog, classify by risk).

2. Aggregate and deduplicate

Use the helper script for the mechanical part:

python scripts/aggregate-updates.py <repo-path>

It walks every */build/dependencyUpdates/report.json, deduplicates by group:name, and also lists the JitPack libs (com.github.*) left unresolved for step 1b. If you can't run it, do it by hand from the report.json files. Map each dependency to its key in libs.versions.toml.

3. Filter noise

• Drop any artifact governed by a BOM without its own version.ref (androidx.compose.* under composeBom, Firebase artifacts under their BOM, etc.). Only consider the BOM bump.
• Drop pre-release candidates if the plugin didn't already.
• Group coupled blocks (see references/reference.md) into a single item (e.g. "Kotlin X → Y ⇒ move KSP to Z").

4. Classify by risk

Judge each item on more than the version number:

• Semver magnitude: patch/minor (same major) = low risk; major (first number changes) or large multi-version jumps = high risk — flag it and link the changelog.
• Hidden requirements: a seemingly safe bump can demand a higher compileSdk, AGP, or Kotlin (common with AndroidX). Then it's coupled to that bump, not safe — the verify build (step 7) exposes it ("requires compileSdk N"); reclassify and defer it with the major it depends on.
• Security & license: treat a current version with known vulnerabilities as a reason to prioritize the bump (Android Studio flags vulnerable libraries via the Play SDK Index). On majors, watch for a changed license.
• Blocking toolchain bumps always get their own explicit yes — never the "safe" bucket. The Kotlin version is never "safe", not even for a minor/patch: it's a cascading compiler change that drags ksp, the Compose Compiler, and every Kotlin compiler plugin with it, and can break annotation processing or Compose. Always list kotlin (with its coupled block) separately under "handle with care" and require a distinct confirmation — an "apply the safe ones" approval must never move it. The same applies to AGP and the Gradle wrapper (an AGP major ⇒ Gradle + Studio, often compileSdk/JDK too): their own items, their own yes.
• KSP follows Kotlin. When Kotlin moves, ksp moves under the same confirmation — don't ask twice. A standalone ksp bump (same Kotlin line, e.g. a KSP-only patch) isn't "safe" either: it drives annotation processing (Room, Hilt), so put it under "handle with care" with its own note — the verify build (step 7) catches codegen breakage. The Compose Compiler shares the kotlin ref, so it always rides Kotlin's confirmation automatically.

5. Propose (GATE)

Present a table: catalog key | current → proposed | risk | note/changelog, grouped into "safe" vs "handle with care". Stop and wait for explicit confirmation. Let the user pick a subset (all / safe only / a specific list). Do not edit anything until they say go.

• The Kotlin version (and AGP) must never sit in the "safe" group: an "apply the safe ones" / "solo las seguras" approval must exclude them. They only move on their own explicit yes, called out as separate line items — even for a minor/patch.

6. Apply (only what was confirmed)

• Edit the version.refs in gradle/libs.versions.toml.
• Respect coupled blocks: if you bump kotlin, move ksp to the matching version in the same change.
• The wrapper, if included, via ./gradlew wrapper --gradle-version=<X>.

7. Verify

Build to confirm nothing breaks. Default:

./gradlew :app:assembleDebug

If the changes touch testing/Kotlin/coroutines, add tests + linters for the affected modules (./gradlew :<module>:testDebugUnitTest detekt/lint). Full validation: ./gradlew build.

• If it fails: isolate the culprit bump. Before reverting outright, try stepping down to the highest version that still compiles — a library's latest may pull a too-new transitive (e.g. a kotlin-stdlib the project's compiler can't read), while the previous minor works (real case: Coil 3.5.0 drags stdlib 2.4 and fails on a Kotlin 2.2 compiler, but 3.4.0 → stdlib 2.3 compiles). If nothing compiles, revert that version.ref. Either way report the real error and return to the gate with the adjusted proposal. Never leave the tree in a broken state.

8. Commit (local, thematic)

Before committing: confirm it's a git repo and that you are not on the default branch (main/master). If you are, create a branch first (e.g. chore/deps-update). One local commit per theme, no push unless explicitly asked:

chore(deps): bump <short list of what went up>

If there were distinct blocks (Kotlin/KSP on one side, test libs on the other), consider separate commits per theme.

9. Adapt the code to the new versions (post-bump)

After committing the bump, check whether the existing code needs adjustments. This is independent of the bump and goes in a separate commit — never mixed with chore(deps):. The step-7 build only guarantees it compiles, not that the code is up to date (deprecations still compile).

Scope: only libs whose API the production or test code consumes. Ignore pure tooling (detekt, secrets, google-services). Prioritize majors and minors; patches only if the changelog warns of deprecations.

1. Collect real deprecations. Compile with warnings visible and run the linters:

   ./gradlew :app:assembleDebug --warning-mode all
   ./gradlew lint detekt
   

   List the new deprecation warnings attributable to the bumps (as file:line).
2. Read the migration guide for each relevant major/minor: fetch the changelog URL the plugin's report already provides. Extract deprecated/renamed APIs and behavior changes.
3. Find usages in the code. Search the code for the old symbols across production and tests; map occurrences to file:line.
4. Propose (GATE). For each finding: what changes, why (cite the changelog), affected files, and the suggested refactor. Wait for confirmation. If there's nothing to adapt, say so explicitly.
5. Apply and re-verify what was confirmed (edit + build/tests/linters for what you touched).
6. Separate thematic commit: refactor(deps): adapt <X> to <lib> <version> API. One lib or theme per commit.

Notes

• Don't invent versions: the source of "what's new" is the plugin report for Maven Central/Google, plus the manual JitPack check (step 1b). To confirm a major's compatibility, read the changelog linked in the report (or the GitHub releases for JitPack libs).
• Optional automation: littlerobots' version-catalog-update-plugin can write the TOML automatically from the report. This skill deliberately keeps the manual gated flow; if the user prefers the automated one, apply it only after the same GATE in step 5.
• Adapt the "coupled versions" table (references/reference.md) to the concrete repo's catalog; don't assume every block exists.
• Supply chain: if the project doesn't already use Gradle dependency verification, suggest enabling it before a large update so downloaded artifacts are checksum/signature-verified.
• Transitive fan-out: a catalog bump also moves transitive dependencies. For higher-risk bumps, diff the resolved graph (./gradlew :app:dependencies, or a snapshot tool) to catch version conflicts (search for ->) and new AAR contributions (permissions/components added via manifest merge).
• SDK levels (compileSdk / minSdk / targetSdk) are not catalog dependencies. They live in the module android {} block or the convention plugins (build-logic/), sometimes surfaced as a [versions] value, and ben-manes does not track them. Scope for this skill:
  • compileSdk — raise it only when a confirmed dependency requires it (a "hidden requirement", step 4). Treat that as a coupled, high-risk item with its own confirmation; never bump it speculatively to chase new APIs.
  • targetSdk — out of scope. Raising it is a Play-Store-driven behavior migration (new permissions, behavior changes, its own testing). Flag it and defer to Android Studio's SDK Upgrade Assistant / a dedicated pass; don't move it as part of a dependency update.
  • minSdk — don't change it (a product decision that drops device support), but flag when a dependency bump raises the effective minSdk.