Kora V2

Kora Framework 2.0 — Meta-skill

Single entry point for all Kora 2.0 development. This file is routing and rules only — the implementation knowledge lives in the 39 sub-skills listed below.

This meta-skill is the single entry point for Kora Framework development. It routes to 39 specialized domain skills, each with its own narrow area of expertise.

Read this file first when:

• Starting a new Kora 2.0 microservice project from scratch (Java or Kotlin)
• Adding or refactoring a @KoraApp application graph with *Module interfaces
• Choosing which Kora modules to plug in (HTTP, Database, Kafka, gRPC, SOAP, S3, Telemetry)
• Debugging DI container issues ("dependency not found", ambiguous bindings, graph build failures)
• Configuring typed config with @ConfigSource / @ConfigMapper and environment substitution
• Planning a multi-module Gradle project with @KoraSubmodule boundaries
• Migrating an existing Kora 1.x service — see §6

1. Operating rules

Four rules. They apply to every Kora task, on every turn, from the first message. Each is stated once — here.

R0 is a gate: satisfy it before doing anything else. R1–R3 govern the work itself.

R0 — Ground the workspace before starting, on 2.0 refs

The upstream material is level 5 of the R1 chain and the final authority for every Kora question. It must be on disk before you begin, not fetched reactively once you are already stuck.

Kora 2.0 has no published documentation site of its own. The kora-docs repository documents Kora 1.x on every branch that currently exists, including feature/kora-2.0, whose docs/v2 directory is a byte-identical copy of the 1.x pages. Grounding on it would silently feed you ru.tinkoff.kora APIs. So for 2.0 the ground truth is the framework source at a 2.0 ref plus the migrated example applications, and nothing else.

Run this at the start of every Kora task. It is idempotent — it does nothing when the material is already present, so there is no cost to running it every time:

if [ ! -d .kora-agent/kora-source-2.0 ] || [ ! -d .kora-agent/kora-examples-2.0 ]; then
  mkdir -p .kora-agent
  [ -d .kora-agent/kora-source-2.0 ] \
    || git clone --depth 1 --branch 2.0.0.RC1 \
         https://github.com/kora-projects/kora.git .kora-agent/kora-source-2.0
  [ -d .kora-agent/kora-examples-2.0 ] \
    || git clone --depth 1 --branch migration/2.0 \
         https://github.com/kora-projects/kora-examples.git .kora-agent/kora-examples-2.0
  rm -rf .kora-agent/kora-source-2.0/.git .kora-agent/kora-examples-2.0/.git
  grep -qxF '.kora-agent/' .gitignore 2>/dev/null || echo '.kora-agent/' >> .gitignore
fi

Gate: .kora-agent/kora-source-2.0/ and .kora-agent/kora-examples-2.0/ both exist → proceed.

• Clone fails (no network, restricted environment) → say so explicitly and continue with sub-skills only. Never silently substitute recollection for the source you could not fetch.
• The service targets 2.0.0-SNAPSHOT rather than 2.0.0.RC1 → clone the framework at master instead, and say which ref you grounded on.
• The user declines the clone → note that level 5 is unavailable for this session, and flag any answer that would normally have been verified against it.

Recovery: started Kora work and only then noticed .kora-agent/ is missing → run the block now, then re-verify anything you already produced against it.

R1 — Route before you write

Resolve every Kora question through this chain, in order. Stop at the first level that answers it.

1. This file                        → pick the sub-skill
2. skills/<sub-skill>/SKILL.md      → the actual expertise, templates, scripts
3. skills/<sub-skill>/references/   → detailed patterns for that domain
4. kora-journal (search)            → known mistakes and fixes from past sessions
5. .kora-agent/kora-source-2.0/     → framework source: the final authority
   .kora-agent/kora-examples-2.0/   → working migrated applications

• Never write Kora code straight from memory. Open the sub-skill first.
• Never skip to level 5 because "it's a small change". Levels 2–3 hold the vetted patterns.
• Sub-skill and source disagree → source wins; fix the sub-skill and journal it (R3).
• Within level 5, framework source outranks the examples: an example can be behind, the source cannot.

