agentic-team-templates 0.13.1 → 0.14.0

package/templates/kotlin-expert/CLAUDE.md

@@ -0,0 +1,276 @@
+# Kotlin Expert Development Guide
+
+Principal-level guidelines for Kotlin engineering. Deep language mastery, coroutines, multiplatform, and idiomatic patterns.
+
+---
+
+## Overview
+
+This guide applies to:
+- Backend services (Ktor, Spring Boot, Quarkus)
+- Android applications (Jetpack Compose, Architecture Components)
+- Kotlin Multiplatform (KMP) — shared code across platforms
+- 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. No `!!` without proof.
+- **Immutability by default.** `val` over `var`, immutable collections, data classes.
+- **Conciseness without cleverness.** Less code doesn't mean unreadable code.
+- **Coroutines are structured.** Every coroutine has a scope, every scope has a lifecycle.
+- **Interop is a feature.** Use Java libraries freely, but write Kotlin idiomatically.
+- **If you don't know, say so.** Admitting uncertainty is professional.
+
+### Key Principles
+
+1. **Null Safety Is Non-Negotiable** — No `!!` without justification. Safe calls, elvis, smart casts
+2. **Immutability by Default** — `val`, `List` (not `MutableList`), data classes, `copy()`
+3. **Structured Concurrency** — Every coroutine in a scope. No `GlobalScope`
+4. **Extension Functions Over Utility Classes** — Extend types at the call site
+5. **Sealed Types for State Modeling** — Exhaustive `when`, impossible states are compile errors
+
+### Project Structure
+
+```
+project/
+├── src/main/kotlin/com/example/myapp/
+│   ├── Application.kt
+│   ├── config/
+│   ├── domain/
+│   │   ├── model/
+│   │   ├── service/
+│   │   └── event/
+│   ├── application/
+│   ├── infrastructure/
+│   └── api/
+├── src/test/kotlin/
+├── build.gradle.kts
+└── Dockerfile
+```
+
+---
+
+## Language Features
+
+### Null Safety
+
+```kotlin
+val displayName = user?.name ?: "Anonymous"
+val userId = request.userId ?: throw IllegalArgumentException("userId required")
+// Never: user!!.name — use requireNotNull() with a message
+```
+
+### Data Classes and Value Classes
+
+```kotlin
+data class Order(val id: OrderId, val items: List<OrderItem>, val status: OrderStatus)
+val updated = order.copy(status = OrderStatus.SHIPPED)
+
+@JvmInline
+value class UserId(val value: String) // Zero-overhead type safety
+```
+
+### Sealed Types
+
+```kotlin
+sealed interface Result<out T> {
+    data class Success<T>(val value: T) : Result<T>
+    data class Failure(val error: AppError) : Result<Nothing>
+}
+
+fun describe(result: Result<User>): String = when (result) {
+    is Result.Success -> "User: ${result.value.name}"
+    is Result.Failure -> "Error: ${result.error}"
+    // Exhaustive — compiler enforces all cases
+}
+```
+
+### Extension Functions and Scope Functions
+
+```kotlin
+fun String.toSlug(): String = lowercase().replace(Regex("[^a-z0-9\\s-]"), "").replace(Regex("\\s+"), "-")
+
+val connection = HttpClient().apply { timeout = 30.seconds; retries = 3 }
+val user = createUser(request).also { logger.info("Created: ${it.id}") }
+```
+
+---
+
+## Coroutines
+
+### Structured Concurrency
+
+```kotlin
+suspend fun loadDashboard(userId: UserId): Dashboard = coroutineScope {
+    val user = async { userService.findById(userId) }
+    val orders = async { orderService.findRecent(userId) }
+    Dashboard(user = user.await(), orders = orders.await())
+}
+// If any async fails, ALL are cancelled
+```
+
+### Flow
+
+```kotlin
+val state: StateFlow<UiState> = _state.asStateFlow()
+
+fun observeUsers(): Flow<List<User>> = flow {
+    while (true) {
+        emit(userRepository.findAll())
+        delay(5.seconds)
+    }
+}
+```
+
+### Rules
+
+- No `GlobalScope` — use lifecycle-bound scopes
+- No `runBlocking` in production (except `main()` and tests)
+- No `Thread.sleep()` — use `delay()`
+- Always rethrow `CancellationException`
+- Use `supervisorScope` when child failures should be independent
+
+---
+
+## Error Handling
+
+### Sealed Result Types
+
+```kotlin
+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)
+    }
+}
+```
+
+### Validation
+
+```kotlin
+require(customerId.isNotBlank()) { "customerId must not be blank" }
+check(order.status == OrderStatus.PAID) { "Can only ship paid orders" }
+val user = requireNotNull(userRepo.findById(id)) { "User $id must exist" }
+```
+
+---
+
+## Frameworks
+
+### Ktor
+
+```kotlin
+fun Route.userRoutes() {
+    route("/users") {
+        get("/{id}") {
+            val id = UserId(call.parameters["id"] ?: return@get call.respond(HttpStatusCode.BadRequest))
+            // ...
+        }
+        post { val request = call.receive<CreateUserRequest>(); /* ... */ }
+    }
+}
+```
+
+### Spring Boot
+
+```kotlin
+@RestController
+@RequestMapping("/api/v1/orders")
+class OrderController(private val orderService: OrderService) {
+    @GetMapping("/{id}")
+    suspend fun getById(@PathVariable id: UUID): ResponseEntity<OrderResponse> { /* ... */ }
+}
+```
+
+### Exposed (SQL)
+
+```kotlin
+object Users : Table("users") {
+    val id = uuid("id").autoGenerate()
+    val name = varchar("name", 200)
+    val email = varchar("email", 255).uniqueIndex()
+}
+```
+
+---
+
+## Testing
+
+### Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| JUnit 5 / Kotest | Test framework |
+| MockK | Kotlin-native mocking |
+| kotlinx-coroutines-test | Coroutine testing |
+| Testcontainers | Real databases/services |
+| Ktor Test | HTTP endpoint testing |
+
+### Test Structure
+
+```kotlin
+@Test
+fun `create with valid items returns success`() = runTest {
+    coEvery { inventoryClient.checkAvailability("SKU-001", 2) } returns true
+    val result = sut.create(request)
+    assertThat(result).isInstanceOf(Result.Success::class.java)
+}
+```
+
+---
+
+## Performance
+
+### Key Patterns
+
+- `inline` functions for higher-order function hot paths
+- `value class` for zero-overhead type wrappers
+- Sequences for large collection chains (lazy evaluation)
+- Pre-size collections with `HashMap(expectedSize)`
+- `buildList`/`buildString` for single-allocation construction
+- Buffered channels for coroutine throughput
+
+---
+
+## Tooling
+
+### Essential Stack
+
+| Tool | Purpose |
+|------|---------|
+| Gradle (Kotlin DSL) | Build system |
+| Detekt | Static analysis |
+| ktlint | Code formatting |
+| kotlinx.serialization | Compile-time serialization |
+| kotlin-logging | Structured logging |
+| Koin | Dependency injection |
+
+### CI Essentials
+
+```bash
+./gradlew check      # Build + test + analysis
+./gradlew detekt     # Static analysis
+```
+
+---
+
+## Definition of Done
+
+A Kotlin feature is complete when:
+
+- [ ] Compiles with zero warnings (`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
+- [ ] Detekt reports zero findings
+- [ ] No `TODO` without an associated issue
+- [ ] Code reviewed and approved

package/templates/swift-expert/.cursorrules/concurrency.md

@@ -0,0 +1,230 @@
+# Swift Concurrency
+
+Structured concurrency with async/await, actors, and task groups. No more callback pyramids.
+
+## async/await
+
+```swift
+// Async functions
+func fetchUser(id: UUID) async throws -> User {
+    let (data, response) = try await urlSession.data(from: userURL(id))
+    guard let httpResponse = response as? HTTPURLResponse,
+          httpResponse.statusCode == 200 else {
+        throw APIError.invalidResponse
+    }
+    return try JSONDecoder().decode(User.self, from: data)
+}
+
+// Calling async code
+let user = try await fetchUser(id: userId)
+
+// Async let — parallel execution
+async let user = fetchUser(id: userId)
+async let orders = fetchOrders(userId: userId)
+async let preferences = fetchPreferences(userId: userId)
+
+let dashboard = try await Dashboard(
+    user: user,
+    orders: orders,
+    preferences: preferences
+)
+// All three requests run concurrently
+```
+
+## Task and TaskGroup
+
+```swift
+// Unstructured task (use sparingly)
+Task {
+    do {
+        let result = try await processData()
+        await MainActor.run { updateUI(with: result) }
+    } catch {
+        await MainActor.run { showError(error) }
+    }
+}
+
+// Task group — dynamic parallelism
+func fetchAllUsers(ids: [UUID]) async throws -> [User] {
+    try await withThrowingTaskGroup(of: User.self) { group in
+        for id in ids {
+            group.addTask {
+                try await fetchUser(id: id)
+            }
+        }
+
+        var users: [User] = []
+        for try await user in group {
+            users.append(user)
+        }
+        return users
+    }
+}
+
+// Task cancellation
+func longRunningProcess() async throws {
+    for item in items {
+        try Task.checkCancellation() // Throws if cancelled
+        await process(item)
+    }
+}
+
+// Cooperative cancellation
+Task {
+    let result = try await longRunningProcess()
+}
+// Later:
+task.cancel() // Cooperative — task must check
+```
+
+## Actors
+
+```swift
+// Actor — thread-safe mutable state
+actor ImageCache {
+    private var cache: [URL: UIImage] = [:]
+
+    func image(for url: URL) -> UIImage? {
+        cache[url]
+    }
+
+    func store(_ image: UIImage, for url: URL) {
+        cache[url] = image
+    }
+
+    func clear() {
+        cache.removeAll()
+    }
+}
+
+// Using actors
+let cache = ImageCache()
+let image = await cache.image(for: url) // await required for actor isolation
+
+// nonisolated — opt out for non-mutable access
+actor UserStore {
+    let id: UUID // Immutable, safe without isolation
+
+    nonisolated var description: String {
+        "UserStore(\(id))"
+    }
+}
+```
+
+## MainActor
+
+```swift
+// MainActor — UI thread safety
+@MainActor
+class UserViewModel: ObservableObject {
+    @Published var users: [User] = []
+    @Published var isLoading = false
+    @Published var error: AppError?
+
+    func loadUsers() async {
+        isLoading = true
+        defer { isLoading = false }
+
+        do {
+            users = try await userService.fetchAll()
+        } catch {
+            self.error = AppError(error)
+        }
+    }
+}
+
+// MainActor.run for one-off UI updates
+func processInBackground() async {
+    let result = await heavyComputation()
+    await MainActor.run {
+        self.displayResult = result
+    }
+}
+```
+
+## Sendable
+
+```swift
+// Sendable — safe to pass across concurrency domains
+struct UserDTO: Sendable {
+    let id: UUID
+    let name: String
+    let email: String
+}
+
+// @Sendable closures
+func performAsync(_ work: @Sendable @escaping () async -> Void) {
+    Task { await work() }
+}
+
+// @unchecked Sendable — manual safety guarantee
+final class ThreadSafeCache: @unchecked Sendable {
+    private let lock = NSLock()
+    private var storage: [String: Any] = [:]
+
+    func get(_ key: String) -> Any? {
+        lock.lock()
+        defer { lock.unlock() }
+        return storage[key]
+    }
+}
+```
+
+## AsyncSequence and AsyncStream
+
+```swift
+// AsyncStream for bridging callback APIs
+func notifications(named name: Notification.Name) -> AsyncStream<Notification> {
+    AsyncStream { continuation in
+        let observer = NotificationCenter.default.addObserver(
+            forName: name, object: nil, queue: nil
+        ) { notification in
+            continuation.yield(notification)
+        }
+        continuation.onTermination = { _ in
+            NotificationCenter.default.removeObserver(observer)
+        }
+    }
+}
+
+// Consuming async sequences
+for await notification in notifications(named: .userDidLogin) {
+    handleLogin(notification)
+}
+
+// AsyncSequence transformations
+let validUsers = userStream
+    .filter { $0.isActive }
+    .map { UserViewModel(user: $0) }
+    .prefix(10)
+```
+
+## Rules
+
+- No `DispatchQueue.main.async` in new code — use `@MainActor` or `MainActor.run`
+- No completion handlers in new code — use `async`/`await`
+- No `DispatchGroup` — use `TaskGroup`
+- Always check `Task.isCancelled` or call `Task.checkCancellation()` in loops
+- Mark types as `Sendable` when passed across concurrency domains
+- Use actors for shared mutable state, not locks (in new code)
+- `Task {}` is unstructured — prefer structured concurrency (`async let`, `TaskGroup`)
+
+## Anti-Patterns
+
+```swift
+// Never: fire-and-forget tasks without error handling
+Task { try await riskyOperation() } // Errors silently swallowed
+// Use: Task with do/catch
+
+// Never: blocking the main thread
+DispatchQueue.main.sync { /* ... */ } // Deadlock risk
+// Use: @MainActor or MainActor.run
+
+// Never: capturing self strongly in long-lived tasks
+Task { [self] in await self.process() } // Potential retain cycle
+// Use: Task { [weak self] in await self?.process() }
+
+// Never: using GCD for new concurrent code
+DispatchQueue.global().async { /* ... */ }
+// Use: Task { /* ... */ } with async/await
+```

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

@@ -0,0 +1,213 @@
+# Swift Error Handling
+
+Typed errors, Result, and defensive validation. Make failure states explicit.
+
+## Error Types
+
+```swift
+// Domain-specific errors with associated values
+enum APIError: Error, LocalizedError {
+    case networkUnavailable
+    case unauthorized
+    case notFound(resource: String, id: String)
+    case serverError(statusCode: Int, message: String)
+    case decodingFailed(type: String, underlying: Error)
+    case rateLimited(retryAfter: TimeInterval)
+
+    var errorDescription: String? {
+        switch self {
+        case .networkUnavailable:
+            "Network connection is unavailable"
+        case .unauthorized:
+            "Authentication required"
+        case .notFound(let resource, let id):
+            "\(resource) with ID '\(id)' not found"
+        case .serverError(let code, let message):
+            "Server error \(code): \(message)"
+        case .decodingFailed(let type, let error):
+            "Failed to decode \(type): \(error.localizedDescription)"
+        case .rateLimited(let retryAfter):
+            "Rate limited. Retry after \(retryAfter)s"
+        }
+    }
+}
+```
+
+## do/catch
+
+```swift
+// Specific error handling
+func loadUser(id: UUID) async {
+    do {
+        let user = try await userService.fetch(id: id)
+        self.user = user
+    } catch let error as APIError {
+        switch error {
+        case .notFound:
+            self.state = .notFound
+        case .unauthorized:
+            self.state = .needsLogin
+        case .networkUnavailable:
+            self.state = .offline
+        default:
+            self.state = .error(error)
+        }
+    } catch {
+        // Catch-all for unexpected errors
+        self.state = .error(AppError.unexpected(error))
+    }
+}
+
+// try? — convert to optional (use when failure is acceptable)
+let cachedImage = try? imageCache.load(key: url.absoluteString)
+
+// try! — only when failure is a programmer error
+let regex = try! NSRegularExpression(pattern: "^[a-z]+$")
+```
+
+## Result Type
+
+```swift
+// Result for synchronous operations
+func validate(email: String) -> Result<Email, ValidationError> {
+    guard !email.isEmpty else {
+        return .failure(.empty("email"))
+    }
+    guard email.contains("@") else {
+        return .failure(.invalidFormat("email"))
+    }
+    return .success(Email(rawValue: email))
+}
+
+// Pattern matching on Result
+switch validate(email: input) {
+case .success(let email):
+    createAccount(email: email)
+case .failure(let error):
+    showValidationError(error)
+}
+
+// Result with map/flatMap
+let userName = fetchUser(id: userId)
+    .map { $0.name }
+    .mapError { AppError.network($0) }
+```
+
+## Guard and Preconditions
+
+```swift
+// Guard — early exit for invalid state
+func processOrder(_ order: Order) throws {
+    guard order.items.isEmpty == false else {
+        throw OrderError.emptyOrder
+    }
+    guard order.status == .confirmed else {
+        throw OrderError.invalidStatus(order.status)
+    }
+    guard let paymentMethod = order.paymentMethod else {
+        throw OrderError.noPaymentMethod
+    }
+    // Happy path continues here, all values available
+    charge(paymentMethod, for: order)
+}
+
+// precondition — programmer errors (removed in -Ounchecked)
+func element(at index: Int) -> Element {
+    precondition(index >= 0 && index < count, "Index \(index) out of bounds")
+    return storage[index]
+}
+
+// assert — debug-only checks
+func configure(retryCount: Int) {
+    assert(retryCount > 0, "retryCount must be positive")
+    self.maxRetries = retryCount
+}
+
+// fatalError — truly impossible states
+func handle(_ state: AppState) {
+    switch state {
+    case .ready: start()
+    case .running: continue_()
+    // If new states are added, this will force handling them
+    @unknown default:
+        fatalError("Unhandled state: \(state)")
+    }
+}
+```
+
+## Typed Throws (Swift 6+)
+
+```swift
+// Typed throws — callers know exact error type
+func parse(json: Data) throws(ParseError) -> Config {
+    guard let dict = try? JSONSerialization.jsonObject(with: json) as? [String: Any] else {
+        throw .invalidJSON
+    }
+    guard let name = dict["name"] as? String else {
+        throw .missingField("name")
+    }
+    return Config(name: name)
+}
+
+// Caller gets typed error without casting
+do {
+    let config = try parse(json: data)
+} catch {
+    // error is ParseError, not any Error
+    switch error {
+    case .invalidJSON: handleInvalidJSON()
+    case .missingField(let name): handleMissingField(name)
+    }
+}
+```
+
+## Error Recovery Patterns
+
+```swift
+// Retry with exponential backoff
+func fetchWithRetry<T>(
+    maxAttempts: Int = 3,
+    operation: () async throws -> T
+) async throws -> T {
+    var lastError: Error?
+    for attempt in 0..<maxAttempts {
+        do {
+            return try await operation()
+        } catch {
+            lastError = error
+            if attempt < maxAttempts - 1 {
+                let delay = pow(2.0, Double(attempt))
+                try await Task.sleep(for: .seconds(delay))
+            }
+        }
+    }
+    throw lastError!
+}
+
+// Fallback chain
+func loadAvatar(for user: User) async -> UIImage {
+    if let cached = avatarCache[user.id] { return cached }
+    if let downloaded = try? await downloadAvatar(user.avatarURL) { return downloaded }
+    return UIImage(systemName: "person.circle")!
+}
+```
+
+## Anti-Patterns
+
+```swift
+// Never: catching and ignoring errors
+do { try operation() } catch { } // Silent failure
+// Use: at minimum, log the error
+
+// Never: using try! on fallible operations
+let data = try! Data(contentsOf: fileURL) // Crash on missing file
+// Use: do/try/catch or try? with fallback
+
+// Never: throwing generic Error
+throw NSError(domain: "", code: 0) // No context
+// Use: domain-specific error types
+
+// Never: error types without context
+enum AppError: Error { case failed } // Useless for debugging
+// Use: associated values with context
+```