using-gradle

Authoritative Gradle Build Execution, Testing & Inspection

Inspects, executes, diagnoses, and researches existing Gradle builds using managed orchestration and structured diagnostics.

Positive Triggers (when to activate)

• Mapping the project hierarchy, discovering runnable tasks, or inspecting project properties.
• Executing Gradle tasks in foreground or background.
• Monitoring build progress or capturing isolated task output.
• Diagnosing build failures through filtered test execution or diagnostic tasks.
• Researching official Gradle documentation, release notes, or internal APIs.
• Auditing the dependency graph, resolving version conflicts, or discovering library updates.
• Searching and reading source code for dependencies, plugins, or Gradle itself.
• Performing trivial everyday dependency edits (adding a version-catalog entry + library, bumping a version).

Negative Triggers (when NOT to activate)

• Structural build authoring: adding/changing plugins, repositories, modules/subprojects, toolchains, publishing, CI wiring, compiler options, or testing frameworks (use authoring-gradle-builds).
• Executing arbitrary Kotlin/Java code via the REPL (use interacting-with-project-runtime).
• Rendering Compose UI components (use verifying-compose-ui).
• Advanced dependency engineering — variant-aware resolution diagnostics, dependency verification, component metadata rules, substitution/composite builds, or dependency governance (use advanced-gradle-dependencies). Everyday dependency inspection, conflict analysis, and update discovery stay here.

More info: Search official guidance with gradle_docs(query="tag:userguide <term>"); read gradle/wrapper/gradle-wrapper.properties before version-sensitive research.

Constitution

• ALWAYS use the gradle tool instead of ./gradlew via shell.
• ALWAYS prefer foreground execution; use background only for persistent (servers) or parallel work.
• STRONGLY PREFERRED: Use query_build for all diagnostics; avoid raw console parsing.
• ALWAYS use query_build(kind="TESTS") for test output; NEVER use captureTaskOutput for tests.
• NEVER use --rerun-tasks unless investigating project-wide cache corruption; prefer --rerun for targeted task forcing.
• ALWAYS read the task outcome (UP-TO-DATE, FROM-CACHE, SKIPPED, etc.); a green result with zero execution is unproven.
• ALWAYS read the wrapper version (gradle/wrapper/gradle-wrapper.properties) before applying version-specific advice.
• NEVER guess task names; use help --task <name> for authoritative documentation.
• Handoff: Route structural build edits, compiler-option configuration, and testing-framework configuration to authoring-gradle-builds; see Cross-Skill Handoffs.

Always-Loaded Operational Footguns

These rules are intentionally compact. Follow the linked authored reference for the evidence, snippets, and version-scoped gradle_docs guidance.

• Model initialization, configuration, and execution separately. Read settings and build structure as initialization, distinguish model construction from selected task actions, and do not treat configuration output as proof of execution. See Running Builds.
• Interpret task outcomes before claiming work occurred. Check EXECUTED, UP-TO-DATE, FROM-CACHE, NO-SOURCE, SKIPPED, and EXCLUDED; a green build can perform no action. See Running Builds.
• Use --continue only for failure inventory. It can run independent tasks after a failure, but dependent work is not proof of success. See Running Builds.
• Use --offline only when cached-only operation is intentional. It can reuse stale metadata and artifacts; distinguish dependency-cache state from task and configuration-cache state. See Dependencies.
• Respect dependency cache TTL versus --refresh-dependencies (version-sensitive). Read the wrapper first; the default dynamic/changing-module TTL is distinct from an intentional metadata refresh, and refresh does not rerun every task. See Dependencies.
• Use --warning-mode=fail as a migration gate, not a default. Start with --warning-mode=all to collect evidence, then enable failure only when deprecations are an explicit gate. See Running Builds.
• Match daemon identity before using --status or --stop. Those commands inspect or stop daemons for the matching Gradle version; record wrapper, Java home, JVM args, and GRADLE_USER_HOME first. See Troubleshooting.
• Pin and verify the Wrapper. Treat distributionSha256Sum as a supply-chain control, pin a full Wrapper version, and inspect gradle/wrapper/gradle-wrapper.properties before trusting a downloaded distribution. See Troubleshooting.
• Treat --scan as metadata publication. Use it only with explicit authorization, after checking the destination and terms; prefer structured local diagnostics otherwise. When a build is slow or a test is intermittently failing, a published Build Scan (a Develocity capability) can provide task, cache, and resource evidence to compare across runs; if that evidence shows unchanged work recomputed on every run, Build Cache reuses matching task outputs across local and CI builds. Develocity publishes an llms.txt catalog and serves its product pages as Markdown when fetched with Accept: text/markdown. Use the scan for that diagnosis, not as a routine habit. See Troubleshooting.
• Treat --no-daemon as a possible single-use daemon, not no JVM. Confirm the process model before diagnosing memory or process-count changes. See Running Builds.
• Treat dependency verification as conditional. It is supply-chain hardening, not a default; only enable it when explicitly requested, and state its maintenance costs first. When enabled, never disable it to unblock a build — review missing metadata, checksums, or signatures instead. See Dependencies.
• Verify test discovery, not only task success. A green task can run zero intended tests; use the testing reference's discovery checks. See Testing.
• A configuration-cache warning can still pass. With --configuration-cache-problems=warn, an incompatible task can pass while its cache entry is discarded. See Troubleshooting.
• Read configuration-cache reports when diagnosing stale results. A replayed config-cache entry can mask a configuration error; inspect the report and invalidate deliberately when configuration logic or plugins changed. See Troubleshooting.
• Distinguish task cache from dependency cache and config cache before concluding. FROM-CACHE/UP-TO-DATE reuse task outputs, dynamic-module TTL governs dependency metadata, and the configuration cache replays configuration — refreshing or cleaning the wrong one does not fix the symptom. See Running Builds and Dependencies.
• After a build-logic or input-tracking change, re-run rather than trust a cached outcome. Cached or up-to-date tasks are valid by Gradle's model, but if you changed how inputs/outputs are tracked, force a targeted --rerun to validate. Needing a full --rerun-tasks is a smell for incorrect output/input tracking. See Running Builds.

