Ship more than one Kotlin Multiplatform app on the same stack and the shared parts quietly drift: the same TOAD presentation runtime, the same Compose design language, the same ktlint rules and Gradle conventions, duplicated and slowly diverging. rhaydus-foundation is the single, versioned home for everything they share, so a fix or an improvement lands once and every consuming app inherits it.

It ships three things most "shared module" repos don't bother to keep together:

• 📦 KMP libraries: consumed as a git submodule through includeBuild, opt-in by concern.
• 🧰 Build + style tooling: Gradle convention plugins, a shared version catalog file, and a custom ktlint ruleset.
• 🤖 Claude Code assets: a plugin of specialist agents, a skill, and a docs index, so an AI assistant working in a consuming app knows what's available and is steered to actually use it.

• Gradle convention plugins (build-logic/): rhaydus.android.library, rhaydus.kmp.library, rhaydus.android.compose, rhaydus.kmp.compose, for uniform module setup (SDK/JDK levels, the Android+iOS mobileMain seam, the test stack, Compose).
• Canonical conventions docs (docs/): see CAPABILITIES.md (the index of everything available), plus architecture, TOAD, code-style, and design-system foundations.

graph LR
  editorial["designsystem-editorial<br/><i>editorial language</i>"] --> core["designsystem-core<br/><i>neutral skeleton</i>"]
  image["designsystem-image<br/><i>async images</i>"] --> core
  image -. brings .-> coil["Coil"]
  toad["toad<br/><i>presentation runtime</i>"]
  offline["offline-sync<br/><i>optimistic write queue</i>"] --> platform["core-platform<br/><i>platform seams</i>"]
  platform --> common["core-common<br/><i>non-visual primitives</i>"]

An app that wants a different look depends on designsystem-core alone and never pulls the editorial language or Coil; the opinionated layers are opt-in by design.

git submodule add https://github.com/CinqueIzumi/rhaydus-foundation.git foundation
git -C foundation checkout v0.4.0

// settings.gradle.kts
includeBuild("foundation")

// build.gradle.kts
dependencies {
    implementation("nl.rhaydus:toad")
    implementation("nl.rhaydus:designsystem-core")
    implementation("nl.rhaydus:designsystem-editorial") // opt-in
    implementation("nl.rhaydus:designsystem-image")     // opt-in (pulls Coil)
}

Gradle substitutes the nl.rhaydus:* coordinates for the submodule source, so the catalog entries carry no version. The app builds on the same AGP and Kotlin versions as the pinned foundation. CI checkouts that run Gradle set submodules: true, and clones use --recurse-submodules. Nothing is published: the submodule is the only way to consume the foundation.

// settings.gradle.kts
pluginManagement {
    includeBuild("foundation/build-logic")
}

dependencyResolutionManagement {
    versionCatalogs {
        create("rhaydus") { from(files("foundation/gradle/libs.versions.toml")) }
    }
}

Edit foundation/ on a branch; the app builds the change directly, with no version bump. Commit in the foundation first, then record the new pointer in the app with git add foundation. A foundation version change moves the pointer: fetch in foundation/, check out the new tag, git add foundation, commit.

Add this to the project's .claude/settings.json, or run rhaydus-adopt:

{
  "extraKnownMarketplaces": {
    "rhaydus": { "source": { "source": "directory", "path": "./foundation" } }
  },
  "enabledPlugins": { "rhaydus-kotlin@rhaydus": true }
}

Each machine then registers it once, from the project root:

claude plugin marketplace add ./foundation --scope project
claude plugin install rhaydus-kotlin@rhaydus --scope project

The first command writes an absolute path into .claude/settings.json; set it back to ./foundation before committing. The plugin loads in place from the pinned submodule. Claude Code caches it per version, so an edit to it applies only after reinstalling it; see the plugin README.

The rhaydus-kotlin plugin makes a consuming app's AI assistant fluent in the foundation. It ships:

Every agent reads CAPABILITIES.md first, so it reuses what already exists and stays correct for the exact version a project is pinned to, rather than working from a memorized snapshot.

One version covers the whole release: foundation.version in gradle.properties is the version of every foundation module, and a verifyPluginVersion build gate locks the Claude plugin's version to it (the build fails if they drift). Bump them together. A v* tag is only a git marker for the commit consumers pin their submodule to.

./gradlew build   # compile all targets (jvm/android/ios) + tests + gates

A release: bump foundation.version in gradle.properties and the version in plugin.json together, merge, and tag vX.Y.Z. Consumers then fetch in foundation/, check out the tag and git add foundation.

A 0.x release: the public API may still change between minor versions before 1.0, so pin a version when you depend on it. Every release builds on all targets (Android / iOS / Desktop) and is verified against a sample consumer before it ships.

MIT © CinqueIzumi