@geraldmaron/construct 1.0.0

package/skills/development/java.md

@@ -0,0 +1,134 @@
+<!--
+skills/development/java.md — Java Best Practices — Use this skill when writing, reviewing, or debugging Java or Kotlin code on the
+
+Use this skill when writing, reviewing, or debugging Java or Kotlin code on the JVM. ## Project Structure
+-->
+# Java Best Practices
+
+Use this skill when writing, reviewing, or debugging Java or Kotlin code on the JVM.
+
+## Project Structure
+
+```
+src/
+  main/
+    java/com/example/
+      controller/
+      service/
+      repository/
+      model/
+      config/
+    resources/
+      application.yml
+  test/
+    java/com/example/
+      controller/
+      service/
+pom.xml or build.gradle.kts
+```
+
+- Maven or Gradle for build management
+- Follow standard Maven directory layout
+- One class per file; package by feature when the project is large
+
+## Tooling
+
+| Tool | Purpose |
+|---|---|
+| javac / kotlinc | Compilation |
+| Checkstyle / ktlint | Code style enforcement |
+| SpotBugs / ErrorProne | Static analysis |
+| JUnit 5 / Kotest | Testing |
+| Mockito / MockK | Mocking |
+| JaCoCo | Coverage |
+| OWASP Dependency Check | Vulnerability scanning |
+
+## Type Safety
+
+- Use `Optional<T>` for values that may be absent; never return null from public methods
+- Records (Java 16+) or data classes (Kotlin) for immutable value objects
+- Sealed interfaces for closed type hierarchies
+- Generics with bounded wildcards: `<? extends T>` for producers, `<? super T>` for consumers
+- Avoid raw types; always parameterize generics
+
+## Error Handling
+
+- Use checked exceptions for recoverable conditions; unchecked for programming errors
+- Custom exception hierarchy extending `RuntimeException` for domain errors
+- Never catch `Exception` or `Throwable` unless at the top-level handler
+- Include context: `throw new OrderNotFoundException("Order " + id + " not found")`
+- Use try-with-resources for all `AutoCloseable` resources
+- Log at the point of handling, not at the point of throwing
+
+## Immutability
+
+- Records (Java) or data classes (Kotlin) for immutable data
+- `final` fields and classes by default
+- `Collections.unmodifiableList()` or `List.of()` for immutable collections
+- Avoid setters; use builder pattern or `with` methods that return new instances
+- Kotlin: `val` over `var`; `listOf` over `mutableListOf` unless mutation is required
+
+## Patterns
+
+### Dependency Injection
+- Constructor injection (not field injection)
+- Spring: `@Component`, `@Service`, `@Repository` stereotypes
+- Interface-based dependencies for testability
+- Avoid circular dependencies; restructure if detected
+
+### Repository Pattern
+- Interface defines data access contract
+- Implementation handles persistence details
+- Spring Data: derive queries from method names; use `@Query` for complex queries
+- Pageable for list operations
+
+### Stream API
+- Prefer streams over manual loops for collection processing
+- `map`, `filter`, `collect` for transformations
+- `Optional.map`/`flatMap` for null-safe chaining
+- Avoid side effects in stream operations
+- Use parallel streams only with benchmarking evidence
+
+## Testing
+
+- JUnit 5 with `@Test`, `@ParameterizedTest`, `@Nested`
+- Mockito for mocking external dependencies
+- `@SpringBootTest` for integration tests; `@WebMvcTest` for controller tests
+- Testcontainers for database and infrastructure integration tests
+- AssertJ for fluent assertions
+- Test naming: `should_returnEmpty_when_noResultsMatch`
+
+## Performance
+
+- Profile with JFR (Java Flight Recorder) and JMC (Mission Control)
+- GC tuning: choose G1 or ZGC based on latency requirements
+- Connection pooling: HikariCP for database, Apache HttpClient for HTTP
+- Avoid unnecessary object creation in hot paths
+- Use `StringBuilder` for string concatenation in loops
+- JMH for microbenchmarks
+
+## Spring Boot Specifics
+
+- Externalize configuration: `application.yml` with profiles
+- Actuator endpoints for health, metrics, and info
+- Use `@ConfigurationProperties` over `@Value` for structured config
+- Validate configuration with `@Validated`
+- Global exception handler with `@ControllerAdvice`
+
+## Security
+
+- Spring Security for authentication and authorization
+- Parameterized queries via JPA or Spring JDBC
+- Input validation with Bean Validation (`@Valid`, `@NotNull`, `@Size`)
+- OWASP Dependency Check in CI
+- Never log sensitive data; mask PII in logs
+- Use BCrypt for password hashing
+
+## Anti-Patterns
+
+- Service locator instead of dependency injection
+- God classes with mixed responsibilities
+- Catch-and-ignore empty catch blocks
+- Null returns instead of `Optional`
+- Mutable DTOs shared across layers
+- Over-engineering: unnecessary abstract factories and strategy patterns

