po4yka/RIPDPI / .agents/skills/convention-plugin-development
convention-plugin-development
VerifiedAuthor or modify a build-logic convention plugin. Use when changing plugin internals, the diagnostics catalog, or Rust-native wiring. Not for adding a dependency/module (gradle-build-system) or version bumps (dependency-update).
1. Plugin Architecture
Included Build Pattern
The project uses Gradle's included build (includeBuild) to isolate build logic
from the main build. The root settings.gradle.kts includes build-logic/ which itself
is a standalone Gradle project.
build-logic/
settings.gradle.kts -- declares :convention subproject, creates "libs" catalog
convention/
build.gradle.kts -- applies kotlin-dsl, declares compileOnly AGP/plugin deps
src/main/kotlin/ -- all precompiled script plugins and helper classes
build-logic/settings.gradle.kts creates a version catalog named libs pointing at the
root gradle/libs.versions.toml. This gives convention plugins access to the same version
catalog used by application modules.
How Plugins Are Registered
Every *.gradle.kts file under src/main/kotlin/ becomes a precompiled script plugin
whose ID is the filename minus the .gradle.kts suffix. For example,
ripdpi.android.library.gradle.kts registers as plugin ID ripdpi.android.library.
No gradlePlugin {} block or META-INF descriptor is needed -- the kotlin-dsl plugin
handles registration automatically.
Dependency Declaration
build-logic/convention/build.gradle.kts declares external Gradle plugins as
compileOnly dependencies so their extension types are available at compile time:
- AGP (
com.android.tools.build:gradle) - Kotlin Compose compiler plugin
- Hilt, KSP, detekt, ktlint, roborazzi
The kotlinx-serialization-json library is an implementation dependency because the
diagnostics catalog renderer uses it at task execution time.
2. Plugin Inventory
| Plugin ID | File | Purpose |
|---|---|---|
ripdpi.android.application | ripdpi.android.application.gradle.kts | Configures AGP application module: compileSdk, minSdk, targetSdk, R8/ProGuard, artifact naming (AAB), JVM 17 |
ripdpi.android.library | ripdpi.android.library.gradle.kts | Configures AGP library module: compileSdk, minSdk, consumer ProGuard rules, JVM 17 |
ripdpi.android.native | ripdpi.android.native.gradle.kts | Sets NDK version, ABI filters, jniLibs packaging policy. Applied by both application and library plugins |
ripdpi.android.rust-native | ripdpi.android.rust-native.gradle.kts | Cross-compiles Rust workspace into Android .so files via Cargo. Parallel per-ABI builds. See section 4 |
ripdpi.android.compose | ripdpi.android.compose.gradle.kts | Enables Compose, sets stability config, optional metrics/reports on CI |
ripdpi.android.hilt | ripdpi.android.hilt.gradle.kts | Applies Hilt + KSP, adds hilt-android and hilt-compiler dependencies |
ripdpi.android.serialization | ripdpi.android.serialization.gradle.kts | Applies kotlin.plugin.serialization (one-liner) |
ripdpi.android.protobuf | ripdpi.android.protobuf.gradle.kts | Runs protoc directly (no protobuf Gradle plugin). Detects host OS/arch, wires generated Java sources into AGP variants |
ripdpi.android.quality | ripdpi.android.quality.gradle.kts | Aggregator: applies detekt + ktlint + lint |
ripdpi.android.detekt | ripdpi.android.detekt.gradle.kts | Configures detekt: parallel, custom rules from :quality:detekt-rules, compose rules, baseline support |
ripdpi.android.ktlint | ripdpi.android.ktlint.gradle.kts | Configures ktlint: version pin, Android mode, excludes build/generated |
ripdpi.android.lint | ripdpi.android.lint.gradle.kts | Configures Android Lint: abortOnError, baseline, html+xml reports |
ripdpi.android.coverage | ripdpi.android.coverage.gradle.kts | Delegates to jacoco plugin (one-liner) |
ripdpi.android.jacoco | ripdpi.android.jacoco.gradle.kts | JaCoCo setup: excludes generated/Hilt/proto classes, registers jacocoDebugUnitTestReport task |
ripdpi.android.roborazzi | ripdpi.android.roborazzi.gradle.kts | Screenshot testing: enables Android resources in unit tests, sets output dir to src/test/screenshots |
ripdpi.diagnostics.catalog | ripdpi.diagnostics.catalog.gradle.kts | Registers generateDiagnosticsCatalog and checkDiagnosticsCatalog tasks. See section 3 |
ripdpi.android.test | ripdpi.android.test.gradle.kts | Configures com.android.test modules (currently :baselineprofile); wires the shared Gradle Managed Device registry |
Helper Kotlin Files (not plugins)
| File | Purpose |
|---|---|
NativeBuildPolicy.kt | Utility functions: resolvedNativeAbis(), resolvedNativeCargoProfile(), resolveAndroidSdkDir(), resolveRustTool(), CI/release detection |
DiagnosticsCatalogAssembler.kt | Orchestrates pack loading, profile loading, validation, JSON rendering |
DiagnosticsCatalogDefinitions.kt | Singleton entry point wiring the assembler with default sources |
DiagnosticsCatalogDomain.kt | Domain model: DiagnosticsCatalog, TargetPackDefinition, DiagnosticsProfileDefinition, enums |
DiagnosticsCatalogDpiData.kt | DPI-profile target data (domains, TCP targets, whitelist SNI) consumed by DefaultDiagnosticsCatalogProfileSource |
DefaultDiagnosticsCatalogPackSource.kt | DefaultDiagnosticsCatalogPackSource -- builds target pack list |
DefaultDiagnosticsCatalogProfileSource.kt | DefaultDiagnosticsCatalogProfileSource -- builds profile list referencing packs |
DiagnosticsCatalogRendering.kt | DiagnosticsCatalogJsonRenderer and DiagnosticsCatalogValidator -- serializes to JSON, validates pack refs and versions |
DiagnosticsCatalogSharedData.kt | Shared constants (common domains, DNS servers) reused across packs |
DiagnosticsCatalogSupport.kt | Helper functions for building domain/DNS/TCP target lists |
3. Diagnostics Catalog Generator
The catalog defines target packs (groups of network endpoints) and profiles
(scan configurations referencing packs). It is checked into the repo as a JSON asset at
core/diagnostics/src/main/assets/diagnostics/default_profiles.json.
Data Flow
DiagnosticsCatalogPackSourcebuildsList<TargetPackDefinition>from typed Kotlin dataDiagnosticsCatalogProfileSourcebuildsList<DiagnosticsProfileDefinition>, resolving pack refsDiagnosticsCatalogValidatorchecks for duplicate IDs and verifies everypackRefpoints to a real pack with matching versionDiagnosticsCatalogJsonRendererserializes to pretty-printed JSON using kotlinx.serializationDiagnosticsCatalogAssemblerorchestrates steps 1-4
Tasks
generateDiagnosticsCatalog-- writes the JSON to the asset path. Run manually after changing data.checkDiagnosticsCatalog-- runs duringcheck, fails if the committed file differs from what would be generated. This prevents stale catalogs from shipping.
Both tasks use DiagnosticsCatalogGeneratedAt (a date constant in DiagnosticsCatalogDomain.kt)
as an @Input to force re-execution when the generation date changes.
Adding a New Target Pack or Profile
The catalog's content (packs, profiles, and how to add them) is owned by the diagnostics-system skill; this skill covers only the generator plumbing above.
4. Rust-Native Plugin
ripdpi.android.rust-native.gradle.kts is the largest and most volatile convention plugin: it cross-compiles the Rust workspace into Android .so libraries, the root-helper executable, naive-proxy and Cloudflare-origin binaries, and pluggable-transport assets.
- Two task classes do the work:
BuildRustNativeLibsTask(Cargo-built artifact groups --.solibraries, root-helper, naive-proxy, Cloudflare-origin) andBuildPluggableTransportAssetsTask(assets built fromnative/pluggable-transports/sources.json). Both are@CacheableTask. - Artifact groups are declared as pipe-delimited
"<cargo-package>|<cargo-output>|<output-name>"triples in separaterustNativeArtifactSpecs,rustRootHelperArtifactSpecs,rustNaiveProxyArtifactSpecs, andrustCloudflareOriginArtifactSpecslists near the bottom of the plugin file. Read them directly before changing or reasoning about which artifacts get built -- this set changes independently of the skill and is not reproduced here.
For the Cargo invocation sequence, ABI-to-target-triple mapping, profile selection, task wiring into AGP's packaging pipeline, and cache-input tracking, read references/rust-native.md.
5. Adding a New Convention Plugin
Step-by-Step
- Create
build-logic/convention/src/main/kotlin/ripdpi.<category>.<name>.gradle.kts - If the plugin applies an external Gradle plugin, add its artifact as a
compileOnlydependency inbuild-logic/convention/build.gradle.ktsusing thelibs.plugins.<id>.map { ... }pattern - Write the plugin body. Access shared properties via
providers.gradleProperty("ripdpi.<property>") - Apply the plugin in consuming modules:
id("ripdpi.<category>.<name>") - Verify with
./gradlew :app:help(or whichever module applies it) to confirm resolution
Naming Convention
ripdpi.android.*-- plugins that configure Android modules (AGP extensions, Kotlin, quality tools)ripdpi.diagnostics.*-- plugins for the diagnostics subsystem- Use dots as separators. The filename IS the plugin ID.
Helper Classes
Place reusable Kotlin code in plain .kt files alongside the plugins (not inside a
package). These files are compiled into the same classpath and are directly accessible
from any precompiled script plugin in the module.
6. Common Pitfalls
Configuration Cache Compatibility
The project enables org.gradle.configuration-cache=true. Every plugin must be
configuration-cache safe:
- Do not capture
Projectreferences in task actions. Use@Input/@InputFileproperties. - Use
providers.gradleProperty()instead of reading properties eagerly at configuration time. - Task classes that call
ExecOperationsmust inject it via@Inject constructor.
AGP API Compatibility
- Use
extensions.configure<ApplicationExtension>(the DSL type), not the internalBaseAppModuleExtension. Internal types break across AGP upgrades. - For variant-aware wiring, use
ApplicationAndroidComponentsExtensionorLibraryAndroidComponentsExtensionwithonVariants {}. - The protobuf plugin uses
variant.sources.java?.addGeneratedSourceDirectory()to wire generated sources -- this is the modern AGP variant API approach.
Included Build Quirks
- Version catalog access in
build.gradle.ktsuseslibs.versions.<name>andlibs.plugins.<name>. Inside precompiled script plugins, usethe<VersionCatalogsExtension>().named("libs")orversionCatalogs.named("libs"). - Changes to
build-logic/sources require a Gradle sync in the IDE. Gradle does not auto-detect included build source changes in all cases. - The
kotlin-dslplugin implicitly appliesjava-gradle-pluginandkotlin("jvm"). Do not apply them again.
Baseline Policy
Per project rules (CLAUDE.md): never extend detekt baselines, lint baselines, or LoC baselines to suppress new violations. Fix the underlying issue. Baselines exist only for legacy debt.
Rust-Native Cache Misses
If the Rust build runs unexpectedly, or skips when a rebuild was expected:
- Every Rust-native task's
@InputFilestracks the wholenative/rust/crates/tree,Cargo.lock,rust-toolchain.toml,.cargo/, andvendor/automatically -- there is no manually maintained per-crate allowlist to fall out of sync. Seereferences/rust-native.mdfor the exact input set. - Check if
Cargo.lockchanged (a dependency update triggers a rebuild). - Verify the profile selection logic -- local dev should use
android-jni-dev.
Protobuf Plugin
The project deliberately avoids the protobuf-gradle-plugin and instead uses a custom
GenerateProtoLiteSourcesTask that downloads protoc as a detached configuration and
runs it directly. This avoids version conflicts and configuration-cache issues with the
official plugin.
See Also
gradle-build-systemskill -- everyday dependency/module lookups and build-failure triage; start there before this deeper reference.dependency-updateskill -- version-catalog and cross-ecosystem (Gradle + Cargo) update workflows.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |