Record 033: Gradle Standards Skill

Status

Done

Problem

Currently, there's no comprehensive guidance for Gradle build configuration using Kotlin DSL. While standards-java provides basic Gradle snippets, developers need deeper knowledge for:

1. Project Configuration: Setting up build scripts, managing dependencies, configuring plugins, multi-module projects
2. Plugin/Task Development: Writing custom Gradle plugins and tasks for build automation

Gradle Kotlin DSL (.gradle.kts) is now the modern standard, offering type safety and better IDE support compared to Groovy DSL. However, developers often:

• Struggle with Kotlin DSL syntax differences from Groovy
• Don't know Gradle best practices (dependency management, plugin application, task configuration)
• Need guidance on structuring custom plugins and tasks
• Miss opportunities to leverage Gradle's powerful features

Why solve this?

• Gradle is the build tool for Java/Kotlin projects (especially Android, Kotlin Multiplatform)
• Kotlin DSL is now the recommended approach, but documentation often shows Groovy
• Custom plugins/tasks are common for build automation, but patterns aren't well documented
• Having coding standards for build scripts improves project maintainability

What if we do nothing?

• Developers continue using inconsistent Gradle patterns
• Build scripts remain hard to understand and maintain
• Opportunities for build automation (custom tasks) are missed
• New projects might default to Groovy DSL instead of Kotlin DSL

Scope: This will be a comprehensive skill (~1000-1200 lines), similar in depth to standards-java. It covers both everyday project configuration and advanced plugin development patterns.

Options Considered

Option A: Two Major Sections (Recommended)

Structure:

• Section 1: Project Configuration (70% of content)

  • Build script basics (build.gradle.kts, settings.gradle.kts)
  • Dependency management (configurations, version catalogs)
  • Plugin application and configuration
  • Multi-module projects
  • Gradle 9 features

• Section 2: Plugin/Task Development (30% of content)

  • Custom task creation with proper input/output handling
  • Extension API (configurable plugins)
  • Providers API (lazy configuration)
  • Gradle caching (build cache and configuration cache)
  • Custom plugin development patterns
  • Build logic reuse (buildSrc, convention plugins)

Groovy DSL Coverage:

• Kotlin DSL throughout the skill
• Dedicated "Groovy → Kotlin Migration" section at end
• Common patterns and their equivalents

Auto-loading:

applies_to: [gradle]

• Loads when editing .gradle.kts or .gradle files
• Complements standards-java and standards-kotlin

Pros:

• Clear separation: configuration users vs plugin authors
• Progressive disclosure: most developers need Section 1 only
• Comprehensive coverage of Gradle 9 modern APIs
• Plugin section covers critical concepts (providers, caching, extensions)

Cons:

• Plugin development section substantial (but necessary)
• Might be a large skill file

Option B: Three Separate Sections

Structure:

• Section 1: Essential Configuration
• Section 2: Advanced Configuration (multi-module, custom configurations)
• Section 3: Plugin/Task Development

Pros:

• More granular learning path

Cons:

• Harder to navigate
• Arbitrary split between "essential" and "advanced"
• Over-engineered for a standards skill

Option C: Integrated Approach

Structure:

• Mix configuration and customization throughout
• Each topic shows both usage and extension

Pros:

• Shows full Gradle power

Cons:

• Confusing for developers who just want to configure dependencies
• Doesn't match typical usage patterns

Decision

Option A - Two major sections with expanded plugin development coverage.

Rationale:

• Matches how developers use Gradle: most configure projects, some build plugins
• Plugin section comprehensive enough to cover modern Gradle APIs (providers, caching, extensions)
• Clear structure makes it easy to find relevant information
• Gradle 9 focus ensures modern best practices
• Groovy migration guide helps teams transitioning from legacy projects

Solution

Create a comprehensive Gradle standards skill based on Gradle 9 LTS with Kotlin DSL as the primary syntax.

Skill Metadata

name: standards-gradle
description: Gradle build tool standards focusing on Kotlin DSL. Covers project configuration, dependency management, and custom plugin/task development.
type: context
applies_to: [gradle]

Content Structure

# Gradle Coding Standards (Gradle 9 LTS)

## Core Principles
- Declarative over imperative
- Type-safe configuration (Kotlin DSL)
- Lazy configuration (Providers API)
- Build cache-friendly tasks
- Configuration cache compatible

## Section 1: Project Configuration (~70% of content)

### Build Script Basics
- `build.gradle.kts` structure and organization
- `settings.gradle.kts` for multi-module projects
- Plugin application (plugins {} block)
- Repository configuration (mavenCentral, etc.)

### Dependency Management
- Dependency configurations (implementation, api, compileOnly, runtimeOnly)
- Version catalogs (libs.versions.toml) - Gradle's modern approach
- Dependency constraints and platform/BOM dependencies
- Excluding transitive dependencies

### Plugin Configuration
- Applying plugins: id() vs apply()
- Configuring plugin extensions
- Common plugins: java, kotlin-jvm, application
- Plugin versions and version catalogs integration

