@cubis/foundry 0.3.71 → 0.3.72

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

@@ -3,54 +3,65 @@ name: "golang-pro"
 description: "Use for modern Go services and tooling with Go 1.26-era language/runtime patterns, concurrency safety, and production operations."
 license: MIT
 metadata:
-  version: "2.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "go"
-  baseline: "Go 1.26"
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Golang Pro
 
-## When to use
+## Purpose
+
+Expert-level guidance for modern Go development covering APIs, workers, CLIs, and microservices. Focuses on explicit error handling, context-propagated concurrency, generics where they simplify, and production profiling discipline.
+
+## When to Use
 
 - Building APIs, workers, CLIs, and microservices in Go.
-- Designing concurrency with goroutines/channels/context.
-- Optimizing latency, allocations, and reliability.
+- Designing concurrency patterns with goroutines, channels, and context.
+- Optimizing latency, allocations, and reliability in Go services.
+
+## Instructions
+
+1. **Define package boundaries and interfaces** — keep interfaces small and accept them where consumed, not where implemented. Prefer composition over deep inheritance-like abstractions.
+
+2. **Pass `context.Context` as the first parameter** in all APIs that cross network or scheduling boundaries. Do not store contexts in structs because they represent request-scoped lifetimes.
+
+3. **Handle every error with actionable wrapping** — wrap with `%w` for traceable error chains. Define sentinel errors for well-known failure conditions. Use custom error types when errors carry structured context. Do not discard errors silently; document any intentional discard with a comment. Do not use stringly-typed error comparisons (`err.Error() == "something"`) because sentinel values and type assertions are safer and refactor-proof.
+
+4. **Design concurrency with clear ownership** — use channels for ownership transfer, not shared mutation. Choose sync primitives (`Mutex`, `RWMutex`, `atomic`) deliberately. Keep goroutine lifecycles bounded with cancellation via `select` with `ctx.Done()`. Bound worker pools with fixed goroutine counts reading from a shared channel. Use `errgroup.Group` for coordinated fan-out with shared error propagation.
+
+5. **Use generics where they simplify** — generics serve well when the abstraction covers 3+ distinct types. Prefer concrete types when a function has only one or two callers because generics add cognitive cost. Avoid deeply nested type parameter lists; if a generic needs 4+ parameters, break it into smaller pieces.
+
+6. **Test with table-driven subtests and race detection** — use `t.Run` for systematic input coverage. Run `go test -race -count=1 ./...` in CI. Use `httptest.NewServer` for HTTP handler tests. Use `t.Cleanup()` for teardown. Use `testing.B` benchmarks with `b.ReportAllocs()` to prove optimization impact.
+
+7. **Lint and format consistently** — use `golangci-lint` with `govet`, `staticcheck`, `errcheck`, `gosec`, and `revive` at minimum. Enforce `gofmt`/`goimports` in CI. Use `gofumpt` for stricter formatting.
+
+8. **Thread observability through the stack** — use structured logs with request IDs and trace context. Make cancellation, retries, and deadlines visible in logging. Reproduce concurrency issues with race tests and deterministic fixtures first.
 
-## Core workflow
+9. **Profile before optimizing** — benchmark hot paths with `testing.B` and `b.ReportAllocs()`. Use `pprof` (CPU, heap, goroutine, block, mutex) for production profiling. Do not fire-and-forget goroutines without a cancellation path because they leak resources. Do not use panic-based control flow because it circumvents explicit error handling. Do not create over-generalized interfaces without real callers because they add indirection without value.
 
-1. Define package boundaries and interfaces.
-2. Implement with explicit error handling and context propagation.
-3. Add tests and race checks for behavior under load.
-4. Profile before optimization.
+10. **Build for production** — use `go build -trimpath -ldflags='-s -w'` for release binaries. Keep `go.mod` tidy. Use `ko` or multi-stage Docker for container builds.
 
-## Baseline standards
+## Output Format
 
-- Keep APIs context-aware: pass `context.Context` first.
-- Handle every error with actionable wrapping.
-- Use table-driven tests and subtests for logic coverage.
-- Run `go test -race` for concurrency-sensitive paths.
-- Prefer composition over deep inheritance-like abstractions.
+Produces Go code following standard project layout with explicit error handling, context propagation, and bounded concurrency patterns. Includes table-driven tests and structured error types where applicable.
 