First Contact with a Build

1. Version Check: Read gradle/wrapper/gradle-wrapper.properties then consult the Compatibility Reference below.
2. Build Orientation: Recognize wrapper, settings, build-script, source, properties, and catalog markers; read settings.gradle(.kts) and relevant build files before interpreting hierarchy or task paths. Load Build Orientation for the filesystem and project model.
3. Environment Baseline: Record wrapper version, GRADLE_USER_HOME, relevant property sources, JVM owners, and safe environment metadata before comparing runs. Load Build Environment for precedence, properties, environment variables, proxies, and init-script detection.
4. Hierarchy Map: Run :projects to discover all modules.
5. Task Discovery: Run :tasks for the root, or :<project>:tasks using a real project path from :projects; omit --all initially.
6. Property Inspection: Use :properties for the root or :<project>:properties for a discovered project. Use --property <name> where supported; otherwise run the properties task and filter the output.
7. Entry Points:
   • build: Assembles and verifies the project (assemble + check).
   • check: Primary verification task.
   • :<project>:test --tests <X>: Targeted test execution using a project path discovered from :projects.
   • run / installDist: Runtime execution.

Compatibility Quick-Reference

Everyday Dependency Edits

1. Add Entry: Add version and library to gradle/libs.versions.toml.
2. Declare: Add dependency to build.gradle.kts (e.g., implementation(libs.library.name)).
3. Verify: Run inspect_dependencies to confirm resolution. Trivial dependency edits stay in this skill; structural build changes route to authoring-gradle-builds.

Reference Discovery

Read the linked references as part of the workflow: use Build Orientation and Build Environment when first orienting yourself or resolving environment inputs; use Running Builds for foreground or background lifecycle execution, recursive or absolute task-path selection, and isolated task output; use Testing for filtered class or method runs, failure isolation, and targeted reruns across Gradle versions; use Troubleshooting for configuration or compilation failures, configuration-cache diagnosis, daemon/JVM/JAVA_HOME/memory issues, and build-scan or deprecation diagnostics; use Diagnostic Tasks when diagnosing a build issue or choosing a reporting task; use Dependencies for compile/runtime/test configuration scoping, resolved-graph audits, version conflicts, and stable updates; use Included Builds when a build includes other builds via includeBuild or --include-build and you need to address their tasks or diagnose composite behavior; and use Research for version-aware official Gradle documentation, Gradle internals and lifecycle, and dependency, plugin, or JDK source research.

Cross-Skill Handoffs

• Structural Build Changes (plugins, repositories, modules, toolchains, publishing, CI, compiler options, testing frameworks) $\rightarrow$ authoring-gradle-builds.
• Runtime Logic Probing (JVM/Kotlin REPL) $\rightarrow$ interacting-with-project-runtime.
• UI Verification (Compose) $\rightarrow$ verifying-compose-ui.
• Advanced Dependency Engineering (variant-aware resolution diagnostics, dependency verification, component metadata rules, substitution/composite builds, dependency governance) $\rightarrow$ advanced-gradle-dependencies.

Workflows

Investigative Loop

1. Execute build/test via Running Builds.

2. Diagnose failures via Troubleshooting or Testing.

3. Inspect conflicts via Dependencies.

4. Read source via Research.

5. Identify missing/incorrect config using inspection tools.

6. If the change is a trivial dependency edit, update the version-catalog entry and library declaration in this skill, then verify resolution with inspect_dependencies.

7. If the change is structural (plugins, repositories, modules/subprojects, toolchains, publishing, CI, compiler options, or testing frameworks), follow the authoritative handoff in Constitution.

8. Verify the fix with a fresh build.

Everyday Dependency Edit

1. Update libs.versions.toml $\rightarrow$ 2. Update build.gradle.kts $\rightarrow$ 3. Verify via inspect_dependencies.