@cubis/foundry 0.3.67 → 0.3.69

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/swift-pro/references/testing-and-packages.md

@@ -0,0 +1,192 @@
+# Testing and Packages
+
+## Swift Testing framework
+
+### Basic test structure
+
+```swift
+import Testing
+
+@Test("User creation sets default role")
+func userCreationDefault() {
+    let user = User(name: "Alice")
+    #expect(user.role == .viewer)
+}
+
+@Test("Deposit increases balance")
+func depositIncreasesBalance() async throws {
+    let account = BankAccount(balance: 100)
+    try await account.deposit(50)
+    let balance = await account.balance
+    #expect(balance == 150)
+}
+```
+
+- Use `@Test` attribute with descriptive display names.
+- Use `#expect` for assertions — clearer failure messages than XCTest.
+- Use `#require` for preconditions that should abort the test on failure.
+
+### Parameterized tests
+
+```swift
+@Test("Parse valid integers", arguments: [
+    ("42", 42),
+    ("-1", -1),
+    ("0", 0),
+])
+func parseValid(input: String, expected: Int) throws {
+    let result = try parse(input)
+    #expect(result == expected)
+}
+```
+
+- Use `arguments:` to run the same test logic across multiple inputs.
+- Each argument combination runs as a separate test case with individual pass/fail.
+
+### Test organization with suites
+
+```swift
+@Suite("User Repository")
+struct UserRepositoryTests {
+    let repo: MockUserRepository
+
+    init() {
+        repo = MockUserRepository()
+    }
+
+    @Test func findExistingUser() async throws {
+        repo.seed(User(id: 1, name: "Alice"))
+        let user = try await repo.find(id: 1)
+        #expect(user?.name == "Alice")
+    }
+
+    @Test func findMissingReturnsNil() async throws {
+        let user = try await repo.find(id: 999)
+        #expect(user == nil)
+    }
+}
+```
+
+- `@Suite` groups related tests with shared setup in `init()`.
+- Each test gets a fresh instance — no shared mutable state between tests.
+
+### Testing async and actor code
+
+```swift
+@Test func actorStateUpdates() async {
+    let cache = ImageCache()
+    await cache.store(image, forKey: "logo")
+    let retrieved = await cache.get("logo")
+    #expect(retrieved != nil)
+}
+
+// Test expected errors
+@Test func withdrawInsufficientFunds() async {
+    let account = BankAccount(balance: 50)
+    await #expect(throws: BankError.insufficientFunds) {
+        try await account.withdraw(100)
+    }
+}
+```
+
+### Confirmation for event-driven behavior
+
+```swift
+@Test func notificationFired() async {
+    await confirmation("User saved notification") { confirm in
+        let observer = NotificationCenter.default.addObserver(
+            forName: .userSaved, object: nil, queue: nil
+        ) { _ in
+            confirm()
+        }
+        await service.saveUser(user)
+        NotificationCenter.default.removeObserver(observer)
+    }
+}
+```
+
+## Dependency injection for tests
+
+### Protocol-based injection
+
+```swift
+protocol NetworkClient: Sendable {
+    func data(from url: URL) async throws -> (Data, URLResponse)
+}
+
+// Production
+struct URLSessionClient: NetworkClient {
+    func data(from url: URL) async throws -> (Data, URLResponse) {
+        try await URLSession.shared.data(from: url)
+    }
+}
+
+// Test
+struct MockNetworkClient: NetworkClient {
+    var responses: [URL: (Data, URLResponse)] = [:]
+
+    func data(from url: URL) async throws -> (Data, URLResponse) {
+        guard let response = responses[url] else {
+            throw URLError(.badURL)
+        }
+        return response
+    }
+}
+
+// Injection
+class UserService {
+    private let network: NetworkClient
+
+    init(network: NetworkClient = URLSessionClient()) {
+        self.network = network
+    }
+}
+```
+
+- Inject dependencies through initializer parameters with production defaults.
+- Keep mock types simple — only implement what the test needs.
+- Avoid mocking frameworks unless the mock implementation becomes complex.
+
+## Package.swift module organization
+
+### Multi-target package
+
+```swift
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "MyApp",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "Domain", targets: ["Domain"]),
+        .library(name: "Networking", targets: ["Networking"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
+    ],
+    targets: [
+        // Core domain — no external dependencies
+        .target(name: "Domain"),
+
+        // Networking depends on Domain
+        .target(name: "Networking", dependencies: ["Domain"]),
+
+        // Tests
+        .testTarget(name: "DomainTests", dependencies: ["Domain"]),
+        .testTarget(name: "NetworkingTests", dependencies: [
+            "Networking",
+            .product(name: "Algorithms", package: "swift-algorithms"),
+        ]),
+    ]
+)
+```
+
+### Package organization guidelines
+
+- Keep `Domain` (models, protocols, business logic) as a standalone target with zero external dependencies.
+- Put I/O, networking, and persistence in separate targets that depend on `Domain`.
+- Use `@testable import` only in test targets.
+- Pin dependency versions with `.upToNextMinor(from:)` for stability. Use `.upToNextMajor(from:)` only for well-trusted packages.
+- Keep `Package.resolved` in version control for applications. Omit it for library packages.
+- Use conditional compilation (`#if canImport(UIKit)`) for platform-specific code in multi-platform targets.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/tailwind-patterns/SKILL.md

