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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.2 KB |
| references/rust-native.md | markdown | 3.7 KB |
SKILL.md
View on GitHub---
name: convention-plugin-development
description: Author 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
1. `DiagnosticsCatalogPackSource` builds `List<TargetPackDefinition>` from typed Kotlin data
2. `DiagnosticsCatalogProfileSource` builds `List<DiagnosticsProfileDefinition>`, resolving pack refs
3. `DiagnosticsCatalogValidator` checks for duplicate IDs and verifies every `packRef` points to a real pack with matching version
4. `DiagnosticsCatalogJsonRenderer` serializes to pretty-printed JSON using kotlinx.serialization
5. `DiagnosticsCatalogAssembler` orchestrates steps 1-4
### Tasks
- `generateDiagnosticsCatalog` -- writes the JSON to the asset path. Run manually after changing data.
- `checkDiagnosticsCatalog` -- runs during `check`, 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 -- `.so` libraries, root-helper, naive-proxy, Cloudflare-origin) and `BuildPluggableTransportAssetsTask` (assets built from `native/pluggable-transports/sources.json`). Both are `@CacheableTask`.
- Artifact groups are declared as pipe-delimited `"<cargo-package>|<cargo-output>|<output-name>"` triples in separate `rustNativeArtifactSpecs`, `rustRootHelperArtifactSpecs`, `rustNaiveProxyArtifactSpecs`, and `rustCloudflareOriginArtifactSpecs` lists 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
1. Create `build-logic/convention/src/main/kotlin/ripdpi.<category>.<name>.gradle.kts`
2. If the plugin applies an external Gradle plugin, add its artifact as a `compileOnly`
dependency in `build-logic/convention/build.gradle.kts` using the `libs.plugins.<id>.map { ... }` pattern
3. Write the plugin body. Access shared properties via `providers.gradleProperty("ripdpi.<property>")`
4. Apply the plugin in consuming modules: `id("ripdpi.<category>.<name>")`
5. 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 `Project` references in task actions. Use `@Input`/`@InputFile` properties.
- Use `providers.gradleProperty()` instead of reading properties eagerly at configuration time.
- Task classes that call `ExecOperations` must inject it via `@Inject constructor`.
### AGP API Compatibility
- Use `extensions.configure<ApplicationExtension>` (the DSL type), not the internal
`BaseAppModuleExtension`. Internal types break across AGP upgrades.
- For variant-aware wiring, use `ApplicationAndroidComponentsExtension` or
`LibraryAndroidComponentsExtension` with `onVariants {}`.
- 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.kts` uses `libs.versions.<name>` and
`libs.plugins.<name>`. Inside precompiled script plugins, use
`the<VersionCatalogsExtension>().named("libs")` or `versionCatalogs.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-dsl` plugin implicitly applies `java-gradle-plugin` and
`kotlin("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:
1. Every Rust-native task's `@InputFiles` tracks the whole `native/rust/crates/` tree, `Cargo.lock`, `rust-toolchain.toml`, `.cargo/`, and `vendor/` automatically -- there is no manually maintained per-crate allowlist to fall out of sync. See `references/rust-native.md` for the exact input set.
2. Check if `Cargo.lock` changed (a dependency update triggers a rebuild).
3. 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-system` skill -- everyday dependency/module lookups and build-failure triage; start there before this deeper reference.
- `dependency-update` skill -- 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: 198k | 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: 194k | 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: 194k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |