@djm204/agent-skills 1.0.0

package/templates/languages/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/languages/python-expert/.cursor/rules/async-python.mdc

@@ -0,0 +1,71 @@
+---
+description: Async Python
+alwaysApply: false
+---
+
+# Async Python
+
+`asyncio` enables concurrent I/O on a single thread. Understand the event loop, coroutines, and task lifecycle.
+
+## Coroutines and Tasks
+
+```python
+async def fetch_data(url: str) -> bytes:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.read()
+
+# Tasks run concurrently on the event loop
+async def fetch_all(urls: list[str]) -> list[bytes]:
+    tasks = [asyncio.create_task(fetch_data(url)) for url in urls]
+    return await asyncio.gather(*tasks)
+```
+
+## gather vs TaskGroup
+
+```python
+# gather — returns results in order
+users, posts = await asyncio.gather(fetch_users(), fetch_posts())
+
+# TaskGroup (3.11+) — structured concurrency, cancels all on first failure
+async with asyncio.TaskGroup() as tg:
+    user_task = tg.create_task(fetch_users())
+    post_task = tg.create_task(fetch_posts())
+users, posts = user_task.result(), post_task.result()
+```
+
+## Timeouts and Bounded Concurrency
+
+```python
+# Timeout (3.11+)
+async with asyncio.timeout(5.0):
+    data = await fetch_data(url)
+
+# Semaphore for bounding concurrency
+semaphore = asyncio.Semaphore(10)
+async def bounded_fetch(url: str) -> Response:
+    async with semaphore:
+        return await fetch(url)
+```
+
+## Key Rules
+
+- Use `run_in_executor` for blocking/CPU-bound work in async context
+- Async generators (`async for`) for streaming large result sets
+- Every spawned task needs error handling and a cancellation strategy
+
+## Anti-Patterns
+
+```python
+# Never: Blocking calls in async code
+async def bad():
+    requests.get(url)  # Blocks event loop — use aiohttp
+    time.sleep(1)      # Blocks event loop — use asyncio.sleep()
+
+# Never: Fire-and-forget without error handling
+asyncio.create_task(work())  # Who catches exceptions?
+
+# Never: Unbounded task spawning — use semaphore
+for item in million_items:
+    asyncio.create_task(process(item))  # OOM risk
+```

package/templates/languages/python-expert/.cursor/rules/overview.mdc

@@ -0,0 +1,76 @@
+---
+description: Python Expert
+alwaysApply: false
+---
+
+# Python Expert
+
+Idiomatic Python, production systems, and deep interpreter knowledge.
+
+## Scope
+
+- Web services and APIs (Django, FastAPI, Flask)
+- CLI tools, automation, data processing, ETL pipelines
+- Libraries/packages, ML infrastructure, async services
+
+## Core Philosophy
+
+- **Readability counts.** The Zen of Python is the engineering standard
+- **Explicit is better than implicit.** Type hints, clear names, no magic
+- **Errors should never pass silently.** Bare `except:` is a bug
+- **The standard library is rich — use it.** `collections`, `itertools`, `pathlib`, `dataclasses`, `contextlib`
+
+## Key Principles
+
+### Type Hints Are Not Optional
+
+```python
+# Good: Fully typed
+def fetch_users(db: Database, *, limit: int = 100) -> list[User]: ...
+type Handler = Callable[[Request], Awaitable[Response]]
+
+# Bad: No type information
+def fetch_users(db, limit=100): ...  # What does this return?
+```
+
+### Dataclasses and Pydantic Over Raw Dicts
+
+```python
+@dataclass(frozen=True, slots=True)
+class User:
+    id: str
+    email: str
+    name: str
+    created_at: datetime = field(default_factory=datetime.now)
+
+# Bad: user = {"id": "123", "email": "a@b.com"}  # No validation, no safety
+```
+
+### EAFP Over LBYL
+
+```python
+# Good: Try it and handle the exception
+try:
+    value = mapping[key]
+except KeyError:
+    value = default
+
+# Bad: if key in mapping → double lookup, race conditions
+```
+
+### Context Managers for Resources
+
+```python
+with open("data.json") as f:
+    data = json.load(f)
+
+async with aiohttp.ClientSession() as session:
+    response = await session.get(url)
+```
+
+## Definition of Done
+
+- [ ] `mypy --strict` passes with zero errors
+- [ ] `ruff check` and `ruff format --check` pass
+- [ ] `pytest` passes; error cases tested
+- [ ] No bare `except:`, no mutable defaults, no `# type: ignore` without explanation

package/templates/languages/python-expert/.cursor/rules/patterns-and-idioms.mdc