@@ -1,267 +1,99 @@
 ---
 name: tailwind-patterns
-description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
+description: "Use for Tailwind CSS v4 architecture, CSS-first theme setup, utility composition, container-query usage, design-token hygiene, and dark-mode strategy."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "4.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
-# Tailwind CSS Patterns (v4 - 2025)
+# Tailwind Patterns
 
-> Modern utility-first CSS with CSS-native configuration.
+## Purpose
 
----
-
-## 1. Tailwind v4 Architecture
-
-### What Changed from v3
-
-| v3 (Legacy) | v4 (Current) |
-|-------------|--------------|
-| `tailwind.config.js` | CSS-based `@theme` directive |
-| PostCSS plugin | Oxide engine (10x faster) |
-| JIT mode | Native, always-on |
-| Plugin system | CSS-native features |
-| `@apply` directive | Still works, discouraged |
-
-### v4 Core Concepts
-
-| Concept | Description |
-|---------|-------------|
-| **CSS-first** | Configuration in CSS, not JavaScript |
-| **Oxide Engine** | Rust-based compiler, much faster |
-| **Native Nesting** | CSS nesting without PostCSS |
-| **CSS Variables** | All tokens exposed as `--*` vars |
-
----
-
-## 2. CSS-Based Configuration
-
-### Theme Definition
-
-```
-@theme {
-  /* Colors - use semantic names */
-  --color-primary: oklch(0.7 0.15 250);
-  --color-surface: oklch(0.98 0 0);
-  --color-surface-dark: oklch(0.15 0 0);
-  
-  /* Spacing scale */
-  --spacing-xs: 0.25rem;
-  --spacing-sm: 0.5rem;
-  --spacing-md: 1rem;
-  --spacing-lg: 2rem;
-  
-  /* Typography */
-  --font-sans: 'Inter', system-ui, sans-serif;
-  --font-mono: 'JetBrains Mono', monospace;
-}
-```
-
-### When to Extend vs Override
-
-| Action | Use When |
-|--------|----------|
-| **Extend** | Adding new values alongside defaults |
-| **Override** | Replacing default scale entirely |
-| **Semantic tokens** | Project-specific naming (primary, surface) |
-
----
-
-## 3. Container Queries (v4 Native)
-
-### Breakpoint vs Container
-
-| Type | Responds To |
-|------|-------------|
-| **Breakpoint** (`md:`) | Viewport width |
-| **Container** (`@container`) | Parent element width |
-
-### Container Query Usage
-
-| Pattern | Classes |
-|---------|---------|
-| Define container | `@container` on parent |
-| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
-| Named containers | `@container/card` for specificity |
-
-### When to Use
-
-| Scenario | Use |
-|----------|-----|
-| Page-level layouts | Viewport breakpoints |
-| Component-level responsive | Container queries |
-| Reusable components | Container queries (context-independent) |
-
----
-
-## 4. Responsive Design
-
-### Breakpoint System
-
-| Prefix | Min Width | Target |
-|--------|-----------|--------|
-| (none) | 0px | Mobile-first base |
-| `sm:` | 640px | Large phone / small tablet |
-| `md:` | 768px | Tablet |
-| `lg:` | 1024px | Laptop |
-| `xl:` | 1280px | Desktop |
-| `2xl:` | 1536px | Large desktop |
-
-### Mobile-First Principle
-
-1. Write mobile styles first (no prefix)
-2. Add larger screen overrides with prefixes
-3. Example: `w-full md:w-1/2 lg:w-1/3`
-
----
-
-## 5. Dark Mode
-
-### Configuration Strategies
-
-| Method | Behavior | Use When |
-|--------|----------|----------|
-| `class` | `.dark` class toggles | Manual theme switcher |
-| `media` | Follows system preference | No user control |
-| `selector` | Custom selector (v4) | Complex theming |
-
-### Dark Mode Pattern
-
-| Element | Light | Dark |
-|---------|-------|------|
-| Background | `bg-white` | `dark:bg-zinc-900` |
-| Text | `text-zinc-900` | `dark:text-zinc-100` |
-| Borders | `border-zinc-200` | `dark:border-zinc-700` |
-
----
-
-## 6. Modern Layout Patterns
-
-### Flexbox Patterns
-
-| Pattern | Classes |
-|---------|---------|
-| Center (both axes) | `flex items-center justify-center` |
-| Vertical stack | `flex flex-col gap-4` |
-| Horizontal row | `flex gap-4` |
-| Space between | `flex justify-between items-center` |
-| Wrap grid | `flex flex-wrap gap-4` |
-
-### Grid Patterns
-
-| Pattern | Classes |
-|---------|---------|
-| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
-| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
-| Sidebar layout | `grid grid-cols-[auto_1fr]` |
-
-> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.
-
----
-
-## 7. Modern Color System
-
-### OKLCH vs RGB/HSL
-
-| Format | Advantage |
-|--------|-----------|
-| **OKLCH** | Perceptually uniform, better for design |
-| **HSL** | Intuitive hue/saturation |
-| **RGB** | Legacy compatibility |
+Use for Tailwind CSS v4 architecture, CSS-first theme setup, utility composition, container-query usage, design-token hygiene, and dark-mode strategy.
 
