agentic-team-templates 0.13.2 → 0.14.0

package/templates/kotlin-expert/.cursorrules/performance.md

@@ -0,0 +1,185 @@
+# Kotlin Performance
+
+Profile first. Understand the JVM. Kotlin-specific optimizations matter.
+
+## Profile Before Optimizing
+
+```bash
+# JFR (Java Flight Recorder) — works with Kotlin on JVM
+java -XX:StartFlightRecording=filename=recording.jfr,duration=60s -jar app.jar
+
+# Kotlin-specific: check for unnecessary boxing, allocations
+# Use JMH for micro-benchmarks
+```
+
+## Inline Functions
+
+```kotlin
+// inline eliminates lambda allocation overhead — use for hot paths
+inline fun <T> measure(label: String, block: () -> T): T {
+    val start = System.nanoTime()
+    val result = block()
+    val elapsed = System.nanoTime() - start
+    logger.debug { "$label took ${elapsed / 1_000_000}ms" }
+    return result
+}
+
+// crossinline — prevent non-local returns in inlined lambdas
+inline fun transaction(crossinline block: () -> Unit) {
+    beginTransaction()
+    try {
+        block()
+        commit()
+    } catch (e: Exception) {
+        rollback()
+        throw e
+    }
+}
+
+// reified — preserve generic type info at runtime (only with inline)
+inline fun <reified T> parseJson(json: String): T {
+    return objectMapper.readValue(json, T::class.java)
+}
+
+// Rules:
+// - Inline small, frequently-called higher-order functions
+// - Don't inline large function bodies (code bloat)
+// - Standard library uses inline extensively: let, apply, also, run, with, map, filter
+```
+
+## Value Classes
+
+```kotlin
+// Zero overhead wrappers — no runtime allocation for the wrapper
+@JvmInline
+value class UserId(val value: String)
+
+@JvmInline
+value class Email(val value: String) {
+    init {
+        require(value.contains("@")) { "Invalid email" }
+    }
+}
+
+// At runtime, UserId("abc") is just the String "abc"
+// But at compile time, you can't pass UserId where Email is expected
+fun findUser(id: UserId): User // Type-safe, zero overhead
+```
+
+## Sequences vs Collections
+
+```kotlin
+// Collections: eager, creates intermediate lists
+val result = users
+    .filter { it.isActive }     // Creates List<User>
+    .map { it.name }            // Creates List<String>
+    .take(10)                   // Creates List<String>
+
+// Sequences: lazy, no intermediate allocations
+val result = users.asSequence()
+    .filter { it.isActive }     // No intermediate list
+    .map { it.name }            // No intermediate list
+    .take(10)                   // Stops after 10 matches
+    .toList()                   // Single terminal allocation
+
+// Use sequences when:
+// - Processing large collections (>1000 elements)
+// - Chaining multiple operations
+// - Using take/first (short-circuit)
+
+// Use collections when:
+// - Small datasets
+// - Single operation
+// - Need indexed access during processing
+```
+
+## Coroutine Performance
+
+```kotlin
+// Channel buffers for throughput
+val channel = Channel<Event>(capacity = 64) // Buffered, not unlimited
+
+// Fan-out for parallel processing
+val workers = List(Runtime.getRuntime().availableProcessors()) {
+    launch(Dispatchers.Default) {
+        for (item in channel) process(item)
+    }
+}
+
+// Avoid unnecessary suspension
+// Bad: wrapping non-suspending code in withContext
+suspend fun format(name: String): String = withContext(Dispatchers.Default) {
+    name.trim().lowercase() // This is instant — no need for withContext
+}
+
+// Good: only use withContext for actual blocking/CPU work
+suspend fun hashPassword(password: String): String = withContext(Dispatchers.Default) {
+    BCrypt.hashpw(password, BCrypt.gensalt()) // Actually CPU-intensive
+}
+```
+
+## Collection Optimization
+
+```kotlin
+// Pre-size collections
+val map = HashMap<String, User>(expectedSize)
+val list = ArrayList<User>(expectedSize)
+
+// buildList/buildMap — single allocation
+val items = buildList(expectedSize) {
+    for (item in source) {
+        if (item.isValid) add(transform(item))
+    }
+}
+
+// Use appropriate collection types
+val lookup = users.associateBy { it.id }     // HashMap for O(1) lookup
+val uniqueEmails = users.mapTo(HashSet()) { it.email } // HashSet for uniqueness
+val sorted = users.sortedBy { it.name }      // Single sort, not repeated
+
+// Avoid: repeated list.contains() — use a Set
+val activeIds = activeUsers.map { it.id }.toSet() // O(1) lookup
+orders.filter { it.userId in activeIds } // Fast membership test
+```
+
+## String Performance
+
+```kotlin
+// StringBuilder for complex concatenation
+val result = buildString {
+    for (item in items) {
+        append(item.name)
+        append(": ")
+        appendLine(item.value)
+    }
+}
+
+// joinToString for simple cases
+val csv = items.joinToString(",") { it.name }
+
+// String templates are efficient — Kotlin compiles them to StringBuilder
+val message = "User $name logged in from $ip" // Fine for most cases
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: premature optimization without profiling
+// "I think this allocation is slow" — prove it with JFR or JMH
+
+// Never: creating coroutines for non-suspending work
+launch { val x = 1 + 1 } // Overhead of coroutine machinery for nothing
+
+// Never: using reflection in hot paths
+val prop = User::class.memberProperties.find { it.name == "email" }
+// Use direct property access
+
+// Never: unnecessary boxing
+val numbers: List<Int> = listOf(1, 2, 3) // Boxed integers
+// For performance-critical code: IntArray(3) { it + 1 }
+
+// Never: mutable shared state in coroutines without synchronization
+var counter = 0
+repeat(1000) { launch { counter++ } } // Data race
+// Use: AtomicInteger, Mutex, or single-writer pattern
+```

