@cubis/foundry 0.3.67 → 0.3.69

package/workflows/skills/java-pro/references/stream-api-patterns.md

@@ -0,0 +1,182 @@
+# Stream API Patterns
+
+## Stream Pipeline Design
+
+Streams are lazy, single-use data pipelines. Design them as declaration of intent, not imperative loops.
+
+```java
+// Transform and collect
+List<String> activeEmails = users.stream()
+    .filter(User::isActive)
+    .map(User::email)
+    .map(String::toLowerCase)
+    .distinct()
+    .sorted()
+    .toList(); // unmodifiable list (Java 16+)
+
+// Early termination — streams short-circuit
+Optional<User> admin = users.stream()
+    .filter(u -> u.role() == Role.ADMIN)
+    .findFirst(); // stops iteration at first match
+```
+
+## Collector Patterns
+
+```java
+// Group by key
+Map<Department, List<Employee>> byDept = employees.stream()
+    .collect(Collectors.groupingBy(Employee::department));
+
+// Group and transform values
+Map<Department, List<String>> namesByDept = employees.stream()
+    .collect(Collectors.groupingBy(
+        Employee::department,
+        Collectors.mapping(Employee::name, Collectors.toList())
+    ));
+
+// Partition (boolean grouping)
+Map<Boolean, List<Order>> partitioned = orders.stream()
+    .collect(Collectors.partitioningBy(o -> o.total() > 100));
+
+// Statistics
+DoubleSummaryStatistics stats = orders.stream()
+    .collect(Collectors.summarizingDouble(Order::total));
+// stats.getAverage(), stats.getMax(), stats.getCount()
+
+// String joining
+String csv = users.stream()
+    .map(User::name)
+    .collect(Collectors.joining(", ", "[", "]")); // [Alice, Bob, Charlie]
+
+// Collecting to Map with merge function
+Map<String, Integer> wordCounts = words.stream()
+    .collect(Collectors.toMap(
+        w -> w,
+        w -> 1,
+        Integer::sum // merge function for duplicate keys
+    ));
+```
+
+## `Optional` Integration
+
+```java
+// flatMap to chain optional-returning operations
+Optional<String> city = getUserById(id)
+    .flatMap(User::address)
+    .map(Address::city);
+
+// orElseGet for lazy default
+String name = findUser(id)
+    .map(User::name)
+    .orElseGet(() -> fetchDefaultName()); // lambda called only if empty
+
+// Stream from Optional (Java 9+)
+List<User> admins = userIds.stream()
+    .map(this::findUser)            // Stream<Optional<User>>
+    .flatMap(Optional::stream)       // Stream<User> — drops empties
+    .filter(u -> u.role() == Role.ADMIN)
+    .toList();
+```
+
+## Parallel Streams — When and When Not
+
+```java
+// USE parallel when:
+// - Large dataset (10,000+ elements)
+// - CPU-bound operations per element
+// - No shared mutable state
+// - Order doesn't matter (or use forEachOrdered)
+long count = largeDataset.parallelStream()
+    .filter(this::expensiveComputation) // CPU-bound
+    .count();
+
+// DO NOT USE parallel when:
+// - Small datasets (overhead exceeds benefit)
+// - I/O-bound operations (use virtual threads instead)
+// - Operations have side effects or shared mutable state
+// - Order is important and unordered() is not acceptable
+// - Inside a web request handler (contends with other requests)
+
+// Parallel with custom pool (isolate from ForkJoinPool.commonPool)
+ForkJoinPool customPool = new ForkJoinPool(4);
+List<Result> results = customPool.submit(() ->
+    items.parallelStream()
+        .map(this::process)
+        .toList()
+).get();
+```
+
+## Stream Gotchas
+
+```java
+// Streams are single-use — cannot reuse
+Stream<String> stream = list.stream().filter(s -> s.length() > 3);
+stream.count();   // OK
+stream.toList();  // IllegalStateException: stream has already been operated upon
+
+// Side effects in map/filter are bugs
+// BAD — mutation inside map
+List<String> results = new ArrayList<>();
+items.stream().map(i -> {
+    results.add(i.name()); // side effect!
+    return i.transform();
+}).toList();
+
+// GOOD — collect, don't mutate
+List<String> names = items.stream().map(Item::name).toList();
+List<Transformed> transformed = items.stream().map(Item::transform).toList();
+
+// flatMap for one-to-many
+List<String> allTags = articles.stream()
+    .flatMap(a -> a.tags().stream()) // flatten List<List<String>> → List<String>
+    .distinct()
+    .toList();
+```
+
+## Custom Collectors
+
+```java
+// Collector that builds a comma-separated string with limit
+Collector<String, ?, String> limitedJoin(int limit) {
+    return Collector.of(
+        () -> new StringJoiner(", "),
+        (joiner, item) -> {
+            if (joiner.length() < limit) joiner.add(item);
+        },
+        StringJoiner::merge,
+        StringJoiner::toString
+    );
+}
+
+// Teeing collector — two collectors in one pass (Java 12+)
+record Stats(long count, double average) {}
+
+Stats stats = numbers.stream().collect(
+    Collectors.teeing(
+        Collectors.counting(),
+        Collectors.averagingDouble(Double::doubleValue),
+        Stats::new
+    )
+);
+```
+
+## Functional Patterns
+
+```java
+// Method references over lambdas when possible
+names.stream().map(String::toUpperCase)      // clearer than s -> s.toUpperCase()
+users.stream().filter(User::isActive)        // clearer than u -> u.isActive()
+items.stream().sorted(Comparator.comparing(Item::price))
+
+// Predicate composition
+Predicate<User> isActive = User::isActive;
+Predicate<User> isAdmin = u -> u.role() == Role.ADMIN;
+Predicate<User> activeAdmin = isActive.and(isAdmin);
+
+users.stream().filter(activeAdmin).toList();
+
+// Function composition
+Function<String, String> normalize = String::toLowerCase;
+Function<String, String> trim = String::strip;
+Function<String, String> clean = normalize.andThen(trim);
+```