-### Color Token Architecture
+## When to Use
 
-| Layer | Example | Purpose |
-|-------|---------|---------|
-| **Primitive** | `--blue-500` | Raw color values |
-| **Semantic** | `--color-primary` | Purpose-based naming |
-| **Component** | `--button-bg` | Component-specific |
+- Building or refactoring Tailwind-based UI systems.
+- Choosing theme token structure and CSS-first configuration.
+- Applying container queries, responsive composition, and utility extraction.
+- Reviewing class composition for maintainability and scale.
+- Setting up dark mode, color-scheme toggling, or multi-theme systems.
+- Optimizing Tailwind output for production bundle size.
 
----
+## Instructions
 
-## 8. Typography System
+1. Confirm whether the codebase is truly Tailwind-first and which v4 features are active.
+2. Establish semantic tokens (color, spacing, type, radius) before piling on utilities.
+3. Define dark-mode and color-scheme strategy at the theme level, not per-component.
+4. Use responsive and container-query rules deliberately at the component boundary.
+5. Extract repeated patterns only when reuse and readability clearly improve.
+6. Verify the result stays readable, consistent, and easy to extend.
 
-### Font Stack Pattern
+### Baseline standards
 
-| Type | Recommended |
-|------|-------------|
-| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
-| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
-| Display | `'Outfit', 'Poppins', sans-serif` |
+- Prefer CSS-first theme and token definition in v4-era setups.
+- Keep utility composition semantic at the component boundary.
+- Use container queries for component context, not everything.
+- Treat arbitrary values as exceptions, not the system.
+- Keep spacing, typography, and color scales coherent.
+- Define dark mode via `@custom-variant` or built-in `dark:` — never inline JavaScript toggling of raw classes.
+- Use CSS custom properties for tokens that need runtime switching.
 
