While building Ready Together, I kept seeing the same risk: an agent could make a plausible Kotlin Multiplatform change quickly, but another session could not always explain why the code belonged in that source set, which decision had been approved, or what had actually been verified on Android and iOS.
The problem was not code generation. It was continuity. KMP features cross several boundaries at once: shared rules, platform integrations, serialized contracts, persistence, backend authority, degraded connectivity, and two different release pipelines. A short prompt can produce code. It cannot be durable project memory.
I needed a workflow that kept my engineering judgment in the loop while giving agents enough structure to work independently. The result is now a public repository: SOSMex/kmp-spec-driven-skills.
The failure mode: fast code, weak boundaries
In a multiplatform codebase, a locally reasonable shortcut can create a long-term inconsistency. A domain rule can drift into an Android host. A transport DTO can become the business model. An unknown contract value can become an optimistic default. One convenient Gradle task can pass and quietly become a claim of cross-platform parity.
The same confusion happens in the planning artifacts. A feature specification, an RFC, and an ADR answer different questions. If every change gets all three, the process turns into ceremony. If risky synchronization, privacy, billing, or compatibility choices get none of them, the decision lives only in a conversation that the next contributor cannot audit.
Skill one: design before tasks
kmp-spec-driven-design begins after a product outcome is understood and before implementation tasks are written. It first discovers the repository’s actual modules, targets, source sets, contracts, tests, and instructions. It does not assume that every KMP project looks like Ready Together.
The skill then makes four decisions explicit: the smallest vertical slice, the correct source-set or module owner, the degraded and compatibility states, and the evidence that will be required later. It also includes a decision router for choosing the lightest responsible artifact.
Clear, local, and reversible
Use a bounded task, implementation, focused verification, and a reviewable handoff.
Normal product behavior
Define user behavior, degraded states, boundaries, tasks, and target-aware evidence.
A risky proposal needs agreement
Use it for realtime, auth, privacy, billing, persistence, compatibility, or costly dependencies.
A durable choice was accepted
Record the decision and trade-offs after agreement; do not use an ADR as a task list.
Skill two: prove parity without inflating it
kmp-proof-of-parity starts from the claims a change is making. It traces the affected shared logic, platform adapters, backend behavior, and UI surfaces, then discovers the real Gradle tasks, Xcode schemes, CI jobs, emulators, simulators, and devices available in that repository.
Its most important output is not a green check. It is an evidence matrix. Each behavior and target receives the strongest status that the evidence supports: Compiled, Automated-tested, Emulator-tested, Physically-tested, Store-submitted, or Released.
Those labels are deliberately separate. Shared JVM tests do not prove iOS runtime behavior. An Android emulator does not close a physical Android–iPhone flow. Uploading a build does not mean it is released. The skill is designed to make the remaining gate visible instead of smoothing it over with an adjective.
Where I remain in the loop
The skills do not hand product ownership to an agent. I still define the outcome, challenge scope, approve risky proposals, accept durable decisions, and decide whether the evidence is sufficient for a public claim. Agents can inspect, draft, implement, test, and report. The repository preserves the handoff between those responsibilities.
This is especially important for KMP because “shared” is not the same as “identical.” I want deterministic product meaning to live in the broadest valid shared source set, while native lifecycle, accessibility, notifications, deep links, secure storage, and store work remain honest platform boundaries.
What the repository includes
The first tagged release contains the two skills, concise architecture and RFC/ADR references, templates for specs through handoffs, three worked examples, eight evaluation scenarios, and a deterministic validator for metadata, local links, structure, release assets, placeholders, and common secret patterns.
npx skills add SOSMex/kmp-spec-driven-skills \
+ --skill kmp-spec-driven-design \
+ --skill kmp-proof-of-parityIt is intentionally not a Gradle plugin or a full application generator. I want the workflow to become useful and testable before turning it into more tooling. Contributions can add a reproducible failure mode, a clearer decision boundary, or a stronger parity check without adopting Ready Together’s private code or product constraints.
Where does your team most often lose confidence in a KMP change: architecture placement, decision history, or proof that both platforms behave as intended?
Please share a workflow failure mode rather than private project code or credentials.