package/skills/development/kotlin.md

@@ -0,0 +1,140 @@
+<!--
+skills/development/kotlin.md — Kotlin / Android Development — | Scope | Use when |
+
+## Coroutines & Flows ### Coroutine scope discipline
+-->
+# Kotlin / Android Development
+
+## Coroutines & Flows
+
+### Coroutine scope discipline
+
+| Scope | Use when |
+|---|---|
+| `viewModelScope` | ViewModel-bound work; auto-cancelled on clear |
+| `lifecycleScope` | Fragment/Activity-bound; cancelled on destroy |
+| `rememberCoroutineScope()` | Compose-scoped; cancelled on composition exit |
+| `GlobalScope` | Never — uncontrolled lifetime |
+
+```kotlin
+class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
+  private val _items = MutableStateFlow<List<Item>>(emptyList())
+  val items: StateFlow<List<Item>> = _items.asStateFlow()
+
+  init {
+    viewModelScope.launch {
+      repo.itemsFlow().collect { _items.value = it }
+    }
+  }
+}
+```
+
+### Flow operators
+
+- `stateIn(scope, SharingStarted.WhileSubscribed(5_000), initial)` — converts cold flow to hot StateFlow for UI consumption
+- `map`, `filter`, `distinctUntilChanged`, `debounce` for transform chains
+- `combine` for merging multiple flows
+- Use `flowOn(Dispatchers.IO)` for upstream CPU/IO work; do not switch dispatchers in the collector
+
+### Dispatcher guidelines
+
+| Dispatcher | Use for |
+|---|---|
+| `Dispatchers.Main` | UI updates |
+| `Dispatchers.IO` | Network, disk, database |
+| `Dispatchers.Default` | CPU-intensive work |
+| `Dispatchers.Unconfined` | Rarely — only in tests |
+
+## Jetpack Compose
+
+### State hoisting
+
+Hoist state to the lowest common owner. Stateless composables receive state and callbacks:
+
+```kotlin
+@Composable
+fun ItemList(items: List<Item>, onDelete: (Item) -> Unit) { ... }
+```
+
+### Side effects
+
+| Effect | Use when |
+|---|---|
+| `LaunchedEffect(key)` | Coroutine that re-launches when key changes |
+| `SideEffect` | Sync non-Compose state each recomposition |
+| `DisposableEffect(key)` | Setup/teardown with cleanup |
+| `rememberUpdatedState` | Capture latest lambda in long-lived effect |
+
+### Performance
+
+- `remember` expensive computations with stable keys
+- `key(id) { ... }` in lazy lists to preserve item identity
+- Avoid unstable lambdas — use `remember { { ... } }` or stable function references
+- Enable Compose compiler metrics to detect recomposition hot spots
+- Prefer `LazyColumn` over `Column` for variable-length lists
+
+## Architecture: Clean + MVVM
+
+```
+UI Layer (Composables) → ViewModel (StateFlow) → Domain (UseCases) → Data (Repository) → API / DB
+```
+
+- Domain layer is pure Kotlin, no Android dependencies
+- Repository abstracts data sources; returns `Flow` or `Result`
+- UseCases wrap single business operations; testable in isolation
+
+## Testing
+
+### Unit tests (JUnit 5 + MockK)
+
+```kotlin
+@Test
+fun `fetchItems returns mapped items`() = runTest {
+  val repo = mockk<ItemRepository>()
+  coEvery { repo.fetchAll() } returns listOf(Item(id = "1", title = "Test"))
+  val vm = ItemViewModel(repo)
+  assertEquals(1, vm.items.value.size)
+}
+```
+
+- Use `runTest` from `kotlinx-coroutines-test` for coroutine unit tests
+- `advanceUntilIdle()` to drain pending coroutines
+- `turbine` library for Flow assertion (`flow.test { assertItem() }`)
+
+### UI tests (Compose testing)
+
+```kotlin
+composeTestRule.onNodeWithText("Submit").performClick()
+composeTestRule.onNodeWithTag("result").assertIsDisplayed()
+```
+
+- Prefer semantic matchers (`onNodeWithContentDescription`) over positional
+- Use `createComposeRule()` for isolated component tests
+
+## Dependency Injection
+
+Use **Hilt** (Dagger-backed) for Android projects. Annotate entry points correctly:
+
+```kotlin
+@HiltViewModel
+class ItemViewModel @Inject constructor(
+  private val repo: ItemRepository
+) : ViewModel()
+```
+
+Scoping: `@Singleton` for app-scoped, `@ActivityRetainedScoped` for ViewModel-lived, `@ActivityScoped` for Activity-lived.
+
+## Build & Tooling
+
+- **Gradle Version Catalogs** (`libs.versions.toml`) for dependency management
+- Enable R8 / ProGuard in release builds for shrinking and obfuscation
+- **Kotlin Symbol Processing (KSP)** instead of KAPT for annotation processing
+- `detekt` for static analysis; `ktlint` for formatting
+- Minimum SDK: follow Play Store distribution requirements (API 26+ covers ~95%)
+
+## Common Pitfalls
+
+- `collect` in `Fragment.onViewCreated` without `repeatOnLifecycle(STARTED)` — causes collection after view destruction
+- `StateFlow.value` reads in tests without collecting — use `turbine` or `runTest { first() }`
+- Leaking `Activity` context into long-lived objects — use `applicationContext`
+- `LazyColumn` with `items(list)` where `list` is `State<List<...>>` causing full recomposition — use `key` param