-### Type Scale
+### Implementation guidance
 
-| Class | Size | Use |
-|-------|------|-----|
-| `text-xs` | 0.75rem | Labels, captions |
-| `text-sm` | 0.875rem | Secondary text |
-| `text-base` | 1rem | Body text |
-| `text-lg` | 1.125rem | Lead text |
-| `text-xl`+ | 1.25rem+ | Headings |
+- Use `@theme` blocks to define design tokens as CSS custom properties.
+- Prefer `@layer` directives to control specificity ordering.
+- Use `@variant` for semantic state grouping (e.g., `@variant hover, focus-visible`).
+- Keep component-level `@apply` usage to shared design-system primitives, not arbitrary shortcuts.
+- Use `@container` at the component wrapper level with named containers for clarity.
+- Compose responsive with container queries: responsive for page layout, container queries for component-internal layout.
 
----
+### Dark mode and theming
 
-## 9. Animation & Transitions
+- Define color tokens as HSL or OKLCH custom properties for easy theme switching.
+- Use `@custom-variant dark` with a class or media-query strategy — pick one per project and enforce it.
+- Keep contrast ratios WCAG AA minimum (4.5:1 text, 3:1 large text / UI).
+- Test both themes with real content, not just color swatches.
 
-### Built-in Animations
+### Performance and production
 
-| Class | Effect |
-|-------|--------|
-| `animate-spin` | Continuous rotation |
-| `animate-ping` | Attention pulse |
-| `animate-pulse` | Subtle opacity pulse |
-| `animate-bounce` | Bouncing effect |
+- Purge unused styles by keeping utility usage in template files Tailwind can scan.
+- Avoid dynamic class construction (`bg-${color}-500`) — Tailwind cannot detect these at build time.
+- Keep `@apply` chains short — long chains defeat tree-shaking.
+- Use `content` configuration to limit scan scope in monorepos.
+- Prefer targeted `@import` over importing the entire Tailwind base when only utilities are needed.
 
-### Transition Patterns
+### Constraints
 
-| Pattern | Classes |
-|---------|---------|
-| All properties | `transition-all duration-200` |
-| Specific | `transition-colors duration-150` |
-| With easing | `ease-out` or `ease-in-out` |
-| Hover effect | `hover:scale-105 transition-transform` |
+- Avoid dumping arbitrary values into every class list.
+- Avoid mixing old config habits into a CSS-first setup without reason.
+- Avoid repeating long class strings when a component or token should exist.
+- Avoid styling choices that fight the design system instead of clarifying it.
+- Avoid dynamic class name construction that breaks purge scanning.
+- Avoid overriding Tailwind with inline styles or `!important` instead of fixing token conflicts.
+- Avoid using `@apply` with responsive or state variants — compose those in the template.
 
----
+## Output Format
 
-## 10. Component Extraction
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### When to Extract
+## References
 
-| Signal | Action |
-|--------|--------|
-| Same class combo 3+ times | Extract component |
-| Complex state variants | Extract component |
-| Design system element | Extract + document |
+Load on demand. Do not preload all reference files.
 
-### Extraction Methods
+| File                                            | Load when                                                                                                                 |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `references/token-and-composition-checklist.md` | You need deeper Tailwind guidance for v4 token setup, utility composition, container queries, and class extraction rules. |
+| `references/dark-mode-and-theming-guide.md`     | The task involves dark mode setup, multi-theme systems, color-scheme toggling, or OKLCH token architecture.               |
+| `references/performance-and-purge-checklist.md` | The task involves production build optimization, bundle size reduction, or monorepo content configuration.                |
 
