@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/i18n-localization/SKILL.md

@@ -1,154 +1,169 @@
 ---
 name: i18n-localization
-description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
-allowed-tools: Read, Glob, Grep
+description: Implement internationalization and localization including RTL support, pluralization, date/number formatting, translation workflows, and locale-aware UI.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
-# i18n & Localization
+# I18N & Localization
 
-> Internationalization (i18n) and Localization (L10n) best practices.
+## Purpose
 
----
+Guide internationalization (i18n) and localization (l10n) implementation. Ensure applications can be adapted for different languages, regions, and cultural conventions without code changes.
 
-## 1. Core Concepts
+## When to Use
 
-| Term | Meaning |
-|------|---------|
-| **i18n** | Internationalization - making app translatable |
-| **L10n** | Localization - actual translations |
-| **Locale** | Language + Region (en-US, tr-TR) |
-| **RTL** | Right-to-left languages (Arabic, Hebrew) |
+- Adding multi-language support to an application
+- Implementing RTL (right-to-left) layout support
+- Handling dates, numbers, and currencies across locales
+- Setting up translation workflows and string management
+- Reviewing code for i18n readiness
+- Building locale-aware UI components
 
----
+## Instructions
 
-## 2. When to Use i18n
+### Step 1 — Externalize All User-Facing Strings
 
-| Project Type | i18n Needed? |
-|--------------|--------------|
-| Public web app | ✅ Yes |
-| SaaS product | ✅ Yes |
-| Internal tool | ⚠️ Maybe |
-| Single-region app | ⚠️ Consider future |
-| Personal project | ❌ Optional |
+**Never hardcode user-visible text**:
 
----
+```typescript
+// DON'T
+<button>Save Changes</button>
 
-## 3. Implementation Patterns
+// DO
+<button>{t('actions.save_changes')}</button>
+```
 
-### React (react-i18next)
+**String keys**:
 
-```tsx
-import { useTranslation } from 'react-i18next';
+- Use namespaced dot notation: `page.section.element`
+- Keys should be descriptive, not the English text
+- Group by feature/page, not by component
 
-function Welcome() {
-  const { t } = useTranslation();
-  return <h1>{t('welcome.title')}</h1>;
+**Message format** (ICU MessageFormat):
+
+```json
+{
+  "items.count": "{count, plural, =0 {No items} one {# item} other {# items}}",
+  "greeting": "Hello, {name}!",
+  "order.total": "Total: {total, number, currency}"
 }
 ```
 
-### Next.js (next-intl)
+### Step 2 — Handle Pluralization
 
-```tsx
-import { useTranslations } from 'next-intl';
+Different languages have different plural rules (Arabic has 6 plural forms):
 