package/skills/development/mobile-crossplatform.md

@@ -0,0 +1,144 @@
+<!--
+skills/development/mobile-crossplatform.md — Mobile Cross-Platform Development — Before choosing a framework, answer:
+
+## Decision Framework: Native vs Cross-Platform Before choosing a framework, answer:
+-->
+# Mobile Cross-Platform Development
+
+## Decision Framework: Native vs Cross-Platform
+
+Before choosing a framework, answer:
+
+| Question | Leans native | Leans cross-platform |
+|---|---|---|
+| Platform-specific APIs needed (ARKit, Health, NFC)? | Yes | No |
+| Animation fidelity is a differentiator? | Yes | Partial |
+| Single team, both platforms? | — | Yes |
+| Heavy use of platform OS widgets? | Yes | No |
+| App is primarily data-display / CRUD? | — | Yes |
+| Existing web team? | — | React Native |
+| Existing Kotlin/Swift team? | Native | — |
+
+---
+
+## Flutter
+
+**Runtime:** Dart compiled to native ARM; Skia/Impeller rendering engine (no platform widgets by default).
+
+**Best for:** pixel-perfect UI consistency across iOS/Android/web/desktop from a single codebase. Strong for teams without web background.
+
+### Architecture pattern: BLoC / Riverpod
+
+```dart
+@riverpod
+Future<List<Item>> items(ItemsRef ref) async {
+  return ref.watch(repositoryProvider).fetchAll();
+}
+```
+
+- `riverpod` for dependency injection and async state
+- `BLoC` for complex event-driven state machines
+- Avoid `StatefulWidget` + `setState` beyond leaf components
+
+### Performance
+
+- `const` constructors everywhere possible — eliminates widget rebuilds
+- `RepaintBoundary` around independently-animated subtrees
+- Profile with Flutter DevTools → CPU flame chart + widget rebuild tracker
+- `ListView.builder` for lazy lists; never `ListView(children: [...])` for long lists
+
+### Testing
+
+```dart
+testWidgets('shows items on load', (tester) async {
+  await tester.pumpWidget(ProviderScope(child: ItemList()));
+  await tester.pumpAndSettle();
+  expect(find.text('Item 1'), findsOneWidget);
+});
+```
+
+- `flutter_test` for widget tests (fast, no device needed)
+- `integration_test` for E2E on real device / emulator
+- `mocktail` or `mockito` for mocking
+
+### Tooling
+
+- `flutter analyze` + `dart format`
+- `very_good_cli` for project scaffolding with opinionated defaults
+- `flutter_flavorizr` for environment flavors (dev/staging/prod)
+
+---
+
+## React Native
+
+**Runtime:** JavaScript/TypeScript on Hermes engine; bridges to native views via the New Architecture (JSI + Fabric).
+
+**Best for:** Teams with React web experience sharing logic/types between web and mobile.
+
+### New Architecture (React Native 0.74+)
+
+Enable the New Architecture by default on new projects. Key changes:
+- JSI replaces the async bridge — sync native calls
+- Fabric replaces the native renderer — concurrent React features work correctly
+- TurboModules replace native modules
+
+### State & logic sharing with web
+
+```ts
+// Shared hook — works in React Native and React web
+export function useItems() {
+  const { data } = useQuery({ queryKey: ['items'], queryFn: fetchItems });
+  return data ?? [];
+}
+```
+
+- Share: types, API clients, business logic hooks, validation schemas
+- Do not share: navigation, platform-specific UI, native module wrappers
+
+### Navigation
+
+Use **Expo Router** (file-based) for new projects or **React Navigation** (stack/tab/drawer) for maximum control:
+
+```tsx
+// expo-router
+export default function ItemScreen() { ... }
+// file: app/items/[id].tsx → /items/:id
+```
+
+### Performance
+
+- Use the Hermes profiler to find JS thread bottlenecks
+- Move heavy computation to native modules or worklets (`react-native-reanimated`)
+- `FlatList` with `getItemLayout` for fixed-height rows; `FlashList` for variable heights
+- Enable `useMemo` / `useCallback` sparingly and only after measuring
+
+### Expo vs bare React Native
+
+| | Expo (managed) | Bare RN |
+|---|---|---|
+| Setup speed | Fast | Slower |
+| Custom native code | EAS custom builds | Full control |
+| Over-the-air updates | Expo Updates | Manual setup |
+| Recommended for | Most new projects | Deep native integration |
+
+### Testing
+
+- `@testing-library/react-native` for component tests
+- `Detox` or `Maestro` for E2E
+
+---
+
+## Common Pitfalls (both frameworks)
+
+- **Deep linking not tested until late** — set up universal links / app links in week 1
+- **Push notifications complexity** — Expo Notifications or Firebase Cloud Messaging; plan for permission states
+- **Over-the-air update strategy** — define what can be OTA vs what requires App Store review
+- **Platform capability divergence** — features available on iOS 17+ may be absent on Android 12; maintain a capability matrix
+- **Code signing automation** — `fastlane match` (iOS) and keystore management (Android) require upfront investment; do it early
+
+## When to go native anyway
+
+- Camera pipelines, real-time audio/video processing
+- Tight OS integration (CarPlay, watchOS, Android Auto)
+- Games or high-frame-rate interactive graphics
+- Health / fitness sensors with continuous background access

