agentic-team-templates 0.13.2 → 0.15.0

package/templates/kotlin-expert/.cursorrules/error-handling.md

@@ -0,0 +1,149 @@
+# Kotlin Error Handling
+
+Sealed types for expected failures. Exceptions for exceptional conditions. Never swallow errors.
+
+## Sealed Result Types
+
+```kotlin
+// Model expected outcomes explicitly
+sealed interface Result<out T> {
+    data class Success<T>(val value: T) : Result<T>
+    data class Failure(val error: AppError) : Result<Nothing>
+}
+
+sealed interface AppError {
+    data class NotFound(val entity: String, val id: String) : AppError
+    data class Validation(val errors: Map<String, String>) : AppError
+    data class Conflict(val message: String) : AppError
+    data class Unauthorized(val reason: String) : AppError
+}
+
+// Usage in services
+class UserService(private val userRepo: UserRepository) {
+    suspend fun register(request: CreateUserRequest): Result<User> {
+        val errors = validate(request)
+        if (errors.isNotEmpty()) {
+            return Result.Failure(AppError.Validation(errors))
+        }
+
+        val existing = userRepo.findByEmail(request.email)
+        if (existing != null) {
+            return Result.Failure(AppError.Conflict("Email already registered"))
+        }
+
+        val user = userRepo.create(request)
+        return Result.Success(user)
+    }
+}
+
+// Handling in routes/controllers
+when (val result = userService.register(request)) {
+    is Result.Success -> call.respond(HttpStatusCode.Created, result.value)
+    is Result.Failure -> when (result.error) {
+        is AppError.Validation -> call.respond(HttpStatusCode.BadRequest, result.error)
+        is AppError.Conflict -> call.respond(HttpStatusCode.Conflict, result.error)
+        is AppError.NotFound -> call.respond(HttpStatusCode.NotFound, result.error)
+        is AppError.Unauthorized -> call.respond(HttpStatusCode.Unauthorized, result.error)
+    }
+}
+```
+
+## kotlin.Result and runCatching
+
+```kotlin
+// For wrapping operations that might throw
+val result: kotlin.Result<User> = runCatching {
+    userRepository.findById(id)
+}
+
+result
+    .onSuccess { user -> logger.info("Found user: ${user.id}") }
+    .onFailure { error -> logger.error("Failed to find user", error) }
+
+val user = result.getOrNull()
+val userOrDefault = result.getOrDefault(User.anonymous())
+val userOrElse = result.getOrElse { error ->
+    logger.warn("Falling back to anonymous", error)
+    User.anonymous()
+}
+
+// Chaining
+val displayName = runCatching { fetchUser(id) }
+    .map { it.displayName }
+    .getOrDefault("Unknown User")
+```
+
+## Validation
+
+```kotlin
+// require — preconditions (throws IllegalArgumentException)
+fun createOrder(customerId: String, items: List<OrderItem>) {
+    require(customerId.isNotBlank()) { "customerId must not be blank" }
+    require(items.isNotEmpty()) { "Order must have at least one item" }
+    require(items.size <= MAX_ITEMS) { "Maximum $MAX_ITEMS items allowed" }
+}
+
+// check — state invariants (throws IllegalStateException)
+fun ship(order: Order) {
+    check(order.status == OrderStatus.PAID) { "Can only ship paid orders" }
+    check(order.items.isNotEmpty()) { "Cannot ship empty order" }
+}
+
+// requireNotNull / checkNotNull
+val user = requireNotNull(userRepo.findById(id)) {
+    "User $id must exist after authentication"
+}
+```
+
+## Exception Best Practices
+
+```kotlin
+// Custom exceptions for domain boundaries
+class OrderProcessingException(
+    val orderId: OrderId,
+    message: String,
+    cause: Throwable? = null
+) : RuntimeException(message, cause)
+
+// Catch specific exceptions
+try {
+    paymentService.charge(order)
+} catch (e: PaymentDeclinedException) {
+    logger.warn("Payment declined for order ${order.id}", e)
+    return Result.Failure(AppError.PaymentDeclined(e.reason))
+} catch (e: PaymentTimeoutException) {
+    logger.error("Payment timeout for order ${order.id}", e)
+    throw OrderProcessingException(order.id, "Payment timed out", e)
+}
+
+// Never catch Exception broadly without rethrowing CancellationException
+try {
+    suspendingOperation()
+} catch (e: CancellationException) {
+    throw e // Always rethrow — coroutine cancellation must propagate
+} catch (e: Exception) {
+    logger.error("Operation failed", e)
+}
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: empty catch blocks
+try { riskyOperation() }
+catch (e: Exception) { } // Silently swallowed
+
+// Never: catch Throwable (catches OutOfMemoryError, StackOverflowError)
+try { work() }
+catch (e: Throwable) { } // Too broad
+// Use: catch (e: Exception) at most
+
+// Never: using exceptions for control flow
+try { return items.first { it.isActive } }
+catch (e: NoSuchElementException) { return null }
+// Use: items.firstOrNull { it.isActive }
+
+// Never: wrapping without context
+catch (e: Exception) { throw RuntimeException(e) }
+// Add context: throw OrderProcessingException(orderId, "Failed to process", e)
+```

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