package/workflows/skills/java-pro/references/virtual-threads-patterns.md

@@ -0,0 +1,120 @@
+# Virtual Threads Patterns
+
+## When to Use Virtual Threads
+
+Virtual threads (Project Loom) are lightweight threads managed by the JVM. They excel at blocking I/O workloads where the thread spends most of its time waiting.
+
+```java
+// Task-per-request server — ideal for virtual threads
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    ServerSocket server = new ServerSocket(8080);
+    while (true) {
+        Socket socket = server.accept();
+        executor.submit(() -> handleRequest(socket));
+    }
+}
+
+// Parallel I/O operations
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Response>> futures = urls.stream()
+        .map(url -> executor.submit(() -> httpClient.send(url)))
+        .toList();
+
+    List<Response> responses = futures.stream()
+        .map(f -> {
+            try { return f.get(10, TimeUnit.SECONDS); }
+            catch (Exception e) { throw new RuntimeException(e); }
+        })
+        .toList();
+}
+```
+
+## Structured Concurrency (Preview)
+
+```java
+// StructuredTaskScope for coordinated subtasks
+Response handleRequest(Request req) throws Exception {
+    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+        Subtask<User> userTask = scope.fork(() -> fetchUser(req.userId()));
+        Subtask<List<Order>> ordersTask = scope.fork(() -> fetchOrders(req.userId()));
+
+        scope.join();           // wait for both
+        scope.throwIfFailed();  // propagate first failure
+
+        return new Response(userTask.get(), ordersTask.get());
+    }
+}
+
+// ShutdownOnSuccess — return first successful result
+String fetchFromAnyMirror(List<String> mirrors) throws Exception {
+    try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {
+        for (String mirror : mirrors) {
+            scope.fork(() -> download(mirror));
+        }
+        scope.join();
+        return scope.result();
+    }
+}
+```
+
+## Carrier Thread Pinning
+
+Virtual threads run on carrier (platform) threads. Certain operations "pin" the virtual thread to its carrier, preventing other virtual threads from using that carrier.
+
+```java
+// BAD — synchronized pins the carrier thread
+synchronized (lock) {
+    database.query(sql); // blocking I/O while pinned = carrier starvation
+}
+
+// GOOD — ReentrantLock does not pin
+private final ReentrantLock lock = new ReentrantLock();
+
+void safeQuery(String sql) {
+    lock.lock();
+    try {
+        database.query(sql); // virtual thread can unmount during I/O
+    } finally {
+        lock.unlock();
+    }
+}
+
+// Detect pinning in tests/staging
+// JVM flag: -Djdk.tracePinnedThreads=full
+// This prints stack traces when a virtual thread is pinned
+```
+
+## Thread-Local Alternatives
+
+Virtual threads are cheap — thousands may exist simultaneously. Thread-local variables consume memory per virtual thread.
+
+```java
+// BAD — thread-local wastes memory across thousands of virtual threads
+private static final ThreadLocal<SimpleDateFormat> formatter =
+    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));
+
+// GOOD — use scoped values (Preview) for request-scoped data
+private static final ScopedValue<RequestContext> CONTEXT = ScopedValue.newInstance();
+
+void handleRequest(Request req) {
+    ScopedValue.runWhere(CONTEXT, new RequestContext(req.traceId()), () -> {
+        processRequest(); // CONTEXT.get() available in all called methods
+    });
+}
+
+// GOOD — use immutable thread-safe formatters
+private static final DateTimeFormatter FORMATTER =
+    DateTimeFormatter.ofPattern("yyyy-MM-dd");
+```
+
+## Migration Checklist
+
+When migrating from platform threads to virtual threads:
+
+1. Replace `Executors.newFixedThreadPool(N)` with `Executors.newVirtualThreadPerTaskExecutor()`.
+2. Replace `synchronized` blocks around I/O with `ReentrantLock`.
+3. Audit thread-local usage — remove or replace with scoped values.
+4. Remove thread-pool sizing tuning — virtual threads do not need pool size limits.
+5. Keep semaphores for resource bounding (database connections, API rate limits).
+6. Run with `-Djdk.tracePinnedThreads=full` to identify remaining pinning.
+7. Verify that native libraries called via JNI do not hold monitors during blocking.