### Multi-Module Projects
- Project structure conventions
- Shared configuration via convention plugins
- Dependency management across modules
- buildSrc vs included builds vs composite builds

### Gradle 9 Features
- Latest LTS improvements
- Performance enhancements
- New APIs and deprecations

## Section 2: Plugin/Task Development (~30% of content)

### Custom Tasks
- Registering vs creating tasks (lazy vs eager)
- Task inputs and outputs (proper annotations for up-to-date checks)
- Task dependencies, ordering (dependsOn, finalizedBy)
- Abstract task classes with Property<T>

### Extension API
- Creating extensions for configurable plugins
- Extension properties using Property<T>
- Nested extensions for complex configuration
- Extension best practices

### Providers API
- Lazy configuration with Provider<T>
- Property<T> for mutable properties (task inputs)
- Connecting providers (map, flatMap, zip)
- Avoiding eager configuration anti-patterns

### Gradle Caching
- **Build cache**: Task output caching, cache keys
- **Configuration cache**: Build graph caching, compatibility requirements
- Writing cache-compatible tasks (avoid mutable state)
- Cache debugging and troubleshooting

### Custom Plugins
- Plugin implementation patterns (Plugin<Project>)
- Precompiled script plugins in buildSrc
- Convention plugins for shared configuration
- Composite builds for plugin development

### Build Logic Reuse
- buildSrc directory structure
- Included builds for modular build logic
- Convention plugins across projects
- Publishing plugins to repositories

## Groovy → Kotlin DSL Migration Guide

- Syntax differences (assignment vs =, strings, etc.)
- Plugin application conversion
- Dependency declaration differences
- Common patterns and idioms
- Configuration block conversions

Integration Points

1. Auto-loading: Skill loads when editing .gradle.kts files (Kotlin DSL focus)
2. Groovy DSL files: For .gradle files, skill provides migration guide to Kotlin DSL; primary content is Kotlin-focused
3. Complements: Works alongside standards-java and standards-kotlin
4. Framework-agnostic: Pure Gradle concepts, no Spring Boot/Android specifics
5. Version baseline: All examples assume Gradle 9 LTS
6. Version strategy: Update in place for minor Gradle versions; evaluate new skill for major versions (e.g., Gradle 10+)

Content Tone

• Practical examples with BAD/GOOD patterns
• Focus on modern APIs (providers, lazy configuration)
• Emphasize build performance (caching, configuration cache)
• Clear migration guidance from Groovy DSL

User Stories

Story 1: Create Skill File and Core Structure

As a developer I want the basic standards-gradle skill file with metadata and structure So that the skill can be loaded and the sections are ready for content

Acceptance Criteria:

• Create skills/standards-gradle/SKILL.md
• Add frontmatter: name, description, type, applies_to
• Add all section headers (Core Principles, Section 1 headings, Section 2 headings, Migration Guide)
• Add brief placeholder text for each section
• Skill file validates (proper YAML frontmatter)

Priority: High Status: Done

Story 1.5: Create Test Gradle Project

As a developer writing the skill I want a test Gradle project to validate code examples So that all code snippets in the skill are tested and valid

Acceptance Criteria:

• Create test Gradle project in skills/standards-gradle/test-project/
• Project uses Gradle 9 LTS (9.3.1)
• Includes build.gradle.kts and settings.gradle.kts
• Can run gradle tasks successfully
• Includes examples for: dependencies, plugins, custom tasks, extensions
• README.md explains how to validate skill code snippets
• All code from skill can be copy-pasted and executed in test project

Priority: High Status: Done

Story 2: Write Section 1 - Project Configuration

As a developer configuring Gradle projects I want comprehensive guidance on Kotlin DSL build configuration So that I can set up projects following best practices

Acceptance Criteria:

• Build Script Basics section complete with examples
• Dependency Management section with version catalogs
• Plugin Configuration section with plugins {} block
• Multi-Module Projects section with convention plugins
• Gradle 9 Features section with modern APIs
• All examples use Kotlin DSL (.gradle.kts)
• BAD/GOOD pattern examples throughout
• Code examples are tested and valid (validated in test project from Story 1.5)
• Examples verified against Gradle 9 official documentation for accuracy

Priority: High Status: Done

Story 3: Write Section 2 - Plugin/Task Development

As a developer building custom Gradle plugins I want guidance on modern Gradle APIs (providers, caching, extensions) So that I can write performant, cache-compatible build logic

Acceptance Criteria:

• Custom Tasks section with lazy registration, input/output annotations
• Extension API section with Property<T> examples
• Providers API section with lazy configuration patterns
• Gradle Caching section covering build cache AND configuration cache
• Custom Plugins section with Plugin<Project> implementation
• Build Logic Reuse section (buildSrc, convention plugins)
• All examples demonstrate cache-compatible patterns
• Provider API anti-patterns (eager configuration) shown as BAD examples
• Include working example of cache-compatible custom task (not just snippets)
• Examples verified against Gradle 9 official documentation for accuracy

Priority: High Status: Done

Story 4: Add Groovy → Kotlin DSL Migration Guide

As a developer maintaining Groovy DSL projects I want a conversion guide to migrate to Kotlin DSL So that I can modernize existing build scripts