Recovery: caught writing Kora code without having opened the sub-skill → stop, discard the draft, open the sub-skill, rewrite.

R2 — Kora only, and only what is asked

Kora is a self-contained framework with its own annotations, modules, and generated code.

• Never use Spring / Micronaut / Quarkus / Helidon annotations or idioms.
• Never invent a Kora annotation, class, or config key. If it is not in a sub-skill, a references/ file, or .kora-agent/, it does not exist — go verify it.
• Never carry a Kora 1.x API into 2.0 code. ru.tinkoff.kora.* does not exist in 2.0, and several 1.x names still compile while doing nothing (§4).
• Never add comments or Javadoc, unless the user asked for them or the logic is genuinely opaque (bit manipulation, encodings, cryptography, non-obvious protocol handling).
• Never mix paradigms for one target: OpenAPI-generated controller → implement its delegate, do not hand-write a parallel controller; Kora @HttpClient → do not also call the same service with a raw HTTP library.
• Always express behaviour through Kora's compile-time model — no reflection, no runtime proxies.

Recovery: a framework foreign to Kora slipped in → delete it, re-derive from the sub-skill, journal it (R3).

R3 — Journal incorrect Kora usage

When you realise — or the user tells you — that you used the Kora Framework incorrectly, record it. This is the feedback loop that improves the skills.

Entries are one file each, at ~/.kora-journal/<project>/<module>/<YYYY-MM-DD>_slug.md, shared across all projects and sessions. Full CLI and workflow: skills/kora-journal/SKILL.md.

Recovery: discovered a Kora mistake and moved on without an entry → add the entry now.

2. Per-task procedure

Follow these steps for every Kora request. Do not compress them.

0. Satisfy R0 — run the grounding block, confirm .kora-agent/ holds both 2.0 checkouts. Do not begin step 1 until this gate passes or you have told the user it cannot.
1. Classify the request against the routing tables in §3. More than one domain → handle them one at a time, in dependency order (project setup → config → DI → domain modules → telemetry → tests).
2. Read the sub-skill's SKILL.md end to end, then the references/ entries it points at for your case.
3. Search the journal before implementing anything non-trivial:

   # path is relative to this skill's own directory, not the project you are working in
   python3 skills/kora-journal/scripts/kora_journal.py search "http interceptor auth" --limit 5
   

   Hit → apply it, then mark it applied with integrate <entry-file>. Miss → continue, and expect to add an entry afterwards under R3.
4. Implement in the smallest increment that compiles — one annotation, method, or class at a time.
5. Compile — ./gradlew clean classes. Mandatory after any annotation change; the annotation processors, not the compiler, are what actually validate Kora code.
6. Test — write @KoraAppTest / Testcontainers coverage for real endpoints, queries, and messages, then ./gradlew test.
7. Verify the rules — R1 route followed, R2 no foreign framework, no 1.x API, no stray comments, R3 journal entry added for any Kora mistake made along the way.

Definition of done: it compiles, tests pass, no rule was violated, journal updated if applicable.

Compilation is necessary but not sufficient in Kora 2.0. Ports, interceptor tags, telemetry switches, circuit-breaker windows and mapper wiring all fail silently at runtime while the build stays green (§4). Anything in that list needs a test, not a successful build.

Build commands

3. Sub-skill routing

Read the matching sub-skill's SKILL.md before writing any code for that domain (R1).

Foundation — start here for new projects

Dependency injection

Database

R2DBC and Vert.x SQL were removed in Kora 2.0. There is no reactive database integration — JDBC on virtual threads is the only path.

Communication

Telemetry

In Kora 2.0 component metrics and logging are disabled by default — see §4.

AOP

Testing

Other

4. Architecture facts that drive decisions

• Everything is generated at compile time. DI → *ComponentImpl / *Graph, HTTP → *HttpRouter, AOP → *Aspect, JSON → *JsonReader / *JsonWriter, repositories → *RepositoryImpl, OpenAPI → *Delegate. No reflection, no dynamic proxies, no runtime scanning.