package/workflows/skills/javascript-pro/SKILL.md

@@ -3,73 +3,66 @@ name: "javascript-pro"
 description: "Use for modern JavaScript architecture and implementation across browser, Node, and edge runtimes with runtime-aware production practices."
 license: MIT
 metadata:
-  version: "2.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "javascript"
-  baseline: "Runtime-policy baseline (Node/browser/edge)"
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # JavaScript Pro
 
-## When to use
+## Purpose
+
+Expert-level guidance for modern JavaScript development across browser, Node.js, and edge runtimes. Covers module design, async orchestration, runtime-specific patterns, and production-grade error handling with a focus on runtime-aware code that respects platform boundaries.
+
+## When to Use
 
 - Implementing feature work in plain JavaScript.
 - Refactoring legacy JS toward modern modules and async flows.
-- Improving performance and reliability in browser/Node runtimes.
+- Improving performance and reliability in browser, Node, or edge runtimes.
+- Serving as the language baseline before framework-specific skills are loaded.
+
+## Instructions
+
+1. **Confirm runtime constraints** — identify browser targets, Node version, or edge runtime before choosing APIs or module formats. Runtime determines available features and performance characteristics.
+
+2. **Choose module boundaries and format** — prefer ESM (`import`/`export`) for new code. Configure `"type": "module"` in `package.json`. Keep modules focused to one responsibility. Use barrel exports (`index.js`) only for the public API to preserve tree-shaking.
 