@@ -0,0 +1,227 @@
+# Kotlin Frameworks
+
+Ktor for Kotlin-first, Spring Boot for ecosystem breadth. Both done idiomatically.
+
+## Ktor
+
+```kotlin
+fun main() {
+    embeddedServer(Netty, port = 8080) {
+        configureRouting()
+        configureSerialization()
+        configureAuthentication()
+    }.start(wait = true)
+}
+
+// Routing
+fun Application.configureRouting() {
+    routing {
+        route("/api/v1") {
+            userRoutes()
+            orderRoutes()
+        }
+    }
+}
+
+fun Route.userRoutes() {
+    route("/users") {
+        get {
+            val users = userService.findAll()
+            call.respond(users)
+        }
+
+        get("/{id}") {
+            val id = UserId(call.parameters["id"]
+                ?: return@get call.respond(HttpStatusCode.BadRequest, "Missing id"))
+
+            when (val result = userService.findById(id)) {
+                is Result.Success -> call.respond(result.value)
+                is Result.Failure -> when (result.error) {
+                    is AppError.NotFound -> call.respond(HttpStatusCode.NotFound)
+                    else -> call.respond(HttpStatusCode.InternalServerError)
+                }
+            }
+        }
+
+        post {
+            val request = call.receive<CreateUserRequest>()
+            when (val result = userService.create(request)) {
+                is Result.Success -> call.respond(HttpStatusCode.Created, result.value)
+                is Result.Failure -> call.respond(HttpStatusCode.BadRequest, result.error)
+            }
+        }
+    }
+}
+
+// Content negotiation
+fun Application.configureSerialization() {
+    install(ContentNegotiation) {
+        json(Json {
+            prettyPrint = false
+            ignoreUnknownKeys = true
+            encodeDefaults = true
+            isLenient = false
+        })
+    }
+}
+```
+
+## Spring Boot with Kotlin
+
+```kotlin
+@SpringBootApplication
+class Application
+
+fun main(args: Array<String>) {
+    runApplication<Application>(*args)
+}
+
+// REST controller — Kotlin-idiomatic
+@RestController
+@RequestMapping("/api/v1/orders")
+class OrderController(private val orderService: OrderService) {
+
+    @GetMapping("/{id}")
+    suspend fun getById(@PathVariable id: UUID): ResponseEntity<OrderResponse> {
+        return orderService.findById(OrderId(id.toString()))
+            ?.let { ResponseEntity.ok(OrderResponse.from(it)) }
+            ?: ResponseEntity.notFound().build()
+    }
+
+    @PostMapping
+    suspend fun create(@Valid @RequestBody request: CreateOrderRequest): ResponseEntity<OrderResponse> {
+        return when (val result = orderService.create(request)) {
+            is Result.Success -> ResponseEntity
+                .created(URI("/api/v1/orders/${result.value.id}"))
+                .body(OrderResponse.from(result.value))
+            is Result.Failure -> ResponseEntity
+                .badRequest()
+                .build()
+        }
+    }
+}
+
+// Configuration with Kotlin DSL
+@Configuration
+class SecurityConfig {
+    @Bean
+    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
+        return http {
+            csrf { disable() }
+            authorizeHttpRequests {
+                authorize("/api/public/**", permitAll)
+                authorize("/actuator/health", permitAll)
+                authorize(anyRequest, authenticated)
+            }
+            oauth2ResourceServer { jwt { } }
+            sessionManagement { sessionCreationPolicy = SessionCreationPolicy.STATELESS }
+        }
+    }
+}
+```
+
+## Exposed (Kotlin SQL Framework)
+
+```kotlin
+// Type-safe SQL — no string queries
+object Users : Table("users") {
+    val id = uuid("id").autoGenerate()
+    val name = varchar("name", 200)
+    val email = varchar("email", 255).uniqueIndex()
+    val active = bool("active").default(true)
+    val createdAt = timestamp("created_at").defaultExpression(CurrentTimestamp)
+
+    override val primaryKey = PrimaryKey(id)
+}
+
+// Repository
+class UserRepository(private val database: Database) {
+
+    suspend fun findByEmail(email: String): User? = dbQuery {
+        Users.selectAll()
+            .where { Users.email eq email }
+            .map { it.toUser() }
+            .singleOrNull()
+    }
+
+    suspend fun create(request: CreateUserRequest): User = dbQuery {
+        val id = Users.insert {
+            it[name] = request.name
+            it[email] = request.email
+        } get Users.id
+
+        findById(UserId(id.toString()))!!
+    }
+
+    private suspend fun <T> dbQuery(block: suspend () -> T): T =
+        newSuspendedTransaction(Dispatchers.IO) { block() }
+}
+```
+
+## Ktor Client (HTTP)
+
+```kotlin
+// Shared client instance with configuration
+val httpClient = HttpClient(CIO) {
+    install(ContentNegotiation) { json() }
+    install(HttpTimeout) {
+        requestTimeoutMillis = 30_000
+        connectTimeoutMillis = 5_000
+    }
+    install(HttpRequestRetry) {
+        retryOnServerErrors(maxRetries = 3)
+        exponentialDelay()
+    }
+}
+
+// Type-safe API calls
+suspend fun fetchGitHubUser(username: String): GitHubUser {
+    return httpClient.get("https://api.github.com/users/$username").body()
+}
+```
+
+## Dependency Injection (Koin)
+
+```kotlin
+// Module definition
+val appModule = module {
+    single { Database.connect(get<DatabaseConfig>().url) }
+    single { UserRepository(get()) }
+    single { OrderRepository(get()) }
+    factory { UserService(get(), get()) }
+    factory { OrderService(get(), get()) }
+}
+
+// Ktor integration
+fun Application.configureKoin() {
+    install(Koin) {
+        modules(appModule)
+    }
+}
+
+// Injection in routes
+fun Route.userRoutes() {
+    val userService by inject<UserService>()
+    // ...
+}
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: blocking calls in coroutine context
+suspend fun fetchData(): Data {
+    val response = okHttpClient.newCall(request).execute() // BLOCKS the thread
+    // Use: a suspend-compatible HTTP client (Ktor Client, suspend wrappers)
+}
+
+// Never: exposing mutable state from services
+class UserService {
+    val users = mutableListOf<User>() // Anyone can mutate
+    // Use: private mutableListOf, expose as List
+}
+
+// Never: Java-style builder patterns (use named arguments + copy())
+User.builder().name("Alice").email("a@b.com").build()
+// Use: User(name = "Alice", email = "a@b.com")
+```