• The generated sources are the ground truth. When wiring or aspect behaviour is unclear, read them:

  • Java: build/generated/sources/annotationProcessor/
  • Kotlin: build/generated/ksp/ Never edit generated code as a fix — regenerate instead.

• Contracts are synchronous, executed on virtual threads. Reactive types (Mono/Flux) are gone framework-wide — there is no response mapper for Mono/Flux — and suspend repositories, controllers and HTTP clients are gone with them; the database KSP processor rejects suspend outright with "Suspend methods are not supported by the repository generator." Wrapping a Kora call in withContext(Dispatchers.IO) is now pointless overhead, and real parallelism moves to Java StructuredTaskScope.

  Async is not rejected everywhere, though, and what happens instead differs per generator — never diagnose from the one-line rule.

  Generator	Async shape	What happens
  @KafkaPublisher	Future/CompletionStage, + suspend/Deferred in Kotlin	first-class and awaited — do not "fix" it
  @KafkaListener	suspend, batch or key/value	accepted, wrapped in runBlocking — compiles, buys nothing
  @KafkaListener	suspend, single ConsumerRecord	does not compile — no such branch
  @KafkaListener	async return type	silently discarded — see the silent-failure table
  Cassandra repository	CompletionStage	accepted, Java only
  repositories, controllers, HTTP clients, scheduling, SOAP	any	rejected with a named error

  Two things apply to every Kotlin async path above: runBlocking runs to completion on the calling thread, so it buys no concurrency; and kotlinx-coroutines is a dependency of no Kora module, so generated code that uses it compiles only if your project supplies coroutines itself. Write a plain fun in listeners — because it is pointless, not because it is rejected. Two verified exceptions, both source-backed: Cassandra repositories still generate Java CompletionStage/CompletableFuture methods — CassandraRepositoryGenerator emits prepareAsync(...).thenCompose(...), and the migrated kora-java-database-cassandra example ships and tests one; the Kotlin side is synchronous there. Kafka publishers accept async return types in both languages — the Java generator branches on isFuture() || isCompletionStage(), the KSP one also on isSuspend() || isDeferred(), with a passing testReturnRecordMetadataSuspend and a shipped Future<RecordMetadata> sendMetaAsync(...) in kora-java-kafka. Do not "fix" either into a synchronous signature.

• Context no longer exists anywhere in the framework. A signature that threaded a Kora Context has to be rewritten, not mechanically patched.

• Nullability is JSpecify in Java (org.jspecify.annotations.Nullable) and the type in Kotlin (T?). JSpecify annotations are type-use: Outer.@Nullable Inner, List<@Nullable String>, String @Nullable []. Kora contracts are @NullMarked, so Kotlin overrides must match exactly — HttpServerResponseMapper<T>.apply(request, result: T?) with a non-null result fails as 'apply' overrides nothing, a message that never mentions nullability.

• Aspects need a non-final target. In Kotlin an AOP-annotated class and method must be open, otherwise the aspect is silently not generated.

Silent failures — green build, broken service

These are the Kora 2.0 traps that compile cleanly and fail only at runtime. Treat every one as a test case, never as something a successful build has proved.

Troubleshooting

5. Upstream sources

Availability of this material is R0, the gate in §1 — it is a precondition for starting work, not a step you reach once you need it.

Module-by-module map of the framework source, the migrated example apps, and the areas this plugin does not cover: references/kora-docs-map.md.

6. Coming from Kora 1.x

This plugin teaches and generates native Kora 2.0 code. It is not a migration tool.

• A project still on ru.tinkoff.kora should use the kora-v1 plugin, which is maintained separately and installs alongside this one.
• Migrating a real service is a semantic job, not a rename: typed resilient specifications, removed Context, synchronous contracts replacing suspend/reactive chains, JSpecify placement, the S3 redesign and the generated-OpenAPI adaptation all require decisions a search-and-replace cannot make. The upstream migration corpus lives at kora-examples migration/2.0 and is fetched by the R0 block above as part of .kora-agent/kora-examples-2.0/.
• Sub-skills flag 1.x APIs where a 2.0 agent is likely to reach for one by habit. Those notes exist to help you recognise and replace legacy input — never to justify emitting it.