@@ -0,0 +1,77 @@
+---
+description: Python Patterns and Idioms
+alwaysApply: false
+---
+
+# Python Patterns and Idioms
+
+Idiomatic Python leverages generators, decorators, context managers, and the data model. Write Pythonic code, not Java-in-Python.
+
+## Data Model
+
+Use `@dataclass(frozen=True, slots=True)` for immutable value objects. Implement `__repr__`, `__eq__`, `__hash__` automatically. Use `@total_ordering` for comparison.
+
+## Generators
+
+```python
+# Lazy evaluation — process one item at a time
+def read_large_file(path: Path) -> Iterator[str]:
+    with open(path) as f:
+        for line in f:
+            yield line.strip()
+
+# Generator expressions over list comprehensions when iterating once
+total = sum(order.total for order in orders)
+
+# itertools for complex iteration
+for batch in batched(items, 100):  # 3.12+
+    process_batch(batch)
+```
+
+## Decorators
+
+```python
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def retry(max_attempts: int = 3):
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(max_attempts):
+                try: return func(*args, **kwargs)
+                except Exception:
+                    if attempt == max_attempts - 1: raise
+        return wrapper
+    return decorator
+```
+
+## Context Managers
+
+```python
+@contextmanager
+def timed_operation(name: str) -> Iterator[None]:
+    start = time.monotonic()
+    try: yield
+    finally: logger.info(f"{name} took {time.monotonic() - start:.3f}s")
+
+# contextlib.suppress for intentionally ignored exceptions
+with suppress(FileNotFoundError):
+    os.remove(temp_file)
+```
+
+## Anti-Patterns
+
+```python
+# Never: Mutable default arguments
+def append(item, target=[]):  # Shared across all calls!
+    target.append(item)
+# Never: Bare except — catches KeyboardInterrupt, SystemExit
+try: risky()
+except: pass
+# Never: Star imports — pollutes namespace, hides origins
+from os.path import *
+```

package/templates/languages/python-expert/.cursor/rules/performance.mdc

@@ -0,0 +1,74 @@
+---
+description: Python Performance
+alwaysApply: false
+---
+
+# Python Performance
+
+Profile before optimizing. Reach for the right tool when raw speed matters.
+
+## Profile First
+
+```bash
+py-spy record -o profile.svg -- python myapp.py  # Production profiling
+python -m cProfile -s cumulative script.py        # Function-level
+# line_profiler for line-by-line, memory_profiler for memory
+```
+
+## Data Structures
+
+- `dict` — O(1) lookup, insertion, deletion
+- `set` — O(1) membership testing
+- `deque` — O(1) append/pop from both ends
+- `heapq` — O(log n) push/pop for priority queues
+- `bisect` — O(log n) search in sorted lists
+
+## Common Bottlenecks
+
+```python
+# String concatenation — use join, not +=
+result = "".join(chunks)  # O(n), not O(n²)
+
+# Generator expressions when you don't need the full list
+total = sum(x * x for x in range(1_000_000))  # No intermediate list
+
+# Local variable lookup is faster in hot loops
+append = result.append
+for item in items:
+    append(transform(item))
+```
+
+## Concurrency Models
+
+```python
+# I/O-bound: threading or asyncio
+with ThreadPoolExecutor(max_workers=10) as executor:
+    results = list(executor.map(fetch_url, urls))
+
+# CPU-bound: multiprocessing (bypasses GIL)
+with ProcessPoolExecutor() as executor:
+    results = list(executor.map(cpu_work, data_chunks))
+```
+
+## Caching
+
+```python
+from functools import lru_cache, cache
+
+@lru_cache(maxsize=256)
+def fibonacci(n: int) -> int:
+    if n < 2: return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+@cache  # 3.9+, unlimited
+def load_schema(name: str) -> Schema:
+    return Schema.from_file(f"schemas/{name}.json")
+```
+
+## Key Rules
+
+- `slots=True` on dataclasses for memory efficiency
+- `"".join()` over `+=` for string building
+- NumPy/Polars for vectorized numeric operations
+- Never optimize without profiling first
+- A 10% speedup that makes code unmaintainable is a net loss

package/templates/languages/python-expert/.cursor/rules/testing.mdc

@@ -0,0 +1,77 @@
+---
+description: Python Testing
+alwaysApply: false
+---
+
+# Python Testing
+
+pytest is the standard. Every behavior has a test. Every bug fix starts with a failing test.
+
+## Test Structure (AAA)
+
+```python
+def test_user_creation() -> None:
+    # Arrange
+    repo = FakeUserRepo()
+    service = UserService(repo)
+    input_data = CreateUserInput(name="Alice", email="alice@example.com")
+    # Act
+    user = service.create(input_data)
+    # Assert
+    assert user.name == "Alice"
+    assert user.id is not None
+```
+
+## Parametrize
+
+```python
+@pytest.mark.parametrize("input_str, expected", [
+    ("hello world", "hello-world"),
+    ("UPPER CASE", "upper-case"),
+    ("", ""),
+])
+def test_slugify(input_str: str, expected: str) -> None:
+    assert slugify(input_str) == expected
+```
+
+## Dependency Injection Over Mocking
+
+```python
+def test_create_user_sends_notification() -> None:
+    notifier = Mock(spec=Notifier)
+    service = UserService(FakeUserRepo(), notifier)
+    service.create(CreateUserInput(name="Alice", email="a@b.com"))
+    notifier.send_welcome.assert_called_once_with("a@b.com")
+
+# When you must patch (third-party code)
+@patch("mypackage.services.user_service.send_email")
+def test_sends_email(mock_send: Mock) -> None:
+    service.signup(email="test@example.com")
+    mock_send.assert_called_once()
+```
+
+## Integration Testing
+
+```python
+@pytest.fixture
+async def client(app) -> AsyncClient:
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_create_and_retrieve_user(client: AsyncClient) -> None:
+    resp = await client.post("/users", json={"name": "Alice", "email": "a@b.com"})
+    assert resp.status_code == 201
+    resp = await client.get(f"/users/{resp.json()['id']}")
+    assert resp.json()["name"] == "Alice"
+```
+
+## Anti-Patterns
+
+```python
+# Never: Tests that depend on execution order
+# Never: Assertions without context
+assert result  # What was expected? Use: assert result.status == "active"
+# Never: Excessive mocking — if 5+ mocks, unit is too large
+# Never: time.sleep() in tests — use polling or mock the clock
+```