Guides

Starter Project Templates

Kolt ships two ready-to-build project templates — one for Android-only projects and one for Kotlin Multiplatform. Use the CLI bootstrap script or the IntelliJ plugin wizard to generate a new project in seconds.

Two ways to bootstrap

🖥️ CLI Script (recommended)

Run scripts/new-project.sh from the UtilsLibs repo with flags or in interactive mode. Works anywhere — CI, local machine, Makefile.

🔌 IntelliJ / Android Studio Plugin

A GUI wizard inside the IDE. Same templates, same output — no terminal required. See the IntelliJ Plugin guide for setup.

CLI bootstrap script

The script lives at scripts/new-project.sh in the UtilsLibs repo root. It copies the relevant template, substitutes your project name and package, initialises the Gradle wrapper, and opens the directory.

# Android-only project (non-interactive)
./scripts/new-project.sh --type android --name MyApp --package com.example.myapp

# KMP project (non-interactive)
./scripts/new-project.sh --type kmp --name MyApp --package com.example.myapp

# Fully interactive — prompts for all values
./scripts/new-project.sh

Then do your first build to let Kolt scaffold theme resources and steering docs:

cd MyApp
./gradlew :app:assembleDebug   # scaffolds theme XMLs on the first run

Template types

The templates live under project-templates/templates/ in the repo:

android-project

A single-module Android project with a convention plugin applied. Use this when you are building an Android-only app.

MyApp/
  settings.gradle.kts           ← koltlibs catalog imported, :app included
  build.gradle.kts              ← plugins block (apply false)
  gradle.properties             ← AndroidX + POM metadata defaults
  gradlew + gradle/wrapper/
  app/
    build.gradle.kts            ← alias(koltlibs.plugins.kolt.application)
    src/main/
      kotlin/com/example/myapp/ ← empty package placeholder
      res/                      ← (theme XMLs scaffolded on first build)
  CLAUDE.md                     ← fill in project facts (Claude reads this)
  AGENTS.md                     ← fill in project facts (Gemini reads this)
  docs/
    CODING_STANDARDS.md
    ARCHITECTURE.md
    TESTING.md
    KOLT.md

kmp-project

A multi-module KMP project with an Android host app and a shared KMP module. Use this when targeting Android + iOS (and optionally Desktop or WASM).

MyApp/
  settings.gradle.kts           ← koltlibs + kmplibs catalogs, :app + :shared included
  build.gradle.kts
  gradle.properties
  gradlew + gradle/wrapper/
  app/
    build.gradle.kts            ← alias(kmplibs.plugins.kolt.kmp.application)
    src/main/kotlin/com/example/myapp/
    src/main/res/               ← (theme XMLs scaffolded on first build)
  shared/
    build.gradle.kts            ← alias(kmplibs.plugins.kolt.kmp.library.koin.compose)
    src/
      commonMain/kotlin/com/example/myapp/
      androidMain/kotlin/com/example/myapp/
      iosMain/kotlin/com/example/myapp/
  CLAUDE.md
  AGENTS.md
  docs/
    CODING_STANDARDS.md
    ARCHITECTURE.md
    TESTING.md
    KOLT.md

What the docs/ files are

Every generated project includes a docs/ folder with four AI-agent steering files. These are plugin-owned: whenever the consumer project upgrades the Kolt plugin, running any build re-fetches the latest versions automatically.

File	Purpose	When an agent loads it
`CODING_STANDARDS.md`	Binding coding rules — Clean + MVI + SOLID + stateless Compose	Every coding task
`ARCHITECTURE.md`	Layering, DI strategy, offline-first data layer, Android/KMP deltas	When designing or restructuring
`TESTING.md`	Test patterns, reducer/use-case fakes, Turbine, coverage targets	When writing tests
`KOLT.md`	Plugin catalog, DSL options, library APIs, catalog aliases, scaffolding	When using or configuring the Kolt suite

The CLAUDE.md and AGENTS.md files are project-owned: the plugin only writes them once (when absent) and never overwrites them, so your team can fill in project-specific facts freely.

Updating docs/ in an existing project

To refresh the plugin-owned docs to the latest version after a Kolt plugin upgrade, run:

./gradlew scaffoldKoltDocs

This is also triggered automatically on the first build after a plugin version change. It is safe to re-run — CLAUDE.md and AGENTS.md are never touched.

Similarly, to re-generate Compose theme XML resources:

./gradlew scaffoldKoltResources

How templates stay in sync

The canonical template source lives at project-templates/ in this repo. At plugin build time, a generateSteeringTemplates Gradle task copies all template files into the plugin JAR as classpath resources. Both the CLI script and the IntelliJ plugin wizard read from this same source — there is no duplication.

Manual copy (no script needed)

You can also copy a template folder directly if you prefer not to run the script:

# Android project
cp -r project-templates/templates/android-project/ ../MyNewApp
./Standards/scripts/link-standards.sh android ../MyNewApp

# KMP project
cp -r project-templates/templates/kmp-project/ ../MyNewApp
./Standards/scripts/link-standards.sh kmp ../MyNewApp

🔌