package/templates/kotlin-expert/.cursorrules/testing.md

@@ -0,0 +1,213 @@
+# Kotlin Testing
+
+Test behavior with expressive assertions. Coroutines require special test infrastructure.
+
+## Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| JUnit 5 | Test framework |
+| Kotest | Kotlin-native testing (property-based, data-driven) |
+| MockK | Kotlin-native mocking |
+| kotlinx-coroutines-test | Coroutine testing |
+| Testcontainers | Real databases/services |
+| Ktor Test | HTTP endpoint testing |
+| ArchUnit | Architecture tests |
+
+## Unit Test Structure
+
+```kotlin
+class OrderServiceTest {
+
+    private val orderRepo = mockk<OrderRepository>()
+    private val inventoryClient = mockk<InventoryClient>()
+    private val sut = OrderService(orderRepo, inventoryClient)
+
+    @Test
+    fun `create with valid items returns success`() = runTest {
+        // Arrange
+        val request = CreateOrderRequest(
+            customerId = "customer-1",
+            items = listOf(OrderItemRequest("SKU-001", 2))
+        )
+        coEvery { inventoryClient.checkAvailability("SKU-001", 2) } returns true
+        coEvery { orderRepo.save(any()) } answers { firstArg() }
+
+        // Act
+        val result = sut.create(request)
+
+        // Assert
+        assertThat(result).isInstanceOf(Result.Success::class.java)
+        val order = (result as Result.Success).value
+        assertThat(order.customerId).isEqualTo("customer-1")
+        assertThat(order.items).hasSize(1)
+    }
+
+    @Test
+    fun `create with insufficient inventory returns failure`() = runTest {
+        val request = CreateOrderRequest(
+            customerId = "customer-1",
+            items = listOf(OrderItemRequest("SKU-001", 100))
+        )
+        coEvery { inventoryClient.checkAvailability("SKU-001", 100) } returns false
+
+        val result = sut.create(request)
+
+        assertThat(result).isInstanceOf(Result.Failure::class.java)
+        val error = (result as Result.Failure).error
+        assertThat(error).isInstanceOf(AppError.Validation::class.java)
+
+        coVerify(exactly = 0) { orderRepo.save(any()) }
+    }
+}
+```
+
+## Coroutine Testing
+
+```kotlin
+// runTest provides a TestScope with virtual time
+@Test
+fun `polling retries on failure`() = runTest {
+    var attempts = 0
+    coEvery { service.fetch() } answers {
+        attempts++
+        if (attempts < 3) throw IOException("Temporary failure")
+        else Data("success")
+    }
+
+    val result = sut.fetchWithRetry(maxRetries = 3)
+
+    assertThat(result.value).isEqualTo("success")
+    assertThat(attempts).isEqualTo(3)
+}
+
+// Testing flows
+@Test
+fun `user updates emit state changes`() = runTest {
+    val viewModel = UserViewModel(mockUserService)
+
+    viewModel.state.test {
+        assertThat(awaitItem()).isEqualTo(UiState.Loading)
+
+        viewModel.loadUser(UserId("123"))
+
+        assertThat(awaitItem()).isEqualTo(UiState.Loading)
+        assertThat(awaitItem()).isInstanceOf(UiState.Success::class.java)
+    }
+}
+
+// advanceTimeBy for testing delays
+@Test
+fun `cache expires after TTL`() = runTest {
+    cache.set("key", "value")
+
+    assertThat(cache.get("key")).isEqualTo("value")
+
+    advanceTimeBy(cacheTtl + 1.seconds)
+
+    assertThat(cache.get("key")).isNull()
+}
+```
+
+## MockK
+
+```kotlin
+// Suspend function mocking
+coEvery { userRepo.findById(any()) } returns User(id = "1", name = "Alice")
+coEvery { emailService.send(any(), any(), any()) } just Runs
+
+// Verification
+coVerify(exactly = 1) { emailService.send("alice@test.com", any(), any()) }
+coVerify(ordering = Ordering.ORDERED) {
+    userRepo.save(any())
+    emailService.send(any(), any(), any())
+}
+
+// Capturing
+val slot = slot<User>()
+coEvery { userRepo.save(capture(slot)) } answers { firstArg() }
+
+sut.create(request)
+
+assertThat(slot.captured.name).isEqualTo("Alice")
+
+// Relaxed mocks — return defaults for all unmocked calls
+val logger = mockk<Logger>(relaxed = true)
+```
+
+## Ktor Testing
+
+```kotlin
+class UserRoutesTest {
+
+    @Test
+    fun `POST users returns created for valid request`() = testApplication {
+        application {
+            configureRouting()
+            configureSerialization()
+        }
+
+        val response = client.post("/api/v1/users") {
+            contentType(ContentType.Application.Json)
+            setBody("""{"name": "Alice", "email": "alice@test.com"}""")
+        }
+
+        assertEquals(HttpStatusCode.Created, response.status)
+        val user = response.body<UserResponse>()
+        assertEquals("Alice", user.name)
+    }
+
+    @Test
+    fun `GET users id returns not found for missing user`() = testApplication {
+        application { configureRouting() }
+
+        val response = client.get("/api/v1/users/nonexistent")
+
+        assertEquals(HttpStatusCode.NotFound, response.status)
+    }
+}
+```
+
+## Data-Driven Tests (Kotest)
+
+```kotlin
+class SlugifyTest : FunSpec({
+    withData(
+        "Hello World" to "hello-world",
+        "  spaces  " to "spaces",
+        "Special!@#Chars" to "specialchars",
+        "" to "",
+    ) { (input, expected) ->
+        slugify(input) shouldBe expected
+    }
+})
+
+// Property-based testing
+class MoneyTest : FunSpec({
+    test("addition is commutative") {
+        checkAll(Arb.positiveLong(), Arb.positiveLong()) { a, b ->
+            Money(a, USD) + Money(b, USD) shouldBe Money(b, USD) + Money(a, USD)
+        }
+    }
+})
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: Thread.sleep in tests
+Thread.sleep(5000) // Flaky and slow
+// Use: runTest with advanceTimeBy, or Awaitility
+
+// Never: testing internal implementation
+verify { repo.save(any()) } // How, not what
+// Test the observable outcome instead
+
+// Never: shared mutable state between tests
+companion object { val testUsers = mutableListOf<User>() }
+// Use @BeforeEach to reset state
+
+// Never: ignoring coroutine test infrastructure
+@Test fun `test`() { runBlocking { sut.doWork() } }
+// Use: runTest { } for proper virtual time and dispatcher control
+```

