rnett/gradle-mcp/authoring-gradle-builds

Gradle Build Authoring

Author or modify Gradle build definitions, build logic, project structure, and delivery wiring. Optimize for lazy, decoupled, configuration-cache-compatible builds.

Positive Triggers (when to activate)

• Authoring or modifying build.gradle(.kts), settings.gradle(.kts), convention plugins, modules, or subprojects.
• Adding or changing dependency declarations, version catalogs, repositories, or plugin management.
• Configuring JDK toolchains, Kotlin compiler options, test frameworks, publishing, or CI wiring.
• Declaring or modifying composite builds (included builds via includeBuild, build-logic wiring).
• Creating custom tasks, worker actions, build services, value sources, service injection, or project-isolation-compatible build logic.
• Assessing build health, running best-practice audits, or handling Gradle doctor / build health check / performance audit requests.
• Modifying advanced Gradle configuration and build performance settings.

Negative Triggers (when NOT to activate)

• Operation/execution (running builds, running tests, diagnosing failures, and read-only dependency inspection/update discovery) belongs to using-gradle; authoring/modifying build definitions (including dependency declarations and version catalogs) belongs to authoring-gradle-builds. Trivial one-line everyday dependency edits (catalog entry + declaration + version bump) are a sanctioned overlap in using-gradle; anything structural (plugins, repositories, modules, toolchains, publishing, CI) is authoring-gradle-builds only.
• Researching internal Gradle APIs (use using-gradle's research workflow).
• Probing runtime project code (use interacting-with-project-runtime).
• Verifying Compose UI (use verifying-compose-ui).
• Advanced dependency engineering — variant-aware resolution diagnostics, dependency verification implementation (verification-metadata.xml authoring, PGP key and checksum workflows, verification repair, and CI verification workflows), component metadata rules, dependency substitution rules and composite-build diagnosis, capability conflicts, lock modes beyond basics, advanced version catalogs, and repository governance modes (use advanced-gradle-dependencies). Composite-build authoring stays here. Basic dependency declaration, version-catalog basics, and basic locking stay here.

More info: Search the User Guide with gradle_docs(query="tag:userguide <term>") or best practices with gradle_docs(query="tag:best-practices <term>"). Read gradle/wrapper/gradle-wrapper.properties before any version-sensitive authoring.

Before You Modify

1. Read gradle/wrapper/gradle-wrapper.properties; identify the wrapper version.
2. Consult the compatibility quick-reference below; verify version-sensitive claims with gradle_docs(query="tag:userguide <term>").
3. When the change is version-sensitive (wrapper upgrade, API migration, deprecation fix), consult the upgrading page for the wrapper's major version via gradle_docs(path="userguide/upgrading_version_<N>.md") and check gradle_docs(query="tag:release-notes") for breaking changes. See Upgrading and Release Notes.
4. Read settings.gradle.kts, gradle/libs.versions.toml, applied plugins, and convention plugins. Check for existing conventions before proposing changes.
5. Load the narrowest authored reference: links in the directives and workflows above are loaded in context; for the remaining actions, use the Decision Routing table.
6. Treat references/best-practices/_index.md and its corpus detail as optional rationale, consulted on demand rather than as a mandatory pre-load.

Compatibility Quick-Reference

Constitution

• Prefer Kotlin DSL for new authoring (gradle_docs(path="userguide/best_practices_general.md"); use Groovy only when the project requires it).
• Register lazily: use Custom Tasks, tasks.register, tasks.named, and configureEach, not eager tasks.create (gradle_docs(path="userguide/task_configuration_avoidance.md")).
• Use version catalogs when present; centralize versions and aliases (gradle_docs(path="userguide/best_practices_dependencies.md"); catalogs are stable from 7.4).
• Check existing conventions first; use declarative plugins {} and settings pluginManagement {} (gradle_docs(path="userguide/plugins.md"), gradle_docs(path="userguide/best_practices_structuring_builds.md")).
• Never use allprojects or subprojects; apply explicit Convention Plugins and keep projects decoupled (gradle_docs(path="userguide/best_practices_structuring_builds.md"), gradle_docs(path="userguide/isolated_projects.md")).
• Never use Project or Task.project inside task actions; inject Advanced Configuration services and model task inputs (gradle_docs(path="userguide/configuration_cache_requirements.md"), gradle_docs(path="userguide/service_injection.md")).
• Never resolve configurations in the configuration phase; resolve through task inputs or task execution (gradle_docs(path="userguide/best_practices_tasks.md")).
• Do not call Provider.get() while configuring unrelated work; wire Managed Types and Providers with Provider and Property values lazily (gradle_docs(path="userguide/properties_providers.md"), gradle_docs(path="userguide/best_practices_tasks.md")).
• Prohibit afterEvaluate; use providers, pluginManager.withPlugin, and lazy APIs. Permit it only for a documented correctness-critical ordering constraint, with an afterEvaluate-justification: comment (gradle_docs(path="userguide/best_practices_general.md")).

Always-Loaded Best-Practice Footguns

These compact rules are loaded before any authoring reference. Links provide detailed rationale or, where available, the corpus detail; use the linked reference for the procedural guidance.

• Model initialization, configuration, and execution separately. Phase boundaries are easy to blur, and the resulting ordering and performance bugs are often silent. See Build Lifecycle.
• Keep expensive work out of configuration. Unselected tasks still pay configuration-time costs, which makes this mistake hard to spot from a successful build. See Build Lifecycle.
• Use configuration avoidance throughout the model. Eager APIs look harmless but silently realize tasks and domain objects before they are needed. See Custom Tasks.
• Propagate laziness with providers and managed properties. Provider-looking values can still be realized too early, losing provenance and cache inputs. See Managed Types and Providers.
• Read providers only at an execution boundary. Configuration-time reads can work in simple builds while breaking laziness or cache behavior in larger ones. See Custom Tasks.
• Use provider-backed managed model types. Ad hoc mutable fields hide validation, lifecycle, and caching semantics that Gradle must observe. See Managed Types and Providers.
• Use public APIs and injected services only. Internal types often appear convenient until an upgrade exposes an undocumented compatibility break. See Advanced Configuration.
• Wire cross-project behavior through model relationships. Callback-based mutation depends on evaluation order and becomes hostile to project isolation. See Convention Plugins.
• Avoid `afterEvaluate` and `projectsEvaluated` as configuration mechanisms (version-sensitive). Their timing can appear to repair ordering while masking a model relationship that should be explicit; read the wrapper first. See Build Lifecycle.
• Distinguish `set(null)` from an absent provider. Both represent "no value" at a glance, but only one lets a convention apply. See Managed Types and Providers.
• Never resolve or iterate at configuration time. Configuration-phase resolution, iteration, or eager file-tree walking realizes values early and breaks laziness, the configuration cache, and project isolation. See File Operations and Managed Types and Providers.
• Do not capture realized files or `Project`. Retaining an eager File/Path or the Project object freezes values that must stay lazy and is incompatible with the configuration cache and isolated projects. See File Operations.
• Prefer provider wiring over declaration copying. Connect task and extension properties with providers (set(...), from(...), map/flatMap) so changes propagate without re-realizing values. See Managed Types and Providers.

Decision Routing