-| Method | Use When |
-|--------|----------|
-| **React/Vue component** | Dynamic, JS needed |
-| **@apply in CSS** | Static, no JS needed |
-| **Design tokens** | Reusable values |
+## Scripts
 
----
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## 11. Anti-Patterns
-
-| Don't | Do |
-|-------|-----|
-| Arbitrary values everywhere | Use design system scale |
-| `!important` | Fix specificity properly |
-| Inline `style=` | Use utilities |
-| Duplicate long class lists | Extract component |
-| Mix v3 config with v4 | Migrate fully to CSS-first |
-| Use `@apply` heavily | Prefer components |
-
----
-
-## 12. Performance Principles
-
-| Principle | Implementation |
-|-----------|----------------|
-| **Purge unused** | Automatic in v4 |
-| **Avoid dynamism** | No template string classes |
-| **Use Oxide** | Default in v4, 10x faster |
-| **Cache builds** | CI/CD caching |
-
----
+## Examples
 
-> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
+- "Help me with tailwind patterns best practices in this project"
+- "Review my tailwind patterns implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/tailwind-patterns/references/dark-mode-and-theming-guide.md

@@ -0,0 +1,49 @@
+# Dark Mode And Theming Guide
+
+Load this when the task involves dark mode, multi-theme systems, or color-scheme toggling.
+
+## Strategy selection
+
+- **Class strategy** (`dark` class on `<html>`): Best when user preference must persist across visits, or when more than two themes exist.
+- **Media strategy** (`prefers-color-scheme`): Best for respecting OS-level preference with no user toggle.
+- Pick one per project and enforce it. Do not mix strategies.
+
+## Token architecture for theming
+
+- Define color tokens as OKLCH or HSL custom properties:
+  ```css
+  @theme {
+    --color-surface: oklch(98% 0.01 250);
+    --color-text: oklch(15% 0.02 250);
+  }
+  @custom-variant dark {
+    --color-surface: oklch(12% 0.01 250);
+    --color-text: oklch(92% 0.01 250);
+  }
+  ```
+- Keep token names semantic: `--color-surface`, `--color-text-muted`, `--color-border`.
+- Never reference raw palette values (`gray-900`) in components — always go through tokens.
+
+## Contrast and accessibility
+
+- Maintain WCAG AA contrast ratios: 4.5:1 for normal text, 3:1 for large text and UI components.
+- Test with forced-colors mode (Windows High Contrast) — utility classes may be overridden.
+- Use `forced-color-adjust: none` sparingly and only on decorative elements.
+- Test focus rings in both themes — they must remain visible.
+
+## Implementation checklist
+
+- [ ] Color tokens defined as custom properties, not static values.
+- [ ] Dark variant applied at the theme level, not scattered per-component.
+- [ ] Images and media have appropriate dark-mode treatment (invert, opacity, or alternate assets).
+- [ ] Shadows use OKLCH with alpha for theme-aware depth, not hardcoded hex values.
+- [ ] Borders and dividers use token references, not raw colors.
+- [ ] Form elements and inputs tested in both themes.
+- [ ] Code blocks and syntax highlighting tested in both themes.
+
+## Multi-theme systems (beyond dark/light)
+
+- Use CSS custom properties as the switching mechanism.
+- Keep theme definitions in a single `themes.css` file, not scattered across components.
+- Use a `data-theme` attribute on `<html>` for theme selection.
+- Keep each theme self-contained — no theme should depend on another theme's tokens.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/tailwind-patterns/references/performance-and-purge-checklist.md