package/skills/development/python.md

@@ -0,0 +1,109 @@
+<!--
+skills/development/python.md — Python Best Practices — Use this skill when writing, reviewing, or debugging Python code.
+
+Use this skill when writing, reviewing, or debugging Python code. ## Project Structure
+-->
+# Python Best Practices
+
+Use this skill when writing, reviewing, or debugging Python code.
+
+## Project Structure
+
+```
+src/
+  package_name/
+    __init__.py
+    models.py
+    services.py
+    utils.py
+tests/
+  test_models.py
+  test_services.py
+  conftest.py
+pyproject.toml
+```
+
+- Use `pyproject.toml` as the single source for project metadata and tool config
+- `src/` layout to prevent accidental imports from the working directory
+- One module per concern; keep files under 400 lines
+
+## Tooling
+
+| Tool | Purpose |
+|---|---|
+| uv / poetry / pip | Dependency management |
+| ruff | Linting and formatting (replaces flake8, isort, black) |
+| mypy / pyright | Static type checking |
+| pytest | Testing |
+| coverage | Test coverage |
+| bandit | Security scanning |
+
+## Type Hints
+
+- Type all function signatures: parameters and return types
+- Use `from __future__ import annotations` for modern syntax in older Pythons
+- Prefer `str | None` over `Optional[str]`
+- Use `TypeAlias`, `TypeVar`, and `Protocol` for complex type patterns
+- Run mypy or pyright in CI with strict mode
+
+## Error Handling
+
+- Catch specific exceptions, never bare `except:`
+- Use custom exception classes for domain-specific errors
+- Context managers (`with`) for resource cleanup
+- `logging.exception()` in catch blocks to preserve stack trace
+- Return early on validation failures; avoid deep nesting
+
+## Patterns
+
+### Dataclasses and Pydantic
+- `dataclass(frozen=True)` for immutable value objects
+- Pydantic `BaseModel` for input validation and serialization
+- Avoid plain dicts for structured data that crosses function boundaries
+
+### Async
+- Use `asyncio` for I/O-bound concurrency
+- `async with` for resource management in async contexts
+- Never mix `asyncio` and threading without careful isolation
+- Use `asyncio.gather` for concurrent I/O operations
+- Set timeouts on all async operations
+
+### Dependencies
+- Pin exact versions in lock file
+- Use virtual environments always
+- Separate dev, test, and production dependencies
+- Audit with `pip audit` or `safety check`
+
+## Testing
+
+- pytest with fixtures for setup and teardown
+- `conftest.py` for shared fixtures scoped to the directory
+- `@pytest.mark.parametrize` for data-driven tests
+- `unittest.mock.patch` for external dependency isolation
+- Test async code with `pytest-asyncio`
+- Target 80% branch coverage minimum
+
+## Performance
+
+- Profile before optimizing: `cProfile`, `py-spy`, or `scalene`
+- Use generators for large data processing (lazy evaluation)
+- `functools.lru_cache` for expensive pure functions
+- Avoid global mutable state
+- Use list/dict/set comprehensions over manual loops when readable
+- Consider `numpy` or `polars` for numerical and tabular data
+
+## Security
+
+- Never use `eval()`, `exec()`, or `pickle.loads()` on untrusted input
+- Use `subprocess` with `shell=False` and explicit argument lists
+- Validate all external input with Pydantic or equivalent
+- Use `secrets` module for cryptographic randomness, not `random`
+- Keep dependencies updated; automate vulnerability scanning
+
+## Anti-Patterns
+
+- Mutable default arguments (`def f(x=[])`): use `None` and create inside
+- Broad exception handling: catch what you can handle
+- Circular imports: restructure modules or use lazy imports
+- Star imports (`from module import *`): pollutes namespace
+- Global mutable state: use dependency injection or module-level constants