-## When not to use
+3. **Design async strategy** — use `AbortSignal` and `AbortController` for cancellable operations. Use `Promise.allSettled()` when all results matter regardless of individual failures. Limit concurrent operations with semaphore patterns to prevent resource exhaustion.
 
-- Type-driven architecture work where TypeScript is the actual project language.
-- Database-only investigation with no JavaScript runtime behavior involved.
-- One-off shell automation that should remain shell-native.
+4. **Implement with explicit error and cancellation handling** — always attach `.catch()` or use `try/catch` in async flows. Do not leave promise rejections unhandled because they terminate Node.js processes and cause silent failures in browsers.
 
-## Core workflow
+5. **Keep side effects at module edges** — pure logic belongs in reusable modules. Side-effectful initialization at module top-level prevents tree-shaking and complicates testing.
 
-1. Confirm runtime constraints (browser targets, Node/edge version).
-2. Choose module boundaries and async strategy.
-3. Implement with explicit error and cancellation handling.
-4. Verify behavior with tests and runtime checks.
+6. **Validate untrusted input at boundaries** — sanitize at system entry points such as API handlers and form inputs. Keep dependency surface intentionally small.
 
-## Baseline standards
+7. **Use runtime-appropriate tooling** — Vitest or `node --test` for testing, Biome or ESLint for linting, Vite or esbuild for bundling. Use lockfile-based installs (`npm ci`, `pnpm install --frozen-lockfile`) in CI. Enable `corepack` for consistent package manager versions.
 
-- Prefer ESM for new code unless compatibility blocks it.
-- Use `AbortSignal` for cancellable async operations.
-- Keep side effects at edges; pure logic in reusable modules.
-- Validate untrusted input at boundaries.
-- Keep dependency surface intentionally small.
+8. **Debug in the target environment** — reproduce runtime-specific failures in the exact target (browser, Node, or edge). Use structured logging with consistent error shapes. Profile with Chrome DevTools or `node --prof` before redesigning hot paths.
 
-## Implementation guidance
+9. **Optimize deliberately** — use streams for large payloads to avoid memory spikes. Use `Promise.all` for independent parallel operations. Use dynamic `import()` for code-splitting heavy modules. Do not use UA sniffing in browser code because feature detection is more reliable and maintainable.
 
-- Use `Promise.all` for independent parallel operations.
-- Use structured logging and consistent error shapes.
-- Use streams for large payloads to avoid memory spikes.
-- Use feature detection, not UA sniffing, in browser code.
+10. **Do not use heavy framework coupling in low-level modules** because it prevents reuse. Do not allow copy-paste utility proliferation without consolidation because it causes drift and duplication.
 
-## Debugging and observability
+## Output Format
 
-- Reproduce runtime-specific failures in the exact target environment: browser, Node, or edge.
-- Surface async failures with structured errors and explicit logging context.
-- Use performance tooling before redesigning hot paths or caching strategy.
+Produces JavaScript code following ESM module conventions with explicit async error handling, runtime-appropriate API usage, and clear module boundaries. Includes structured error objects and cancellation support where applicable.
 
-## Performance and reliability
+## References
 
-- Keep bundle/runtime boundaries explicit so shared code does not assume unavailable APIs.
-- Bound parallelism and cancellation for network-heavy flows.
-- Prefer streaming, chunking, and incremental parsing for large payloads.
+| File                            | Load when                                                                   |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| `references/modern-syntax.md`   | Choosing modern syntax/features for current runtime targets.                |
+| `references/async-patterns.md`  | Cancellation, retries, concurrency, or promise orchestration needs detail.  |
+| `references/modules.md`         | ESM/CJS/module-boundary tradeoffs are in scope.                             |
+| `references/browser-apis.md`    | Browser-specific APIs, capability checks, or UX/runtime constraints matter. |
+| `references/node-essentials.md` | Node runtime behavior, streams, files, or process concerns matter.          |
 
-## Avoid
+## Scripts
 