package/templates/kotlin-expert/.cursorrules/language-features.md

@@ -0,0 +1,231 @@
+# Kotlin Language Features
+
+Modern Kotlin used deliberately. Every feature exists for safety, clarity, or expressiveness.
+
+## Null Safety
+
+```kotlin
+// The type system enforces null safety — respect it
+fun findUser(email: String): User? {
+    return userRepository.findByEmail(email)
+}
+
+// Safe call chain
+val cityName = user?.address?.city?.name
+
+// Elvis operator for defaults
+val displayName = user?.name ?: "Anonymous"
+
+// Elvis with throw for required values
+val userId = request.userId ?: throw IllegalArgumentException("userId is required")
+
+// Smart casts — the compiler narrows for you
+fun process(value: Any) {
+    if (value is String) {
+        println(value.length) // Smart cast to String
+    }
+}
+
+// Safe cast
+val number = value as? Int // null if not Int, no ClassCastException
+
+// NEVER: !! without proof
+user!!.name // If user is null → NPE. Only use when you've verified externally.
+// Prefer: requireNotNull(user) { "User must exist after authentication" }
+```
+
+### Rules
+
+- `!!` is a code smell. Every usage needs a comment explaining why it's safe
+- Prefer `requireNotNull()` or `checkNotNull()` — they provide meaningful error messages
+- Use `?.let { }` for nullable transformations
+- Return nullable types from functions that legitimately might not find a result
+
+## Data Classes
+
+```kotlin
+// Immutable data carriers — the default for DTOs, events, value objects
+data class CreateUserRequest(
+    val name: String,
+    val email: String,
+    val role: UserRole = UserRole.USER
+)
+
+// Defensive copying for collections
+data class Order(
+    val id: OrderId,
+    val customerId: CustomerId,
+    val items: List<OrderItem>, // Immutable List, not MutableList
+    val status: OrderStatus,
+    val createdAt: Instant
+)
+
+// Non-destructive updates
+val updatedOrder = order.copy(status = OrderStatus.SHIPPED)
+
+// Value objects with validation
+@JvmInline
+value class Email(val value: String) {
+    init {
+        require(value.contains("@")) { "Invalid email: $value" }
+    }
+}
+
+@JvmInline
+value class UserId(val value: String) {
+    init {
+        require(value.isNotBlank()) { "UserId must not be blank" }
+    }
+}
+```
+
+## Sealed Types
+
+```kotlin
+// Exhaustive state modeling — the compiler enforces completeness
+sealed interface PaymentResult {
+    data class Success(val transactionId: String, val processedAt: Instant) : PaymentResult
+    data class Failure(val errorCode: String, val message: String) : PaymentResult
+    data class Pending(val referenceId: String, val estimatedWait: Duration) : PaymentResult
+}
+
+// Exhaustive when — add a new subtype, get a compile error everywhere
+fun describe(result: PaymentResult): String = when (result) {
+    is PaymentResult.Success -> "Paid: ${result.transactionId}"
+    is PaymentResult.Failure -> "Failed: ${result.message}"
+    is PaymentResult.Pending -> "Pending: ${result.referenceId}"
+}
+
+// Result modeling
+sealed interface Result<out T> {
+    data class Success<T>(val value: T) : Result<T>
+    data class Failure(val error: AppError) : Result<Nothing>
+}
+
+sealed interface AppError {
+    data class NotFound(val entity: String, val id: String) : AppError
+    data class Validation(val errors: Map<String, String>) : AppError
+    data class Conflict(val message: String) : AppError
+}
+```
+
+## Extension Functions
+
+```kotlin
+// Add behavior to types without inheritance
+fun String.toSlug(): String =
+    this.lowercase()
+        .replace(Regex("[^a-z0-9\\s-]"), "")
+        .replace(Regex("\\s+"), "-")
+        .trim('-')
+
+// Scoped extensions for domain logic
+fun List<Order>.totalRevenue(): BigDecimal =
+    this.filter { it.status == OrderStatus.COMPLETED }
+        .sumOf { it.total }
+
+// Extension properties
+val String.isValidEmail: Boolean
+    get() = this.matches(Regex("^[^@]+@[^@]+\\.[^@]+$"))
+
+// Generic extensions
+fun <T> T.also(block: (T) -> Unit): T {
+    block(this)
+    return this
+}
+```
+
+## Scope Functions
+
+```kotlin
+// let — transform nullable, scoped operations
+val length = name?.let { it.trim().length }
+
+// apply — configure objects
+val connection = HttpClient().apply {
+    timeout = Duration.ofSeconds(30)
+    retries = 3
+}
+
+// run — execute block with receiver
+val result = StringBuilder().run {
+    append("Hello")
+    append(" ")
+    append("World")
+    toString()
+}
+
+// also — side effects without changing the value
+val user = createUser(request).also { logger.info("Created user: ${it.id}") }
+
+// with — operate on an object
+val summary = with(report) {
+    "$title: $total items, $revenue revenue"
+}
+
+// Rules:
+// - let: nullable chains, scoped transformations
+// - apply: object configuration
+// - run: compute a result from a receiver
+// - also: side effects (logging, validation)
+// - with: multiple operations on same object (avoid for nullable)
+```
+
+## Collection Operations
+
+```kotlin
+// Kotlin collections are immutable by default
+val users: List<User> = fetchUsers() // Immutable
+val mutableUsers: MutableList<User> = mutableListOf() // Explicit mutation
+
+// Functional chains
+val activeAdminEmails = users
+    .filter { it.isActive }
+    .filter { it.role == Role.ADMIN }
+    .map { it.email }
+    .sorted()
+
+// groupBy, associateBy, partition
+val (active, inactive) = users.partition { it.isActive }
+val byDepartment = users.groupBy { it.department }
+val byId = users.associateBy { it.id }
+
+// Sequences for large collections (lazy evaluation)
+val result = users.asSequence()
+    .filter { it.isActive }
+    .map { it.name }
+    .take(10)
+    .toList()
+
+// buildList, buildMap, buildSet
+val items = buildList {
+    add("first")
+    addAll(existingItems)
+    if (includeExtra) add("extra")
+}
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: !! without justification
+user!!.name // NPE waiting to happen
+
+// Never: var when val works
+var name = "Alice" // Will it change? If not, use val
+
+// Never: MutableList in public APIs
+fun getUsers(): MutableList<User> // Caller can mutate your internal state
+// Use: fun getUsers(): List<User>
+
+// Never: Java-style static utilities
+object StringUtils { fun format(s: String): String = ... }
+// Use: extension functions — fun String.format(): String = ...
+
+// Never: when without exhaustive matching on sealed types
+when (result) {
+    is Success -> handle(result)
+    else -> {} // Silently ignores new subtypes
+}
+// Remove else — let the compiler catch missing cases
+```

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