package/skills/development/rust.md

@@ -0,0 +1,127 @@
+<!--
+skills/development/rust.md — Rust Best Practices — Use this skill when writing, reviewing, or debugging Rust code.
+
+Use this skill when writing, reviewing, or debugging Rust code. ## Project Structure
+-->
+# Rust Best Practices
+
+Use this skill when writing, reviewing, or debugging Rust code.
+
+## Project Structure
+
+```
+src/
+  main.rs or lib.rs
+  models/
+    mod.rs
+  services/
+    mod.rs
+  handlers/
+    mod.rs
+  error.rs
+tests/
+  integration_tests.rs
+Cargo.toml
+```
+
+- Binary crates use `main.rs`; libraries use `lib.rs`
+- `mod.rs` or named module files for submodules
+- Keep `main.rs` thin: parse args, build app, run
+- Integration tests in `tests/` directory; unit tests inline with `#[cfg(test)]`
+
+## Tooling
+
+| Tool | Purpose |
+|---|---|
+| rustfmt | Formatting |
+| clippy | Linting with actionable suggestions |
+| cargo test | Testing |
+| cargo bench | Benchmarking |
+| cargo audit | Dependency vulnerability scanning |
+| miri | Undefined behavior detection |
+
+## Ownership and Borrowing
+
+- Prefer borrowing (`&T`, `&mut T`) over ownership transfer when the caller keeps the data
+- Use `Clone` sparingly; understand the cost
+- Prefer `&str` over `String` in function parameters when no ownership is needed
+- Use `Cow<'_, str>` when a function may or may not need to allocate
+- Lifetime annotations: name them meaningfully when multiple lifetimes interact
+
+## Error Handling
+
+- Use `Result<T, E>` for recoverable errors
+- Define a crate-level error enum with `thiserror`
+- Use `anyhow` for application code where error types are less important
+- The `?` operator for propagation; add context with `.context("message")`
+- `panic!` only for programming errors (invariant violations), never for expected failures
+- Avoid `unwrap()` outside tests; use `expect("reason")` if failure is a bug
+
+## Patterns
+
+### Builder Pattern
+- Use for types with many optional parameters
+- `TypeBuilder::new().field(value).build() -> Result<Type>`
+- Validate in `build()`, not in individual setters
+
+### Type-State Pattern
+- Encode state transitions in the type system
+- Prevents invalid state at compile time
+- Use for protocols, workflows, and configuration
+
+### Newtype Pattern
+- Wrap primitive types to add type safety: `struct UserId(u64)`
+- Prevents mixing up parameters of the same underlying type
+- Implement `Deref` selectively; prefer explicit conversion methods
+
+## Async Rust
+
+- Use `tokio` for async runtime (or `async-std` if the project uses it)
+- `async fn` for I/O-bound operations
+- Avoid blocking in async context; use `tokio::task::spawn_blocking` for CPU work
+- Use `tokio::select!` for concurrent operations with cancellation
+- Structured concurrency with `JoinSet` or `tokio::join!`
+- Set timeouts on all async operations: `tokio::time::timeout`
+
+## Testing
+
+- Unit tests in the same file as the code: `#[cfg(test)] mod tests`
+- Integration tests in `tests/` directory
+- Use `#[test]` and `assert_eq!`, `assert!`
+- Property-based testing with `proptest` for complex invariants
+- `#[tokio::test]` for async tests
+- Mock traits with `mockall` or manual test doubles
+- Run `cargo test` and `cargo clippy` in CI
+
+## Performance
+
+- Zero-cost abstractions: iterators, generics, traits have no runtime overhead
+- Use iterators over manual loops; they optimize well
+- `Vec::with_capacity` when the size is known
+- Avoid `Box<dyn Trait>` in hot paths; prefer generics for static dispatch
+- Benchmark with `criterion` for statistical rigor
+- Profile with `perf`, `flamegraph`, or `cargo-instruments`
+
+## Unsafe
+
+- Minimize `unsafe` blocks; document the safety invariant as a comment
+- Prefer safe abstractions that encapsulate `unsafe` internally
+- Run Miri on unsafe code: `cargo +nightly miri test`
+- Review all `unsafe` blocks during code review with extra scrutiny
+- Use `#[deny(unsafe_code)]` at the crate level when possible
+
+## Security
+
+- `cargo audit` in CI to check for vulnerable dependencies
+- Use `secrecy` crate for secret values (prevents accidental logging)
+- Validate all external input at boundaries
+- Use `ring` or `rustcrypto` for cryptographic operations
+- Pin dependency versions in `Cargo.lock` (commit it for binaries)
+
+## Anti-Patterns
+
+- Overusing `clone()` to satisfy the borrow checker without understanding ownership
+- `unwrap()` in production code paths
+- Excessive lifetimes when owned types would be simpler
+- Fighting the borrow checker with `Rc<RefCell<T>>` everywhere
+- Premature optimization with `unsafe` when safe code is fast enough