cortex-agents 1.0.1 → 2.1.0

package/.opencode/skills/desktop-development/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: desktop-development
+description: Cross-platform (Electron, Tauri) and native (SwiftUI, WPF/WinUI, GTK) desktop application development patterns
+license: Apache-2.0
+compatibility: opencode
+---
+
+# Desktop Development Skill
+
+This skill provides patterns and best practices for building desktop applications, covering both cross-platform and native approaches.
+
+## When to Use
+
+Use this skill when:
+- Building new desktop applications
+- Choosing between cross-platform and native development
+- Implementing desktop-specific features (system tray, file access, menus)
+- Packaging and distributing desktop applications
+- Optimizing desktop app performance
+
+## Framework Decision Matrix
+
+| Framework | Language | Bundle Size | Performance | Native Feel | Best For |
+|-----------|----------|-------------|-------------|-------------|----------|
+| Tauri | Rust + Web | ~3-10 MB | Excellent | Good | Modern cross-platform, small bundles |
+| Electron | JS/TS | ~80-150 MB | Good | Fair | Web team building desktop app |
+| .NET MAUI | C# | ~30-50 MB | Good | Good | Microsoft ecosystem, mobile + desktop |
+| Qt/QML | C++ | ~20-40 MB | Excellent | Excellent | Performance-critical, embedded |
+| SwiftUI | Swift | Native | Excellent | Excellent | macOS-only, Apple ecosystem |
+| WPF/WinUI | C# | Native | Good | Excellent | Windows-only, enterprise |
+| GTK 4 | C/Rust/Python | Native | Good | Good (Linux) | Linux-native, GNOME |
+
+### When to Choose Cross-Platform
+- Target multiple OS (Windows, macOS, Linux)
+- Web development team (Electron, Tauri)
+- Rapid prototyping and iteration
+- Content-focused apps (editors, dashboards)
+
+### When to Choose Native
+- Deep OS integration required
+- Maximum performance needed
+- Single-platform target
+- Platform-specific design language
+
+## Cross-Platform: Tauri
+
+### Architecture
+```
+┌────────────────────────────────┐
+│         Tauri Application       │
+├────────────────────────────────┤
+│  Frontend (Web)    │  Backend   │
+│  ─────────────     │  (Rust)    │
+│  HTML/CSS/JS       │           │
+│  React/Vue/Svelte  │  Commands │
+│  Any web framework │  Plugins  │
+│                    │  System    │
+│                    │  Access    │
+├────────────────────────────────┤
+│     System WebView (OS-native)  │
+│  macOS: WKWebView               │
+│  Windows: WebView2 (Edge)       │
+│  Linux: WebKitGTK               │
+└────────────────────────────────┘
+```
+
+### Key Concepts
+- **Commands** — Rust functions callable from frontend via IPC
+- **Events** — Bidirectional event system between frontend and backend
+- **Plugins** — Modular system capabilities (file system, dialog, shell, etc.)
+- **Permissions** — Fine-grained security model (allowlist for system access)
+
+### Tauri Command Example
+```rust
+#[tauri::command]
+async fn read_file(path: String) -> Result<String, String> {
+    std::fs::read_to_string(&path)
+        .map_err(|e| format!("Failed to read file: {}", e))
+}
+
+// Frontend call
+import { invoke } from '@tauri-apps/api/core';
+const content = await invoke('read_file', { path: '/tmp/data.txt' });
+```
+
+### Tauri Best Practices
+- Use permission system — never allow unrestricted file/shell access
+- Keep Rust backend thin — handle system calls, delegate logic to frontend
+- Use Tauri plugins for common needs (fs, dialog, clipboard, notification)
+- Embed frontend assets for offline capability
+- Target specific WebView versions for consistent behavior
+
+## Cross-Platform: Electron
+
+### Architecture
+```
+┌──────────────────────────────┐
+│       Electron Application    │
+├───────────────┬──────────────┤
+│  Main Process │  Renderer    │
+│  (Node.js)    │  (Chromium)  │
+│               │              │
+│  App lifecycle│  UI (HTML/   │
+│  Native APIs  │  CSS/JS)     │
+│  System access│  Web APIs    │
+│  IPC handling │  IPC calls   │
+├───────────────┴──────────────┤
+│  Chromium + Node.js Runtime   │
+└──────────────────────────────┘
+```
+
+### IPC Communication
+```typescript
+// Main process — handle IPC
+import { ipcMain, dialog } from 'electron';
+
+ipcMain.handle('open-file', async () => {
+  const result = await dialog.showOpenDialog({
+    properties: ['openFile'],
+    filters: [{ name: 'Text', extensions: ['txt', 'md'] }],
+  });
+  if (result.canceled) return null;
+  return fs.readFileSync(result.filePaths[0], 'utf-8');
+});
+
+// Renderer process — invoke IPC
+const content = await window.electronAPI.openFile();
+```
+
+### Security Best Practices
+- Enable `contextIsolation: true` (default in modern Electron)
+- Disable `nodeIntegration` in renderer (use preload scripts)
+- Use `contextBridge` to expose safe APIs to renderer
+- Validate all IPC inputs — treat renderer as untrusted
+- Enable `sandbox: true` for renderer processes
+- Keep Electron updated — security patches for Chromium
+
+### Electron Performance
+- Use `BrowserView` for multi-panel UIs instead of multiple windows
+- Lazy-load heavy modules in main process
+- Offload CPU work to worker threads or child processes
+- Monitor memory — Chromium per-process can be expensive
+- Use Electron Forge or electron-builder for optimized builds
+
+## Native: macOS (SwiftUI / AppKit)
+
+### SwiftUI Desktop Patterns
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+        .commands {
+            CommandMenu("File") {
+                Button("Open...") { openFile() }
+                    .keyboardShortcut("o")
+            }
+        }
+
+        MenuBarExtra("Status", systemImage: "circle.fill") {
+            StatusView()
+        }
+        .menuBarExtraStyle(.window)
+
+        Settings {
+            SettingsView()
+        }
+    }
+}
+```
+
+### macOS-Specific Features
+- **Menu bar apps** — `MenuBarExtra` for status bar items
+- **Settings window** — `Settings` scene for preferences
+- **Toolbar** — `.toolbar { }` modifier for window toolbars
+- **Sidebar** — `NavigationSplitView` for master-detail layouts
+- **Drag & drop** — `.onDrop()` and `.draggable()` modifiers
+- **Sandboxing** — App Sandbox for Mac App Store distribution
+
+## Native: Windows (WPF / WinUI 3)
+
+### WinUI 3 Architecture
+- **XAML** for declarative UI layout
+- **MVVM** pattern (Model-View-ViewModel)
+- **Windows App SDK** for modern APIs
+- **WinGet / MSIX** for distribution
+
+### Key Features
+- Fluent Design System integration
+- Acrylic/Mica material backgrounds
+- Toast notifications via Windows API
+- File system and registry access
+- MSI/MSIX packaging for enterprise deployment
+
+## Native: Linux (GTK 4)
+
+### GTK 4 Key Concepts
+- **Widgets** — composable UI elements
+- **Signals** — event-driven communication between widgets
+- **CSS styling** — GTK supports CSS for theming
+- **Flatpak** — recommended packaging format for distribution
+
+### GNOME Integration
+- Follow GNOME Human Interface Guidelines (HIG)
+- Use libadwaita for adaptive, modern GNOME UI
+- Support dark/light theme switching via system preference
+- Use GSettings for persistent configuration
+
+## Desktop-Specific Patterns
+
+### System Tray / Menu Bar
+- Minimize to tray for background apps
+- Show status indicators and quick actions
+- Right-click context menu for common operations
+- Notifications from tray icon
+
+### File System Access
+- Use native file dialogs for open/save (never custom file pickers)
+- Watch file system for changes (fs.watch, FSEvents, inotify)
+- Handle file associations — register as handler for file types
+- Recent files list — track and display recently opened files
+
+### Native Menus & Keyboard Shortcuts
+- Follow platform conventions (Cmd on macOS, Ctrl on Windows/Linux)
+- Standard menu structure: File, Edit, View, Window, Help
+- Global shortcuts for power users
+- Context menus for right-click actions
+
+### Window Management
+- Remember window size and position between launches
+- Support multiple windows when appropriate
+- Handle fullscreen/maximize/minimize states
+- Multi-monitor awareness
+
+### Drag & Drop
+- Support drag from file explorer into app
+- Internal drag for reordering, organizing
+- Drag out to export (files, text, images)
+- Visual feedback during drag operations
+
+## Auto-Update
+
+| Framework | Update Mechanism |
+|-----------|-----------------|
+| Tauri | Built-in updater plugin (checks remote endpoint) |
+| Electron | electron-updater (GitHub Releases, S3, generic server) |
+| macOS Native | Sparkle framework (RSS-based updates) |
+| Windows Native | WinGet, MSIX auto-update, ClickOnce |
+| Linux | Flatpak auto-update, AppImage with AppImageUpdate |
+
+### Update Best Practices
+- Check for updates on launch (non-blocking)
+- Allow user to defer updates
+- Show changelog/release notes
+- Delta updates when possible (reduce download size)
+- Rollback mechanism for failed updates
+- Code sign updates to prevent tampering
+
+## Packaging & Distribution
+
+### macOS
+- **DMG** — Disk image with drag-to-Applications install
+- **pkg** — Installer package for complex setups
+- **Mac App Store** — Sandboxed, Apple review required
+- **Code signing** — Required for Gatekeeper (Developer ID)
+- **Notarization** — Required for distribution outside App Store
+
+### Windows
+- **MSI** — Traditional Windows installer
+- **MSIX** — Modern packaging, auto-update, sandboxed
+- **Portable** — Single .exe, no installation
+- **Code signing** — EV certificate to avoid SmartScreen warnings
+- **Microsoft Store** — Optional, sandboxed distribution
+
+### Linux
+- **AppImage** — Single-file, no installation, runs on most distros
+- **Flatpak** — Sandboxed, auto-update, Flathub distribution
+- **Snap** — Canonical's universal package (Ubuntu-focused)
+- **deb/rpm** — Traditional packages for specific distros
+
+## Technology Recommendations
+
+### By Use Case
+| Use Case | Recommended Stack |
+|----------|-------------------|
+| Web team → Desktop | Tauri + React/Vue/Svelte |
+| Legacy web app → Desktop | Electron + existing frontend |
+| macOS-only tool | SwiftUI + AppKit |
+| Windows enterprise app | WinUI 3 + .NET |
+| Linux GNOME app | GTK 4 + Rust (gtk-rs) or Python |
+| Cross-platform + mobile | .NET MAUI (C#) |
+| Performance-critical (CAD, games) | Qt/QML + C++ |
+| Small utility / CLI with UI | Tauri + minimal frontend |

package/.opencode/skills/frontend-development/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: frontend-development
+description: Component architecture, state management, rendering strategies, styling, and accessibility for modern frontend applications
+license: Apache-2.0
+compatibility: opencode
+---
+
+# Frontend Development Skill
+
+This skill provides patterns and best practices for building modern frontend applications across frameworks.
+
+## When to Use
+
+Use this skill when:
+- Starting a new frontend project or choosing a framework
+- Designing component architecture and state management
+- Implementing routing, SSR/SSG, or rendering strategies
+- Making styling and accessibility decisions
+- Optimizing frontend performance and build tooling
+
+## Component Architecture
+
+### Design Principles
+- Single Responsibility — one component, one purpose
+- Composition over inheritance — combine small components into complex UIs
+- Controlled vs uncontrolled — explicit state vs DOM-managed state
+- Container/Presentational — separate data logic from rendering
+- Compound components — related components that share implicit state
+
+### Component Patterns
+
+```typescript
+// Composition pattern — flexible, reusable
+interface CardProps {
+  children: React.ReactNode;
+}
+
+function Card({ children }: CardProps) {
+  return <div className="card">{children}</div>;
+}
+
+Card.Header = ({ children }: CardProps) => (
+  <div className="card-header">{children}</div>
+);
+Card.Body = ({ children }: CardProps) => (
+  <div className="card-body">{children}</div>
+);
+```
+
+### Custom Hooks / Composables
+- Extract reusable logic into hooks (React) or composables (Vue)
+- Keep hooks focused — one concern per hook
+- Prefix with `use` (React/Vue) for convention
+- Return minimal API surface — only what consumers need
+
+## Framework Patterns
+
+### React
+- Hooks for all state and effects (useState, useEffect, useReducer)
+- Context for cross-cutting concerns (theme, auth, locale)
+- Suspense + lazy() for code splitting
+- Server Components (RSC) for reduced client bundle
+- Error Boundaries for graceful failure handling
+
+### Vue 3
+- Composition API with `<script setup>` for concise components
+- Composables for reusable logic (equivalent to React hooks)
+- Provide/Inject for dependency injection
+- Teleport for portal rendering
+- Keep Options API for simple components if team prefers
+
+### Angular
+- Standalone components (preferred over NgModules)
+- Signals for reactive state management
+- Services with dependency injection for shared logic
+- RxJS for complex async flows
+- Structural directives for template logic
+
+### Svelte
+- Runes ($state, $derived, $effect) for reactivity (Svelte 5)
+- Stores for shared state across components
+- Actions for reusable DOM behavior
+- Transitions and animations built-in
+- Minimal boilerplate — write less, do more
+
+### Laravel Frontend (Blade, Livewire, Inertia.js)
+- **Blade** — Server-rendered templates with `@directives`, layouts, and components
+- **Livewire** — Reactive components without writing JavaScript (server-driven SPA feel)
+- **Inertia.js** — SPA experience using React/Vue/Svelte with Laravel backend (no API needed)
+- **Vite integration** — Built-in Vite support for asset bundling (`@vite` directive)
+- Use Livewire for CRUD-heavy admin panels and dashboards
+- Use Inertia.js for full SPA behavior with Laravel routing and auth
+
+## State Management
+
+### State Categories
+| Type | Scope | Tools |
+|------|-------|-------|
+| Local state | Single component | useState, ref(), signal |
+| Shared state | Component subtree | Context, provide/inject, props |
+| Global state | Entire app | Redux/Zustand, Pinia, NgRx, Svelte stores |
+| Server state | Remote data cache | TanStack Query, SWR, Apollo Client |
+| URL state | Browser URL | React Router, Vue Router, route params |
+| Form state | Form inputs | React Hook Form, Formik, VeeValidate |
+
+### Best Practices
+- Keep state as local as possible — lift only when needed
+- Normalize nested data in global stores
+- Use server state libraries for API data — avoid duplicating cache
+- Derive state instead of storing computed values
+- Use optimistic updates for responsive UIs
+
+## Routing & Navigation
+
+- File-based routing (Next.js, SvelteKit, Nuxt) — convention over configuration
+- Nested routes for layout composition
+- Route guards / middleware for auth protection
+- Code splitting by route for optimal loading
+- Parallel routes for simultaneous views (Next.js App Router)
+- Preserve scroll position on navigation
+
+## Rendering Strategies
+
+| Strategy | When to Use | Examples |
+|----------|-------------|---------|
+| CSR (Client-Side) | Interactive apps, auth-gated content | SPAs, dashboards |
+| SSR (Server-Side) | SEO-critical, dynamic content | E-commerce, news sites |
+| SSG (Static Generation) | Content that rarely changes | Blogs, docs, marketing |
+| ISR (Incremental Static) | Static + periodic updates | Product catalogs |
+| Streaming SSR | Large pages, progressive loading | Next.js App Router, SvelteKit |
+
+### Meta-Framework Recommendations
+- **Next.js** — React, hybrid rendering, App Router for RSC
+- **Nuxt 3** — Vue 3, auto-imports, hybrid rendering
+- **SvelteKit** — Svelte, file-based routing, adapters for any platform
+- **Astro** — Content-focused, island architecture, multi-framework
+
+## Styling Approaches
+
+| Approach | Pros | Cons | Best For |
+|----------|------|------|----------|
+| Tailwind CSS | Fast, consistent, small bundle | Verbose markup | Most projects |
+| CSS Modules | Scoped, standard CSS | No dynamic styles | Component libraries |
+| CSS-in-JS | Dynamic, co-located | Runtime overhead | Theme-heavy apps |
+| SCSS/Sass | Powerful, familiar | Global scope risk | Large legacy projects |
+
+### Design Tokens
+- Use CSS custom properties for theming
+- Define tokens for colors, spacing, typography, shadows
+- Support dark mode with `prefers-color-scheme` and class toggle
+- Use design system tools (Style Dictionary, Tailwind config)
+
+## Accessibility
+
+### Core Requirements
+- Semantic HTML first — use `<button>`, `<nav>`, `<main>`, `<article>`
+- Keyboard navigation — all interactive elements focusable and operable
+- ARIA attributes — use only when semantic HTML is insufficient
+- Color contrast — minimum 4.5:1 for normal text (WCAG AA)
+- Screen reader testing — test with VoiceOver, NVDA, or JAWS
+
+### Common Patterns
+- Skip navigation links for keyboard users
+- Focus management on route changes (SPAs)
+- Live regions (`aria-live`) for dynamic content updates
+- Form labels — every input needs an associated label
+- Alt text — descriptive for content images, empty for decorative
+
+## Performance
+
+### Core Web Vitals
+- **LCP** (Largest Contentful Paint) < 2.5s — optimize hero images, fonts
+- **INP** (Interaction to Next Paint) < 200ms — reduce JS execution
+- **CLS** (Cumulative Layout Shift) < 0.1 — reserve space for dynamic content
+
+### Optimization Techniques
+- Memoization (useMemo, useCallback, React.memo, computed)
+- Lazy loading for below-fold content and heavy components
+- Virtualization for long lists (TanStack Virtual, react-window)
+- Image optimization (next/image, responsive srcset, WebP/AVIF)
+- Bundle analysis and tree shaking
+
+## Build Tooling
+
+### Recommended Tools
+- **Vite** — Fast dev server, optimized production builds (recommended for most projects)
+- **Turbopack** — Next.js incremental bundler
+- **Webpack** — Mature, extensive plugin ecosystem
+- **esbuild** — Ultra-fast bundling for libraries
+
+### Best Practices
+- Enable tree shaking — use ES modules, avoid side effects
+- Configure code splitting — route-based and component-based
+- Analyze bundle size regularly (rollup-plugin-visualizer, webpack-bundle-analyzer)
+- Use import aliases for clean paths
+- Configure path aliases in tsconfig and bundler
+
+## Technology Recommendations
+
+### By Project Type
+| Project | Recommended Stack |
+|---------|-------------------|
+| SPA / Dashboard | React + Vite + Zustand + Tailwind |
+| SEO + Dynamic | Next.js (App Router) + TanStack Query |
+| Content Site | Astro + any UI framework + MDX |
+| Enterprise App | Angular + NgRx + Material |
+| Rapid Prototyping | SvelteKit + Tailwind |
+| Vue Ecosystem | Nuxt 3 + Pinia + VueUse + Tailwind |
+| Laravel Full-Stack | Laravel + Inertia.js + Vue/React + Tailwind |
+| Laravel Server-Driven | Laravel + Livewire + Alpine.js + Tailwind (TALL stack) |