-## Implementation guidance
+## References
 
-- Use channels for ownership transfer, not shared mutation.
-- Choose sync primitives deliberately (`Mutex`, `RWMutex`, `atomic`).
-- Keep goroutine lifecycles bounded with cancellation.
-- Use generics where they simplify, not where they obscure.
-- Benchmark hot paths (`testing.B`, `pprof`) before tuning.
+| File                              | Load when                                                                     |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `references/concurrency.md`       | Concurrency ownership, channels, mutexes, or cancellation safety need detail. |
+| `references/generics.md`          | Generics tradeoffs or reusable type-safe helpers are in scope.                |
+| `references/interfaces.md`        | Interface boundaries and package seams need review.                           |
+| `references/testing.md`           | Test strategy, race checks, or benchmark setup is needed.                     |
+| `references/project-structure.md` | Package layout or service/module decomposition needs guidance.                |
 
-## Avoid
+## Scripts
 
-- Fire-and-forget goroutines without cancellation path.
-- Panic-based control flow.
-- Over-generalized interfaces without real callers.
+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/concurrency.md`
-- `references/generics.md`
-- `references/interfaces.md`
-- `references/testing.md`
-- `references/project-structure.md`
+- "Design the error handling strategy for this Go API service with custom error types and middleware-based error mapping."
+- "Refactor this unbounded goroutine fan-out into a bounded worker pool with context cancellation."
+- "Set up a table-driven test suite for this parser with race detection and benchmark coverage."

package/workflows/powers/graphql-architect/POWER.md

@@ -2,88 +2,70 @@
 ---
 inclusion: manual
 name: graphql-architect
-description: Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.
+description: "Use when designing GraphQL schemas, resolver boundaries, batching strategy, auth and policy enforcement, federation shape, query safety, and real-time graph behavior."
 license: MIT
 metadata:
-  author: https://github.com/Jeffallan
-  version: "1.0.0"
-  domain: api-architecture
-  triggers: GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader
-  role: architect
-  scope: design
-  output-format: schema
-  related-skills: api-designer, microservices-architect, database-optimizer
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # GraphQL Architect
 
-Senior GraphQL architect specializing in schema design and distributed graph architectures with deep expertise in Apollo Federation 2.5+, GraphQL subscriptions, and performance optimization.
+## Purpose
 
-## Role Definition
+Use when designing GraphQL schemas, resolver boundaries, batching strategy, auth and policy enforcement, federation shape, query safety, and real-time graph behavior.
 
-You are a senior GraphQL architect with 10+ years of API design experience. You specialize in Apollo Federation, schema-first design, and building type-safe API graphs that scale across teams and services. You master resolvers, DataLoader patterns, and real-time subscriptions.
+## When to Use
 
-## When to Use This Skill
+- Designing or refactoring GraphQL schemas and resolver structure.
+- Choosing batching, caching, federation, auth, and subscription behavior.
+- Reviewing query safety, nullability, and graph boundary decisions.
+- Converting a REST-shaped backend into a graph with deliberate tradeoffs.
 
-- Designing GraphQL schemas and type systems
-- Implementing Apollo Federation architectures
-- Building resolvers with DataLoader optimization
-- Creating real-time GraphQL subscriptions
-- Optimizing query complexity and performance
-- Setting up authentication and authorization
+## Instructions
 
-## Core Workflow
+1. Model the domain graph and choose what belongs in the schema, not the storage layer.
+2. Define nullability, pagination, mutation semantics, and auth ownership explicitly.
+3. Design resolver boundaries with batching and cache behavior in mind.
+4. Add query safety controls, policy checks, and subscription behavior where needed.
+5. Verify that the graph remains understandable for clients and operable for services.
 
-1. **Domain Modeling** - Map business domains to GraphQL type system
-2. **Design Schema** - Create types, interfaces, unions with federation directives
-3. **Implement Resolvers** - Write efficient resolvers with DataLoader patterns
-4. **Secure** - Add query complexity limits, depth limiting, field-level auth
-5. **Optimize** - Performance tune with caching, persisted queries, monitoring
+### Baseline standards
 
-## Reference Guide
+- Prefer schema clarity over exposing every backend shape.
+- Use batching to prevent N+1 patterns.
+- Keep nullability intentional and documented.
+- Keep auth and permission rules explicit at schema or resolver boundaries.
+- Treat federation and subscriptions as architectural choices, not defaults.
+- Make query cost and auth behavior explicit.
 
-Load detailed guidance based on context:
+### Constraints
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Schema Design | `references/schema-design.md` | Types, interfaces, unions, enums, input types |
-| Resolvers | `references/resolvers.md` | Resolver patterns, context, DataLoader, N+1 |
-| Federation | `references/federation.md` | Apollo Federation, subgraphs, entities, directives |
-| Subscriptions | `references/subscriptions.md` | Real-time updates, WebSocket, pub/sub patterns |
-| Security | `references/security.md` | Query depth, complexity analysis, authentication |
-| REST Migration | `references/migration-from-rest.md` | Migrating REST APIs to GraphQL |
+- Avoid rEST-shaped GraphQL that only mirrors endpoint habits.
+- Avoid resolver logic that hides unbounded fan-out.
+- Avoid ambiguous nullability and inconsistent mutation payloads.
+- Avoid authorization that exists only in the client or gateway with no resolver ownership.
+- Avoid adding federation complexity before single-graph boundaries are clear.
 
-## Constraints
+## Output Format
 
-### MUST DO
-- Use schema-first design approach
-- Implement proper nullable field patterns
-- Use DataLoader for batching and caching
-- Add query complexity analysis
-- Document all types and fields
-- Follow GraphQL naming conventions (camelCase)
-- Use federation directives correctly
-- Provide example queries for all operations
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### MUST NOT DO
-- Create N+1 query problems
-- Skip query depth limiting
-- Expose internal implementation details
-- Use REST patterns in GraphQL
-- Return null for non-nullable fields
-- Skip error handling in resolvers
-- Hardcode authorization logic
-- Ignore schema validation
+## References
 
-## Output Templates
+Load on demand. Do not preload all reference files.
 
-When implementing GraphQL features, provide:
-1. Schema definition (SDL with types and directives)
-2. Resolver implementation (with DataLoader patterns)
-3. Query/mutation/subscription examples
-4. Brief explanation of design decisions
+| File | Load when |
+| --- | --- |
+| `references/schema-resolver-checklist.md` | You need a more detailed checklist for schema shape, nullability, batching, auth and policy, subscriptions, federation, and query safety. |
 
-## Knowledge Reference
+## Scripts
 
-Apollo Server, Apollo Federation 2.5+, GraphQL SDL, DataLoader, GraphQL Subscriptions, WebSocket, Redis pub/sub, schema composition, query complexity, persisted queries, schema stitching, type generation
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with graphql architect best practices in this project"
+- "Review my graphql architect implementation for issues"
 ````

package/workflows/powers/graphql-architect/SKILL.md

@@ -1,86 +1,68 @@
 ---
 name: graphql-architect
-description: Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.
+description: "Use when designing GraphQL schemas, resolver boundaries, batching strategy, auth and policy enforcement, federation shape, query safety, and real-time graph behavior."
 license: MIT
 metadata:
-  author: https://github.com/Jeffallan
-  version: "1.0.0"
-  domain: api-architecture
-  triggers: GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader
-  role: architect
-  scope: design
-  output-format: schema
-  related-skills: api-designer, microservices-architect, database-optimizer
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # GraphQL Architect
 
-Senior GraphQL architect specializing in schema design and distributed graph architectures with deep expertise in Apollo Federation 2.5+, GraphQL subscriptions, and performance optimization.
+## Purpose
 
-## Role Definition
+Use when designing GraphQL schemas, resolver boundaries, batching strategy, auth and policy enforcement, federation shape, query safety, and real-time graph behavior.
 
-You are a senior GraphQL architect with 10+ years of API design experience. You specialize in Apollo Federation, schema-first design, and building type-safe API graphs that scale across teams and services. You master resolvers, DataLoader patterns, and real-time subscriptions.
+## When to Use
 
-## When to Use This Skill
+- Designing or refactoring GraphQL schemas and resolver structure.
+- Choosing batching, caching, federation, auth, and subscription behavior.
+- Reviewing query safety, nullability, and graph boundary decisions.
+- Converting a REST-shaped backend into a graph with deliberate tradeoffs.
 
-- Designing GraphQL schemas and type systems
-- Implementing Apollo Federation architectures
-- Building resolvers with DataLoader optimization
-- Creating real-time GraphQL subscriptions
-- Optimizing query complexity and performance
-- Setting up authentication and authorization
+## Instructions
 
-## Core Workflow
+1. Model the domain graph and choose what belongs in the schema, not the storage layer.
+2. Define nullability, pagination, mutation semantics, and auth ownership explicitly.
+3. Design resolver boundaries with batching and cache behavior in mind.
+4. Add query safety controls, policy checks, and subscription behavior where needed.
+5. Verify that the graph remains understandable for clients and operable for services.
 
-1. **Domain Modeling** - Map business domains to GraphQL type system
-2. **Design Schema** - Create types, interfaces, unions with federation directives
-3. **Implement Resolvers** - Write efficient resolvers with DataLoader patterns
-4. **Secure** - Add query complexity limits, depth limiting, field-level auth
-5. **Optimize** - Performance tune with caching, persisted queries, monitoring
+### Baseline standards
 
-## Reference Guide
+- Prefer schema clarity over exposing every backend shape.
+- Use batching to prevent N+1 patterns.
+- Keep nullability intentional and documented.
+- Keep auth and permission rules explicit at schema or resolver boundaries.
+- Treat federation and subscriptions as architectural choices, not defaults.
+- Make query cost and auth behavior explicit.
 
-Load detailed guidance based on context:
+### Constraints
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Schema Design | `references/schema-design.md` | Types, interfaces, unions, enums, input types |
-| Resolvers | `references/resolvers.md` | Resolver patterns, context, DataLoader, N+1 |
-| Federation | `references/federation.md` | Apollo Federation, subgraphs, entities, directives |
-| Subscriptions | `references/subscriptions.md` | Real-time updates, WebSocket, pub/sub patterns |
-| Security | `references/security.md` | Query depth, complexity analysis, authentication |
-| REST Migration | `references/migration-from-rest.md` | Migrating REST APIs to GraphQL |
+- Avoid rEST-shaped GraphQL that only mirrors endpoint habits.
+- Avoid resolver logic that hides unbounded fan-out.
+- Avoid ambiguous nullability and inconsistent mutation payloads.
+- Avoid authorization that exists only in the client or gateway with no resolver ownership.
+- Avoid adding federation complexity before single-graph boundaries are clear.
 
-## Constraints
+## Output Format
 
-### MUST DO
-- Use schema-first design approach
-- Implement proper nullable field patterns
-- Use DataLoader for batching and caching
-- Add query complexity analysis
-- Document all types and fields
-- Follow GraphQL naming conventions (camelCase)
-- Use federation directives correctly
-- Provide example queries for all operations
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### MUST NOT DO
-- Create N+1 query problems
-- Skip query depth limiting
-- Expose internal implementation details
-- Use REST patterns in GraphQL
-- Return null for non-nullable fields
-- Skip error handling in resolvers
-- Hardcode authorization logic
-- Ignore schema validation
+## References
 
-## Output Templates
+Load on demand. Do not preload all reference files.
 
-When implementing GraphQL features, provide:
-1. Schema definition (SDL with types and directives)
-2. Resolver implementation (with DataLoader patterns)
-3. Query/mutation/subscription examples
-4. Brief explanation of design decisions
+| File | Load when |
+| --- | --- |
+| `references/schema-resolver-checklist.md` | You need a more detailed checklist for schema shape, nullability, batching, auth and policy, subscriptions, federation, and query safety. |
 
-## Knowledge Reference
+## Scripts
 
-Apollo Server, Apollo Federation 2.5+, GraphQL SDL, DataLoader, GraphQL Subscriptions, WebSocket, Redis pub/sub, schema composition, query complexity, persisted queries, schema stitching, type generation
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with graphql architect best practices in this project"
+- "Review my graphql architect implementation for issues"

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

@@ -2,156 +2,171 @@
 ---
 inclusion: manual
 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.
 ````