Acceptance Criteria:

• Syntax differences table (assignment, strings, etc.)
• Plugin application conversion examples
• Dependency declaration conversion
• Configuration block conversion patterns
• Common idioms (buildscript {}, allprojects {})
• Side-by-side comparison examples
• Include common migration gotchas and pitfalls (e.g., string literals, delegate syntax, kotlin vs "kotlin" in versions)

Priority: Medium Status: Done

Story 5: Add E2E Test for Skill Loading

As a maintainer I want automated tests for the standards-gradle skill So that skill loading and integration are validated

Acceptance Criteria:

• Create test scenario in tests/scenarios/
• Test: Skill loads when editing .gradle.kts file
• Test: Skill metadata is valid
• Test: applies_to triggers correctly
• Test: Verify skill behavior with .gradle (Groovy) files (primary focus is Kotlin DSL)
• Test passes in CI (GitHub Actions)

Priority: Medium Status: Done

Story 6: Update Documentation and Version

As a user I want documentation reflecting the new skill So that I know standards-gradle is available and how to use it

Acceptance Criteria:

• Bump content version in templates/VERSION
• Add entry to CHANGELOG.md
• Update README.md badge (content version)
• Update project CLAUDE.md Current Status table
• Add skill to global CLAUDE.md skills table if needed
• Update documentation site (website/pages/features/skills/)
• Document relationship between standards-gradle, standards-java, and standards-kotlin (when to use which)

Priority: Low Status: Done

Test Coverage and Validation

What IS Tested in test-project

The test project (skills/standards-gradle/test-project/) validates these patterns with runnable code:

✅ Fully Validated:

• Plugin application (plugins {} block)
• Repository configuration
• Dependency management with version catalogs (gradle/libs.versions.toml)
• Java toolchain configuration
• Task registration (lazy vs eager)
• Custom tasks with input/output annotations
• Cacheable tasks (@CacheableTask annotation)
• Custom plugins in buildSrc
• Extension API (ExamplePlugin with ExamplePluginExtension)
• Convention plugins (java-conventions.gradle.kts)
• Provider API usage (Property<T>, Provider<T>)
• Task dependencies (dependsOn, mustRunAfter)

What is Illustrative (Not Directly Tested)

Some examples in the skill are illustrative patterns that demonstrate concepts but aren't executed in the test project:

⚠️ Illustrative Examples:

• Multi-module project structure (test project is single module)
• Remote repository authentication (requires actual credentials)
• Dependency constraints and BOM usage (conceptual examples)
• Remote build cache configuration (requires remote server)
• Build services (example shows pattern, not full implementation)
• Composite builds (requires multiple separate projects)
• Provider transformations (map, flatMap, zip - shown but not extensively tested)
• Configuration cache issues (anti-patterns documented but not executed)

E2E Test Validation

The E2E test (tests/scenarios/17-standards-gradle.sh) validates:

1. ✅ Skill metadata and structure
2. ✅ Required sections present
3. ✅ Installation via installer
4. ✅ Test project actually builds (./gradlew build)
5. ✅ Custom tasks execute (./gradlew exampleTask)
6. ✅ Cacheable task works (./gradlew cacheableTask)
7. ✅ Version catalog resolves (./gradlew dependencies)

Critical Fixes Applied

Based on critical review, the following issues were fixed:

Critical Fixes:

1. ✅ Fixed @CacheableTask annotation pattern (was incorrectly showing nested annotation class)
2. ✅ Added working cacheable task to test project with proper @CacheableTask usage
3. ✅ Fixed ServiceReference example (replaced non-existent @ServiceReference with correct build service pattern)
4. ✅ Fixed convention plugin example (added explanation of plugin ID auto-generation)

Quality Improvements: 5. ✅ Added version catalog usage to test project (was only commented out) 6. ✅ Added build validation to E2E test (ensures examples compile) 7. ✅ Added BAD examples for Extension API and Build Services 8. ✅ Updated test project README with cache validation instructions 9. ✅ Documented test coverage limitations (this section)

Content Completion: 10. ✅ Added Gradle Build Phases section (init/config/execution phases) - Location: After "Build Script Basics" (line 154) - Content: ~500 lines explaining lifecycle, when code runs, common mistakes - Includes: Phase examples, anti-patterns, debugging, full lifecycle demo - Impact: Completes understanding of lazy evaluation and configuration cache

Skill Size

• Total lines: 3,843 (larger than originally planned 1000-1200)
• Section 1 (Project Config): ~60% of content
• Section 2 (Plugin/Task Dev): ~30% of content
• Migration Guide: ~10% of content

Decision: Accept the larger size given the comprehensive coverage needed. The skill is well-structured with clear section boundaries, making it navigable despite the length.

Validation Against Official Gradle Documentation

All examples cross-referenced with:

• Gradle 9.3 User Guide
• Kotlin DSL Primer
• Custom Tasks Guide
• Custom Plugins Guide
• Build Cache Guide
• Configuration Cache Guide

Result: Examples match official patterns and use correct Gradle 9 APIs.