-export default function Page() {
-  const t = useTranslations('Home');
-  return <h1>{t('title')}</h1>;
+```json
+{
+  "en": { "items": "{count, plural, one {# item} other {# items}}" },
+  "ar": {
+    "items": "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصراً} other {# عنصر}}"
+  }
 }
 ```
 
-### Python (gettext)
+Never build pluralization with ternaries — always use the ICU plural syntax or equivalent library (Intl.PluralRules).
 
-```python
-from gettext import gettext as _
+### Step 3 — Format Dates, Numbers, and Currencies
 
-print(_("Welcome to our app"))
-```
+Use `Intl` APIs — never format manually:
 
----
+```typescript
+// Date
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// → "15. Januar 2025"
 
-## 4. File Structure
+// Number
+new Intl.NumberFormat("ja-JP").format(1234567);
+// → "1,234,567"
 
-```
-locales/
-├── en/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-├── tr/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-└── ar/          # RTL
-    └── ...
+// Currency
+new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(
+  42.5,
+);
+// → "$42.50"
+
+// Relative time
+new Intl.RelativeTimeFormat("fr", { numeric: "auto" }).format(-1, "day");
+// → "hier"
 ```
 
----
+### Step 4 — Support RTL Languages
 
-## 5. Best Practices
+**CSS logical properties** (replace physical with logical):
 
-### DO ✅
+| Physical (DON'T)   | Logical (DO)          |
+| ------------------ | --------------------- |
+| `margin-left`      | `margin-inline-start` |
+| `padding-right`    | `padding-inline-end`  |
+| `text-align: left` | `text-align: start`   |
+| `float: left`      | `float: inline-start` |
+| `border-left`      | `border-inline-start` |
 
-- Use translation keys, not raw text
-- Namespace translations by feature
-- Support pluralization
-- Handle date/number formats per locale
-- Plan for RTL from the start
-- Use ICU message format for complex strings
+**Layout**:
 
-### DON'T ❌
+- Use `dir="auto"` on user-generated content
+- Set `<html dir="rtl" lang="ar">` at the document level
+- Flexbox and Grid respect `direction` automatically
+- Mirror icons that indicate direction (arrows, back buttons)
+- Don't mirror: logos, numbers, media controls, checkmarks
 
-- Hardcode strings in components
-- Concatenate translated strings
-- Assume text length (German is 30% longer)
-- Forget about RTL layout
-- Mix languages in same file
+### Step 5 — Translation Workflow
 
----
+**File structure**:
 
-## 6. Common Issues
+```
+locales/
+├── en/
+│   ├── common.json      (shared strings)
+│   ├── auth.json         (login/signup)
+│   └── dashboard.json    (dashboard page)
+├── fr/
+├── ja/
+└── ar/
+```
 
-| Issue | Solution |
-|-------|----------|
-| Missing translation | Fallback to default language |
-| Hardcoded strings | Use linter/checker script |
-| Date format | Use Intl.DateTimeFormat |
-| Number format | Use Intl.NumberFormat |
-| Pluralization | Use ICU message format |
+**Process**:
 
----
+1. Developer adds key + English string
+2. CI extracts new/changed keys automatically
+3. Strings sent to translators (Crowdin, Lokalise, or equivalent)
+4. Translations imported back as JSON/YAML
+5. CI validates: no missing keys, no untranslated strings, valid ICU syntax
 
-## 7. RTL Support
+**Rules**:
 
-```css
-/* CSS Logical Properties */
-.container {
-  margin-inline-start: 1rem;  /* Not margin-left */
-  padding-inline-end: 1rem;   /* Not padding-right */
-}
+- Never concatenate translated strings (`t('hello') + ' ' + name` breaks in many languages)
+- Provide context for translators (comments in message files)
+- Max string length varies by language (German ~30% longer than English)
+- Test with pseudo-localization (e.g., "Ŝàvé Çhàñgéŝ") to catch hardcoded strings
+
+## Output Format
 
-[dir="rtl"] .icon {
-  transform: scaleX(-1);
-}
 ```
+## I18N Assessment
+[current state and gaps]
 
----
+## Implementation
+[code changes for i18n support]
 
-## 8. Checklist
+## Translation Setup
+[file structure, workflow, tooling]
 
-Before shipping:
+## RTL Support
+[layout changes for bidirectional support]
+```
 
-- [ ] All user-facing strings use translation keys
-- [ ] Locale files exist for all supported languages
-- [ ] Date/number formatting uses Intl API
-- [ ] RTL layout tested (if applicable)
-- [ ] Fallback language configured
-- [ ] No hardcoded strings in components
+## Examples
 
----
+**User**: "Add multi-language support to our React app"
+
+**Response approach**: Set up react-intl or next-intl. Externalize all strings with namespaced keys. Configure locale detection (URL, browser, user preference). Set up ICU MessageFormat for plurals and interpolation. Show translation file structure.
 
-## Script
+**User**: "Our app needs to support Arabic"
 
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |
+**Response approach**: Add RTL support with CSS logical properties. Set `dir="rtl"` on html element. Audit all physical CSS properties. Mirror directional icons. Test with Arabic translations for text expansion.

package/workflows/powers/java-pro/POWER.md

@@ -5,39 +5,64 @@ name: "java-pro"
 description: "Use for modern Java backend and platform engineering with Java 25-era language/runtime practices."
 license: MIT
 metadata:
-  version: "1.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "java"
-  baseline: "Java SE 25"
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Java Pro
 
-## When to use
+## Purpose
+
+Expert-level guidance for modern Java backend and platform engineering. Covers records, sealed types, virtual threads (Project Loom), null handling, performance profiling, and production observability using current JDK practices.
+
+## When to Use
 
 - Building or modernizing Java backend services.
 - Designing JVM architecture for high-throughput systems.
-- Improving reliability, observability, and maintainability.
+- Improving reliability, observability, and maintainability of Java codebases.
+
+## Instructions
+
+1. **Clarify runtime target and deployment constraints** — confirm the JDK baseline approved by project policy and deployment environment before choosing language features.
+
+2. **Define module boundaries and API contracts** — separate domain, service, and infrastructure layers. Use records for immutable data carriers (API responses, DTOs, event payloads). Use sealed classes/interfaces for closed domain hierarchies with exhaustive pattern matching.
+
+3. **Implement with explicit null handling** — use `Optional<T>` for return types that may legitimately have no value, but never for parameters or fields. Use `@Nullable`/`@NonNull` annotations from JSpecify or Checker Framework. Fail fast with `Objects.requireNonNull()` at method entry. Do not return raw `null` from methods that could return `Optional` or empty collections because it creates silent NPE pathways.
+
+4. **Use virtual threads for blocking I/O workloads** — HTTP calls, database queries, and file reads benefit from virtual threads via `Executors.newVirtualThreadPerTaskExecutor()`. Do not use virtual threads for CPU-bound work because they share carrier threads and cause starvation. Do not use `synchronized` blocks in virtual-thread code because it causes carrier-thread pinning — use `ReentrantLock` instead.
+
+5. **Add structured logging and trace propagation** — capture request/job correlation IDs in logs and traces. Keep exception handling consistent between transport, service, and persistence layers. Do not expose stack traces in production responses.
+
+6. **Enforce dependency and API compatibility checks in CI** — use current JDK tooling, static analysis, and dependency verification. Separate transport DTOs from domain and persistence models to reduce cascade failures.
+
+7. **Profile before optimizing** — use `jcmd`, `async-profiler`, or JFR for production diagnostics without restart. Profile GC behavior with `-Xlog:gc*` before tuning heap sizes. Use escape analysis awareness to avoid large short-lived objects in hot loops. Prefer explicit timeouts, bulkheads, and retry budgets at I/O boundaries.
+
+8. **Add tests and performance checks for critical paths** — use JUnit 5, parameterized tests, and Testcontainers for integration testing. Do not use `Thread.sleep()` for retry logic because it blocks threads — use structured retry with backoff. Do not leak persistence entities directly into API contracts because it couples layers.
+
+9. **Do not use reflection-heavy magic when explicit code is clearer** because it hurts readability and debuggability. Do not build monolithic service classes with mixed responsibilities because they resist testing and change.
+
+## Output Format
+
+Produces Java code using records, sealed types, and modern JDK APIs with clear layer separation, explicit null handling, and structured error propagation. Includes virtual-thread-aware patterns where applicable.
 
-## Core workflow
+## References
 
-1. Clarify runtime target and deployment constraints.
-2. Define module boundaries and API contracts.
-3. Implement with clear domain/service/infrastructure separation.
-4. Add tests and performance checks for critical paths.
+| File                                     | Load when                                                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `references/virtual-threads-patterns.md` | Virtual thread adoption, carrier pinning avoidance, or Loom migration patterns need detail.              |
+| `references/records-sealed-types.md`     | Record design, sealed hierarchy modeling, or pattern matching with switch expressions need detail.       |
+| `references/stream-api-patterns.md`      | Stream pipeline design, collector patterns, parallel stream tradeoffs, or functional idioms need detail. |
+| `references/modern-testing.md`           | JUnit 5 patterns, parameterized tests, Testcontainers, or test architecture decisions need detail.       |
+| `references/gc-and-allocation.md`        | GC tuning, allocation profiling, escape analysis, or memory-sensitive design decisions need detail.      |
 
-## Baseline standards
+## Scripts
 
-- Use current LTS/JDK baseline approved by project policy.
-- Prefer records/sealed hierarchies where they simplify modeling.
-- Keep null-handling explicit; avoid silent NPE pathways.
-- Use structured logging and trace propagation.
-- Enforce dependency and API compatibility checks in CI.
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Avoid
+## Examples
 
-- Monolithic service classes with mixed responsibilities.
-- Reflection-heavy magic when explicit code is clearer.
-- Leaking persistence entities directly into API contracts.
+- "Migrate this blocking HTTP client code to use virtual threads with proper carrier-thread pinning avoidance."
+- "Refactor this service to use sealed classes and pattern matching instead of the visitor pattern."
+- "Design the null-handling strategy for this API layer using Optional returns and JSpecify annotations."
 ````

package/workflows/powers/java-pro/SKILL.md

@@ -3,38 +3,63 @@ name: "java-pro"
 description: "Use for modern Java backend and platform engineering with Java 25-era language/runtime practices."
 license: MIT
 metadata:
-  version: "1.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "java"
-  baseline: "Java SE 25"
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Java Pro
 
-## When to use
+## Purpose
+
+Expert-level guidance for modern Java backend and platform engineering. Covers records, sealed types, virtual threads (Project Loom), null handling, performance profiling, and production observability using current JDK practices.
+
+## When to Use
 
 - Building or modernizing Java backend services.
 - Designing JVM architecture for high-throughput systems.
-- Improving reliability, observability, and maintainability.
+- Improving reliability, observability, and maintainability of Java codebases.
+
+## Instructions
+
+1. **Clarify runtime target and deployment constraints** — confirm the JDK baseline approved by project policy and deployment environment before choosing language features.
+
+2. **Define module boundaries and API contracts** — separate domain, service, and infrastructure layers. Use records for immutable data carriers (API responses, DTOs, event payloads). Use sealed classes/interfaces for closed domain hierarchies with exhaustive pattern matching.
+
+3. **Implement with explicit null handling** — use `Optional<T>` for return types that may legitimately have no value, but never for parameters or fields. Use `@Nullable`/`@NonNull` annotations from JSpecify or Checker Framework. Fail fast with `Objects.requireNonNull()` at method entry. Do not return raw `null` from methods that could return `Optional` or empty collections because it creates silent NPE pathways.
+
+4. **Use virtual threads for blocking I/O workloads** — HTTP calls, database queries, and file reads benefit from virtual threads via `Executors.newVirtualThreadPerTaskExecutor()`. Do not use virtual threads for CPU-bound work because they share carrier threads and cause starvation. Do not use `synchronized` blocks in virtual-thread code because it causes carrier-thread pinning — use `ReentrantLock` instead.
+
+5. **Add structured logging and trace propagation** — capture request/job correlation IDs in logs and traces. Keep exception handling consistent between transport, service, and persistence layers. Do not expose stack traces in production responses.
+
+6. **Enforce dependency and API compatibility checks in CI** — use current JDK tooling, static analysis, and dependency verification. Separate transport DTOs from domain and persistence models to reduce cascade failures.
+
+7. **Profile before optimizing** — use `jcmd`, `async-profiler`, or JFR for production diagnostics without restart. Profile GC behavior with `-Xlog:gc*` before tuning heap sizes. Use escape analysis awareness to avoid large short-lived objects in hot loops. Prefer explicit timeouts, bulkheads, and retry budgets at I/O boundaries.
+
+8. **Add tests and performance checks for critical paths** — use JUnit 5, parameterized tests, and Testcontainers for integration testing. Do not use `Thread.sleep()` for retry logic because it blocks threads — use structured retry with backoff. Do not leak persistence entities directly into API contracts because it couples layers.
+
+9. **Do not use reflection-heavy magic when explicit code is clearer** because it hurts readability and debuggability. Do not build monolithic service classes with mixed responsibilities because they resist testing and change.
+
+## Output Format
+
+Produces Java code using records, sealed types, and modern JDK APIs with clear layer separation, explicit null handling, and structured error propagation. Includes virtual-thread-aware patterns where applicable.
 
-## Core workflow
+## References
 
-1. Clarify runtime target and deployment constraints.
-2. Define module boundaries and API contracts.
-3. Implement with clear domain/service/infrastructure separation.
-4. Add tests and performance checks for critical paths.
+| File                                     | Load when                                                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `references/virtual-threads-patterns.md` | Virtual thread adoption, carrier pinning avoidance, or Loom migration patterns need detail.              |
+| `references/records-sealed-types.md`     | Record design, sealed hierarchy modeling, or pattern matching with switch expressions need detail.       |
+| `references/stream-api-patterns.md`      | Stream pipeline design, collector patterns, parallel stream tradeoffs, or functional idioms need detail. |
+| `references/modern-testing.md`           | JUnit 5 patterns, parameterized tests, Testcontainers, or test architecture decisions need detail.       |
+| `references/gc-and-allocation.md`        | GC tuning, allocation profiling, escape analysis, or memory-sensitive design decisions need detail.      |
 
-## Baseline standards
+## Scripts
 
-- Use current LTS/JDK baseline approved by project policy.
-- Prefer records/sealed hierarchies where they simplify modeling.
-- Keep null-handling explicit; avoid silent NPE pathways.
-- Use structured logging and trace propagation.
-- Enforce dependency and API compatibility checks in CI.
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Avoid
+## Examples
 
-- Monolithic service classes with mixed responsibilities.
-- Reflection-heavy magic when explicit code is clearer.
-- Leaking persistence entities directly into API contracts.
+- "Migrate this blocking HTTP client code to use virtual threads with proper carrier-thread pinning avoidance."
+- "Refactor this service to use sealed classes and pattern matching instead of the visitor pattern."
+- "Design the null-handling strategy for this API layer using Optional returns and JSpecify annotations."

package/workflows/powers/javascript-pro/POWER.md

@@ -2,57 +2,70 @@
 ---
 inclusion: manual
 name: "javascript-pro"
-description: "Use for modern JavaScript architecture and implementation across browser, Node, and edge runtimes with ES2025+ practices."
+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: "ES2025+"
+  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.
+
+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.
+
+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.
+
+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.
+
+6. **Validate untrusted input at boundaries** — sanitize at system entry points such as API handlers and form inputs. Keep dependency surface intentionally small.
+
+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.
+
+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.
 
-## Core workflow
+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.
 
-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.
+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.
 
-## Baseline standards
+## Output Format
 
-- 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.
+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.
 
-## Implementation guidance
+## References
 
-- 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.
+| 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
 
-- `references/modern-syntax.md`
-- `references/async-patterns.md`
-- `references/modules.md`
-- `references/browser-apis.md`
-- `references/node-essentials.md`
+- "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."
 ````