android-setup

Android Project Setup

Correct project initialization prevents 80% of downstream agent errors. Read this entire skill before writing any build files.

Non-negotiables

• Kotlin DSL only (build.gradle.kts, settings.gradle.kts) — never Groovy .gradle
• Version Catalog only (libs.versions.toml) — never hardcode versions in build files
• KSP only — never kapt
• minSdk = 24, targetSdk = 35, compileSdk = 35
• Kotlin 2.0.0+, AGP 8.5.0+
• namespace declared in every module's build.gradle.kts

Project Structure

my-app/
├── app/
│   ├── src/main/
│   │   ├── java/com/company/app/
│   │   │   ├── MainActivity.kt
│   │   │   └── MyApplication.kt
│   │   ├── res/
│   │   └── AndroidManifest.xml
│   └── build.gradle.kts
├── core/
│   ├── data/
│   ├── domain/
│   └── ui/
├── feature/
│   └── <feature-name>/
├── gradle/
│   └── libs.versions.toml       ← ALL versions live here
├── build.gradle.kts              ← root, no dependencies
├── settings.gradle.kts
└── gradle.properties

settings.gradle.kts

pluginManagement {
    repositories {
        google { content { includeGroupByRegex("com\\.android.*"); includeGroupByRegex("com\\.google.*"); includeGroupByRegex("androidx.*") } }
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "MyApp"
include(":app")
// include(":core:data")  // add modules as needed

Root build.gradle.kts

// Top-level build file. Do NOT add dependencies here.
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.android.library) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.ksp) apply false
    alias(libs.plugins.hilt) apply false
}