package/templates/kotlin-expert/.cursorrules/tooling.md

@@ -0,0 +1,258 @@
+# Kotlin Tooling and Build System
+
+Gradle with Kotlin DSL. Static analysis. CI/CD. The full production pipeline.
+
+## Gradle (Kotlin DSL)
+
+```kotlin
+// build.gradle.kts
+plugins {
+    kotlin("jvm") version "2.1.0"
+    kotlin("plugin.serialization") version "2.1.0"
+    id("io.ktor.plugin") version "3.0.0" // For Ktor projects
+    id("io.gitlab.arturbosch.detekt") version "1.23.7"
+}
+
+kotlin {
+    jvmToolchain(21)
+    compilerOptions {
+        allWarningsAsErrors = true
+        freeCompilerArgs.addAll(
+            "-Xjsr305=strict",     // Strict null-safety for Java interop
+            "-Xcontext-receivers", // Enable context receivers (experimental)
+        )
+    }
+}
+
+dependencies {
+    // Ktor
+    implementation("io.ktor:ktor-server-core")
+    implementation("io.ktor:ktor-server-netty")
+    implementation("io.ktor:ktor-server-content-negotiation")
+    implementation("io.ktor:ktor-serialization-kotlinx-json")
+
+    // Coroutines
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core")
+
+    // DI
+    implementation("io.insert-koin:koin-ktor")
+
+    // Database
+    implementation("org.jetbrains.exposed:exposed-core")
+    implementation("org.jetbrains.exposed:exposed-jdbc")
+
+    // Testing
+    testImplementation(kotlin("test"))
+    testImplementation("io.ktor:ktor-server-test-host")
+    testImplementation("io.mockk:mockk")
+    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test")
+    testImplementation("org.testcontainers:postgresql")
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+```
+
+## Essential Commands
+
+```bash
+# Build and test
+./gradlew build                    # Full build + tests
+./gradlew test                     # Tests only
+./gradlew check                    # Tests + static analysis
+
+# Run
+./gradlew run                      # Run application
+./gradlew buildFatJar              # Ktor fat JAR
+
+# Dependencies
+./gradlew dependencies             # Dependency tree
+./gradlew dependencyUpdates        # Check for updates
+
+# Static analysis
+./gradlew detekt                   # Detekt analysis
+./gradlew ktlintCheck              # Code formatting check
+./gradlew ktlintFormat             # Auto-format
+```
+
+## Detekt (Static Analysis)
+
+```yaml
+# detekt.yml
+complexity:
+  LongMethod:
+    threshold: 30
+  ComplexCondition:
+    threshold: 4
+  TooManyFunctions:
+    thresholdInFiles: 20
+
+style:
+  ForbiddenComment:
+    values:
+      - "TODO:"
+      - "FIXME:"
+      - "HACK:"
+    allowedPatterns: "TODO\\(#\\d+\\)"  # Allow TODO with issue number
+  MagicNumber:
+    active: true
+    ignoreNumbers:
+      - "-1"
+      - "0"
+      - "1"
+      - "2"
+  MaxLineLength:
+    maxLineLength: 120
+
+exceptions:
+  TooGenericExceptionCaught:
+    active: true
+    exceptionNames:
+      - "Exception"
+      - "RuntimeException"
+      - "Throwable"
+```
+
+## kotlinx.serialization
+
+```kotlin
+// Type-safe serialization — no reflection
+@Serializable
+data class CreateUserRequest(
+    val name: String,
+    val email: String,
+    val role: UserRole = UserRole.USER
+)
+
+@Serializable
+enum class UserRole { USER, ADMIN, VIEWER }
+
+// Custom serializer
+@Serializable(with = InstantSerializer::class)
+data class Event(val name: String, val occurredAt: Instant)
+
+object InstantSerializer : KSerializer<Instant> {
+    override val descriptor = PrimitiveSerialDescriptor("Instant", PrimitiveKind.STRING)
+    override fun serialize(encoder: Encoder, value: Instant) = encoder.encodeString(value.toString())
+    override fun deserialize(decoder: Decoder): Instant = Instant.parse(decoder.decodeString())
+}
+```
+
+## Docker
+
+```dockerfile
+FROM gradle:8-jdk21 AS build
+WORKDIR /app
+COPY build.gradle.kts settings.gradle.kts ./
+COPY gradle/ gradle/
+RUN gradle dependencies --no-daemon
+
+COPY src/ src/
+RUN gradle buildFatJar --no-daemon
+
+FROM eclipse-temurin:21-jre-alpine
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+USER appuser
+WORKDIR /app
+COPY --from=build /app/build/libs/*-all.jar app.jar
+EXPOSE 8080
+
+ENV JAVA_OPTS="-XX:+UseContainerSupport \
+    -XX:MaxRAMPercentage=75.0 \
+    -XX:+UseZGC"
+
+ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - uses: gradle/actions/setup-gradle@v4
+
+      - name: Build and test
+        run: ./gradlew check
+        env:
+          DATABASE_URL: jdbc:postgresql://localhost:5432/testdb
+
+      - name: Detekt
+        run: ./gradlew detekt
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: build/reports/tests/
+```
+
+## Logging
+
+```kotlin
+// kotlin-logging (SLF4J wrapper)
+import io.github.oshai.kotlinlogging.KotlinLogging
+
+private val logger = KotlinLogging.logger {}
+
+// Lazy evaluation — message not constructed if level is disabled
+logger.info { "Processing order ${order.id} with ${order.items.size} items" }
+logger.error(exception) { "Failed to process order ${order.id}" }
+
+// MDC for request context
+MDC.put("requestId", requestId)
+MDC.put("userId", userId)
+try {
+    processRequest()
+} finally {
+    MDC.clear()
+}
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: build.gradle (Groovy) for Kotlin projects
+// Use: build.gradle.kts (Kotlin DSL) — type-safe, IDE support
+
+// Never: skipping detekt in CI
+// Static analysis catches real bugs and code smells
+
+// Never: Jackson for Kotlin (use kotlinx.serialization)
+// Jackson requires reflection and kotlin-module. kotlinx.serialization is compile-time.
+
+// Never: JUnit 4 assertions
+assertEquals(expected, actual) // No message, confusing order
+// Use: assertThat(actual).isEqualTo(expected) // AssertJ, readable
+
+// Never: hardcoded versions scattered across modules
+// Use: version catalogs (gradle/libs.versions.toml)
+```