-- Silent promise rejections.
-- Heavy framework coupling in low-level modules.
-- Copy-paste utility proliferation without consolidation.
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Reference files
+## Examples
 
-| File | Load when |
-| --- | --- |
-| `references/modern-syntax.md` | Choosing modern syntax/features for current runtime targets. |
-| `references/async-patterns.md` | Cancellation, retries, concurrency, or promise orchestration needs detail. |
-| `references/modules.md` | ESM/CJS/module-boundary tradeoffs are in scope. |
-| `references/browser-apis.md` | Browser-specific APIs, capability checks, or UX/runtime constraints matter. |
-| `references/node-essentials.md` | Node runtime behavior, streams, files, or process concerns matter. |
+- "Refactor this callback-heavy Express handler to use async/await with proper error handling and AbortController for timeout."
+- "Design the module structure for a shared utility library that needs to support both ESM and CJS consumers."
+- "Optimize this Node.js data pipeline to use streams instead of loading the full dataset into memory."

package/workflows/skills/kotlin-pro/SKILL.md

@@ -3,62 +3,61 @@ name: "kotlin-pro"
 description: "Use for modern Kotlin backend/mobile/shared code with Kotlin 2.3-era language tooling and production patterns."
 license: MIT
 metadata:
-  version: "1.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "kotlin"
-  baseline: "Kotlin 2.3 line (2.2.20+ compatible)"
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Kotlin Pro
 
-## When to use
+## Purpose
+
+Expert-level guidance for modern Kotlin development across JVM, Android, and multiplatform targets. Covers null safety, coroutine-based concurrency, Flow patterns, sealed type hierarchies, and Kotlin Multiplatform architecture with production testing discipline.
+
+## When to Use
 
 - Building Kotlin services or Android/shared modules.
-- Designing coroutine-based async flows.
-- Improving null-safety and domain model clarity.
+- Designing coroutine-based async flows and reactive patterns.
+- Improving null-safety, domain model clarity, and testability.
+
+## Instructions
 
-## When not to use
+1. **Establish target platform** — confirm JVM, Android, or Kotlin Multiplatform before choosing runtime-specific APIs. Put shared logic in `commonMain`; platform-specific implementations in `androidMain`/`iosMain`/`jvmMain`.
 
-- Frontend-only work with no Kotlin/JVM/Android/shared module in scope.
-- Database-only tuning without Kotlin code changes.
-- Tiny scripts that should stay in existing project tooling.
+2. **Design types with null safety** — keep nullability explicit. Prefer non-null types by default; use `?` only when null is valid domain state. Use `sealed class`/`sealed interface` for closed type hierarchies with exhaustive `when`. Use `data class` for value objects. Use `value class` for type-safe wrappers with zero runtime overhead. Do not use `!!` (forced non-null) in production code because it crashes at runtime — use `requireNotNull` with a message or safe alternatives (`?.`, `?:`, `let`).
 
-## Core workflow
+3. **Model concurrency with structured coroutines** — always launch coroutines in a scope with clear ownership (`viewModelScope`, `lifecycleScope`, custom `CoroutineScope`). Use `supervisorScope` when child failures should not cancel siblings. Use `withContext(Dispatchers.IO)` for blocking I/O. Use `withTimeout` for time-bounded operations. Respect cancellation by checking `isActive` in loops and letting `CancellationException` propagate. Do not use `GlobalScope` because it breaks structured concurrency and hides lifecycle bugs. Do not use `runBlocking` on the main thread because it deadlocks on Android and blocks server threads.
 
-1. Establish target platform (JVM/Android/multiplatform).
-2. Define domain types and boundary contracts first.
-3. Implement with coroutine/flow patterns where appropriate.
-4. Validate with tests and static analysis.
+4. **Use Flow for reactive streams** — use `StateFlow` for observable state; `SharedFlow` for events. Use `stateIn`/`shareIn` to share upstream flows. Prefer `flow {}` for cold streams; `channelFlow` when coroutine interleaving is needed. Use `flowOn(Dispatchers.IO)` for upstream context shifting. Handle backpressure with `conflate()`, `buffer()`, or `collectLatest`.
 