@@ -0,0 +1,44 @@
+# Performance And Purge Checklist
+
+Load this when the task involves production build optimization, bundle size, or monorepo content configuration.
+
+## Content configuration
+
+- List every file extension that contains Tailwind classes: `.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.mdx`.
+- In monorepos, scope content paths to avoid scanning `node_modules` or unrelated packages.
+- Use negative patterns to exclude test fixtures or generated files that bloat the scan.
+
+## Class name detection
+
+- Tailwind scans for complete, unbroken class strings. These patterns break detection:
+  - Template literals: `` `bg-${color}-500` `` — use a safelist or explicit mappings instead.
+  - String concatenation: `'text-' + size` — always use full class names.
+  - Dynamic objects: `{ 'bg-red-500': isError }` — this works because the full string is present.
+- When dynamic classes are unavoidable, use the `safelist` option to preserve them.
+
+## @apply discipline
+
+- Long `@apply` chains defeat tree-shaking — if 20 utilities are applied, all 20 remain even if unused elsewhere.
+- Keep `@apply` for true primitives used across 3+ locations.
+- Prefer component abstraction (React/Vue/Svelte components) over CSS-layer `@apply`.
+
+## Production build checks
+
+- [ ] `NODE_ENV=production` is set during build (enables purge).
+- [ ] Final CSS output is under 30KB gzipped for most projects.
+- [ ] No unused `@import` of plugins or layers that don't apply.
+- [ ] Source maps are excluded from production deployment.
+- [ ] Content paths cover all files that use Tailwind classes.
+- [ ] No safelist entries left from development debugging.
+
+## Monorepo-specific
+
+- Use workspace-relative content paths: `../../packages/ui/src/**/*.{tsx,jsx}`.
+- Share a single Tailwind config at the root with package-specific overrides only when necessary.
+- Consider `@import` chaining to share base tokens while allowing package-level extensions.
+
+## Measuring impact
+
+- Compare gzipped CSS size before and after changes.
+- Use `npx tailwindcss --content ... --output /dev/null` to test class detection without a full build.
+- Check for unused custom properties that add bytes without providing value.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/tailwind-patterns/references/token-and-composition-checklist.md

@@ -0,0 +1,41 @@
+# Token And Composition Checklist
+
+Load this when Tailwind structure needs more detail than the root skill.
+
+## Tokens first
+
+- Start with semantic color, spacing, type, and radius tokens in `@theme` blocks.
+- Use OKLCH or HSL for color tokens — they compose better for dark-mode switching.
+- Map raw scale values to semantic names: `--color-surface`, `--color-text-primary`, not `--gray-900`.
+- Keep arbitrary values exceptional and document them when unavoidable.
+- Prefer system-level consistency over local styling convenience.
+- Use CSS custom properties for tokens that must change at runtime (theme switching).
+
+## Composition
+
+- Use utilities directly when the pattern is local and clear.
+- Extract components or semantic wrappers when repetition and intent justify it.
+- Use `@apply` only for true design-system primitives (`.btn-primary`, `.card-surface`), not for shortcuts.
+- Prefer composition via component abstraction (React/Vue components) over `@apply` chains.
+- Use container queries deliberately for component-internal context, not for page-level layout.
+- Name containers explicitly: `@container sidebar` is clearer than anonymous containers.
+
+## Responsive vs container queries
+
+- Responsive breakpoints: page layout decisions (sidebar visibility, grid columns).
+- Container queries: component-internal decisions (card layout, nav style based on parent width).
+- Never mix both for the same layout decision — pick the one that matches the context.
+
+## Variant strategy
+
+- Use `@variant` for grouped hover/focus/active states when multiple utilities share the same trigger.
+- Keep variant nesting shallow — `group-hover:focus:dark:` chains are unreadable.
+- Prefer `focus-visible` over `focus` for keyboard-accessible focus rings.
+
+## Maintainability
+
+- Keep class lists readable — break long lists across multiple lines in templates.
+- Avoid mixing incompatible config-era habits into a CSS-first v4 setup.
+- Re-check whether a design-system primitive should exist before copying long utility sets.
+- Use Tailwind Prettier plugin or consistent class ordering to reduce merge conflicts.
+- Keep utilities grouped by concern: layout → spacing → typography → color → effects.