@@ -0,0 +1,77 @@
+# Kotlin Expert Overview
+
+Principal-level Kotlin engineering. Deep language mastery, coroutines, multiplatform, and idiomatic patterns.
+
+## Scope
+
+This guide applies to:
+- Backend services (Ktor, Spring Boot, Quarkus)
+- Android applications (Jetpack Compose, Architecture Components)
+- Kotlin Multiplatform (KMP) — shared code across Android, iOS, web, desktop
+- CLI tools and scripting
+- Libraries and Maven/Gradle artifacts
+- Data processing and streaming
+
+## Core Philosophy
+
+Kotlin is a pragmatic language. It gives you safety, expressiveness, and interoperability — use all three.
+
+- **Null safety is the foundation.** The type system distinguishes nullable from non-nullable. Respect it — no `!!` without proof.
+- **Immutability by default.** `val` over `var`, immutable collections, data classes. Mutation is explicit and intentional.
+- **Conciseness without cleverness.** Kotlin lets you write less code. That doesn't mean you should write unreadable code.
+- **Coroutines are structured.** Structured concurrency is not optional — every coroutine has a scope, every scope has a lifecycle.
+- **Interop is a feature, not a compromise.** Kotlin's Java interop is seamless. Use Java libraries freely, but write Kotlin idiomatically.
+- **If you don't know, say so.** Admitting uncertainty is professional. Guessing at coroutine behavior you haven't verified is not.
+
+## Key Principles
+
+1. **Null Safety Is Non-Negotiable** — No `!!` without documented justification. Use safe calls, elvis, and smart casts
+2. **Immutability by Default** — `val`, `List` (not `MutableList`), `data class`, `copy()`
+3. **Structured Concurrency** — Every coroutine lives in a scope. No `GlobalScope`. No fire-and-forget
+4. **Extension Functions Over Utility Classes** — Extend types at the call site, not in static helpers
+5. **Sealed Types for State Modeling** — Exhaustive `when` expressions, impossible states are compile errors
+
+## Project Structure
+
+```
+project/
+├── src/main/kotlin/com/example/myapp/
+│   ├── Application.kt              # Entry point
+│   ├── config/                      # Configuration
+│   ├── domain/                      # Core domain (no framework deps)
+│   │   ├── model/                   # Data classes, value objects, sealed types
+│   │   ├── service/                 # Domain services
+│   │   └── event/                   # Domain events
+│   ├── application/                 # Use cases, orchestration
+│   │   ├── command/
+│   │   ├── query/
+│   │   └── port/                    # Interfaces
+│   ├── infrastructure/              # External concerns
+│   │   ├── persistence/             # Database (Exposed, JPA, R2DBC)
+│   │   ├── messaging/               # Kafka, RabbitMQ
+│   │   └── client/                  # HTTP clients
+│   └── api/                         # REST/gRPC endpoints
+│       ├── route/                   # Ktor routes or Spring controllers
+│       └── dto/                     # Request/response models
+├── src/test/kotlin/com/example/myapp/
+│   ├── unit/
+│   ├── integration/
+│   └── architecture/
+├── build.gradle.kts
+└── Dockerfile
+```
+
+## Definition of Done
+
+A Kotlin feature is complete when:
+
+- [ ] Compiles with zero warnings (`-Werror` or `allWarningsAsErrors = true`)
+- [ ] All tests pass
+- [ ] No `!!` without documented justification
+- [ ] No `var` where `val` suffices
+- [ ] No `MutableList`/`MutableMap` exposed in public APIs
+- [ ] Coroutines use structured concurrency (no `GlobalScope`)
+- [ ] Nullable types handled explicitly (no suppressed warnings)
+- [ ] Detekt reports zero findings
+- [ ] No `TODO` without an associated issue
+- [ ] Code reviewed and approved