[Build] Add Convention Plugin for Kotlin Multiplatform Module Setup

[dhiaspaner]

🧠 D: DOCUMENT — Problem & Opportunity

What is the problem, limitation, or opportunity? Why does this matter for SKaiNET?

Explain the context in clear terms:

• What functionality is missing or insufficient?

SKaiNET currently requires each multiplatform module to manually define its supported Kotlin Multiplatform targets and common Gradle configuration. This leads to duplicated build logic across modules and increases maintenance overhead when adding or changing supported platforms.

• Why is this important now?

As SKaiNET grows with more modules, maintaining platform configuration manually becomes error-prone. A convention plugin will reduce duplicated Gradle code, ensure all modules share the same multiplatform configuration, and simplify the process of creating new modules.

• Who benefits (users, developers, researchers)?

Developers contributing to SKaiNET benefit from a simpler module setup, fewer build configuration mistakes, and a more consistent project structure.

• What is the high-level goal of this proposal?

Create a reusable Gradle convention plugin that defines SKaiNET's standard Kotlin Multiplatform configuration, allowing modules to automatically inherit supported targets, compiler settings, dependencies, and common build conventions.

Summary (1–2 sentences):

Introduce a Kotlin Multiplatform convention plugin to centralize SKaiNET's module configuration. This will eliminate duplicated Gradle setup, improve consistency between modules, and make adding new modules faster and less error-prone.

---

🔍 A: ASSESS — Feasibility & Impact

✔️ Feasibility

• Is the feature straightforward to implement?

Yes. Gradle convention plugins are designed for this purpose and can encapsulate common build logic shared across multiple modules.

The implementation mainly requires:

• Creating a dedicated convention plugin module.

• Moving duplicated Kotlin Multiplatform configuration into the plugin.

• Applying the plugin to existing SKaiNET modules.

• Are there architectural constraints?

The plugin needs to remain flexible enough to support modules with different requirements. Not every module may need the exact same targets or dependencies, so the design should allow customization when necessary.

---

✔️ Expected Impact

• How does this improve SKaiNET?

It improves maintainability by:

• Removing duplicated Gradle configuration.

• Ensuring all modules use the same supported platform targets.

• Reducing configuration inconsistencies between modules.

• Making new module creation faster.

• Does it unlock new capabilities?

It enables easier scaling of the project by providing a foundation for adding new modules and supporting new platforms without repeating configuration work.

---

✔️ Risks / Constraints

• Technical challenges?

Potential challenges include:

• Designing the plugin API to support both common and module-specific configurations.

• Migrating existing modules without introducing build regressions.

• Handling modules that require additional platform-specific settings.

• Numerical stability concerns?

Not applicable. This change only affects build configuration.

• API consistency?

The convention plugin should provide a stable and predictable configuration interface to avoid forcing future modules into unnecessary constraints.

---

✔️ Dependencies

• Does this rely on an existing SKaiNET module?

It depends on the existing Kotlin Multiplatform Gradle structure used by SKaiNET modules.

• Does it require third-party libraries or standards?

No additional libraries are required. It relies on Gradle convention plugins and Kotlin Multiplatform Gradle APIs.

---

📚 R: RESEARCH — What Must Be Understood First?

Research Tasks

• Review existing SKaiNET modules and identify duplicated Gradle configurations.
• Identify which multiplatform targets are officially supported by SKaiNET.
• Compare Gradle convention plugin patterns used in large Kotlin Multiplatform projects.
• Define which configurations should be centralized versus customizable per module.
• Investigate best practices for Kotlin Multiplatform target management.

Open Questions

List unknowns that contributors should discuss or resolve.

• Should all modules automatically enable all SKaiNET-supported targets, or should modules opt into specific targets?
• How should modules override default configuration when they require special behavior?
• Should common dependencies and compiler options also move into the convention plugin?
• Should platform targets like wasmWasi be enabled globally or only for modules that support it?

---

🛠️ C: CODE — Implementation Plan

Development Tasks

• Create a new Gradle convention plugin module.
• Define the standard Kotlin Multiplatform target configuration.
• Move duplicated Gradle configuration from existing modules into the plugin.
• Apply the convention plugin to SKaiNET modules.
• Add support for module-specific customization when required.
• Verify existing modules build successfully after migration.
• Add documentation explaining how to create new SKaiNET modules.
• Add examples showing how modules use the convention plugin.
• Submit PR referencing this issue.

Acceptance Criteria

• New modules can use the convention plugin without manually configuring common multiplatform targets.
• Existing modules successfully migrate to the new configuration.
• Build configuration is centralized and consistent across modules.
• Documentation explains how contributors should use the plugin.
• No regressions are introduced in existing platforms.
• Reviewed and approved by maintainers.

---

💬 Additional Notes

The convention plugin should become the single source of truth for SKaiNET's Kotlin Multiplatform configuration.

Example:

Before:

kotlin {
androidTarget()
jvm()
iosArm64()
iosSimulatorArm64()
wasmWasi()
}
After:
plugins {
id("skainet.multiplatform")
}

[michalharakal]

Thanks for the really thorough write-up, @dhiaspaner — the DARC breakdown is excellent, and the problem is 100% real. A quick scan of the repo backs it up: 32 modules currently hand-roll their own kotlin { } target blocks, and the targets are far from uniform — jvm() appears in 28, iosArm64()/iosSimulatorArm64() in 24, js() in 20, and the native trio (macosArm64/linuxX64/linuxArm64) in 15. That spread is exactly the maintenance tax you're describing.

One important head start: we already have the plumbing for this. There's a build-logic included build with a convention project that ships working plugins today — sk.ainet.documentation, sk.ainet.transformers.bom-coverage, and sk.ainet.dokka. So this isn't greenfield: the cleanest path is to add a new convention plugin into the existing build-logic/convention module rather than standing up a new one. Two things to align with what's there:

• Naming: please follow the existing convention — sk.ainet.multiplatform (matching sk.ainet.*) rather than skainet.multiplatform.
• Look at the existing plugins first — BomCoveragePlugin/DocumentationPlugin are good templates for how we structure a binary convention plugin + extension here.

On your open questions, the target data above actually points to answers:

• Opt-in, not all-targets-global. Since targets are heterogeneous (only ~half the modules go native), a sk.ainet.multiplatform base that sets up jvm + the common config, plus opt-in toggles (e.g. an extension flag or companion plugins like sk.ainet.multiplatform.native / .wasm) will fit the repo better than forcing every module onto the full matrix.
• wasmWasi specifically should almost certainly be opt-in — very few modules need it, so enabling it globally would just add build cost and failure surface.
• Overrides: an extension (skainet { targets { ... } }) or simply letting modules add extra kotlin { } config after applying the plugin keeps it flexible.

Suggested first slice to keep the PR reviewable: land sk.ainet.multiplatform with the common config + jvm, migrate 2–3 representative modules (one jvm-only, one full-native) to prove both paths, and confirm no regressions before doing the bulk migration. Version-catalog and CI are already in place, so migration can be incremental.

This is a genuinely valuable cleanup — happy to review the design PR when you open it. 🚀