-## Baseline standards
+5. **Keep serialization and transport separate from domain** — use `kotlinx.serialization` for cross-platform serialization (not Gson or Moshi in multiplatform code). Keep platform boundary interfaces thin; heavy logic belongs in common code. Use `expect`/`actual` declarations for platform abstractions.
 
-- Keep nullability explicit; avoid forced non-null assertions.
-- Prefer immutable data models and pure transforms.
-- Use structured concurrency and clear scope ownership.
-- Keep serialization and transport models separate from domain.
-- Use dependency boundaries that support modular testing.
+6. **Use extensions and DSLs judiciously** — prefer member functions for core type behavior; extensions for cross-cutting concerns. Scope extensions to the narrowest visibility. Use receiver-based DSLs for configuration blocks. Do not overuse extension properties because functions are more discoverable in IDE completion.
 
-## Debugging and observability
+7. **Validate with tests, detekt, and ktlint** — keep coroutine context, dispatcher use, and cancellation visible in logs and traces. Use `-Dkotlinx.coroutines.debug` for coroutine creation stack traces in development. Use `CoroutineExceptionHandler` at scope boundaries. Bound coroutine fan-out with `limitedParallelism` or `Semaphore`. Do not launch coroutines without lifecycle ownership because it causes leaks on Android and servers.
 
-- Keep coroutine context, dispatcher use, and cancellation visible in logs/traces.
-- Reproduce lifecycle-related failures with focused tests before broader rewrites.
-- Prefer deterministic `Flow`/coroutine tests for race-prone logic.
+8. **Optimize with measurement** — use `Sequence` for lazy evaluation of large collections; `List` for small, eager operations. Prefer `buildList`, `buildMap`, `buildSet` for efficient construction. Use `value class` for primitive wrappers in hot paths. Do not allow platform-specific leakage into shared/core modules because it breaks multiplatform portability. Measure with profiling tools before micro-optimizing.
 
-## Performance and reliability
+## Output Format
 
-- Bound coroutine fan-out and avoid hidden blocking on default dispatchers.
-- Keep Android/shared/JVM boundaries explicit to avoid platform leakage.
-- Favor allocation-light data flows in hot paths and measure before micro-optimizing.
+Produces Kotlin code using data classes, sealed hierarchies, structured coroutines, and Flow patterns with explicit null safety and platform-appropriate architecture. Includes multiplatform separation where applicable.
 
 ## References
 
-| File | Load when |
-| --- | --- |
-| `references/operational-baseline.md` | You need Kotlin coroutine, modularity, testing, and production guardrails. |
+| File                                      | Load when                                                                                               |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `references/operational-baseline.md`      | You need Kotlin coroutine, modularity, testing, and production guardrails.                              |
+| `references/coroutine-patterns.md`        | You need structured concurrency, scope management, dispatcher selection, or cancellation design.        |
+| `references/flow-and-channels.md`         | You need StateFlow/SharedFlow patterns, reactive streams, backpressure, or channel-based communication. |
+| `references/sealed-types-and-dsl.md`      | You need sealed class hierarchies, value classes, pattern matching, or DSL builder patterns.            |
+| `references/multiplatform-and-testing.md` | You need KMP architecture, expect/actual patterns, or coroutine test strategies.                        |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Avoid
+## Examples
 
-- Coroutine launches without lifecycle ownership.
-- Platform-specific leakage into shared/core modules.
-- Overusing extension magic that hurts readability.
+- "Design a coroutine-based repository layer with StateFlow for UI state and proper cancellation handling."
+- "Refactor this Java-style service to use sealed classes, when expressions, and value classes for type safety."
+- "Set up the Kotlin Multiplatform module structure with shared business logic and platform-specific implementations."