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.
• Before you start, prioritize structured problems. When diagnosing a FAILED build or a low-signal error, call query_build(kind="PROBLEMS") BEFORE reading build files; PROBLEMS returns identifiers, severity, documentation, occurrence details, and potential solutions. Start file inspection only when structured problems do not resolve the diagnosis.
• Handoff: Route structural build edits, compiler-option configuration, and testing-framework configuration to authoring-gradle-builds; see Cross-Skill Handoffs.