mosaic

mosaic package architecture, refactor layering, dependency inversion, file organization, DocC documentation, package design discipline, testability, and Swift 6 concurrency rules. Use before adding or meaningfully rewriting Swift files, Swift packages, coordinators, services, repositories, or public package APIs.

Backend TypeScript and Cloud VM development rules for mosaic. Use when editing web/app/api, web/services, backend scripts, Cloud VM lifecycle, provider integrations, Postgres, Stack Auth pricing gates, migrations, or provider image build scripts.

End-user browser automation with mosaic. Use when you need to open sites, interact with pages, wait for state changes, and extract data from mosaic browser surfaces.

Build a custom mosaic sidebar from a plain-language request. Use when the user asks for a custom sidebar, a sidebar that shows their workspaces/tabs/PRs/clock, a vibe-coded sidebar, or anything involving files in ~/.config/mosaic/sidebars/. Covers authoring the interpreted SwiftUI-style file, enabling the beta flag, selecting it, and iterating with hot reload.

Customize mosaic for an end user. Use when changing mosaic.json actions, custom commands, workspace layouts, plus-button behavior, surface tab bar buttons, Command Palette entries, Dock controls, sidebar and app settings, shortcuts, notifications, browser routing, examples-library presets, or Ghostty-backed terminal preferences.

Debug logging, Debug menu, runtime pitfalls, typing-latency-sensitive paths, SwiftUI list snapshot boundaries, OS-version repros, and local visual iteration for mosaic. Use when adding debug probes, diagnosing UI/runtime issues, touching terminal rendering, tab/sidebar list views, drag/drop UTTypes, or using the Debug menu.

Contributor workflow rules for mosaic setup, Xcode project normalization, tagged sidebar ExtensionKit development, and dev builds. Use when setting up the mosaic repo, changing Xcode project files, adding sidebar extensions, or working with tagged debug builds.

Run end-user mosaic diagnostics. Use when mosaic hooks, notifications, session restore, settings, browser automation, socket access, CLI control, or agent resume behavior is not working, or when the user asks for a mosaic health check, doctor report, or support-safe debug summary.

Ghostty submodule and GhosttyKit workflow rules for mosaic. Use when modifying the ghostty submodule, rebuilding GhosttyKit.xcframework, updating the parent submodule pointer, or documenting fork conflict notes.

Guide and apply mosaic keyboard shortcut customization. Use when the user asks to customize, rebind, unbind, reset, audit, or create shortcut templates for mosaic, including tmux-style, Vim-style, terminal-first, browser-heavy, iTerm/Terminal-like, or agent-triage layouts.

Localization rules and audit workflow for mosaic UI strings, settings rows, menus, shortcuts, schema/config text, docs, command/help text, alerts, tooltips, and web messages. Use whenever changing user-facing text.

Open markdown files in a formatted viewer panel with live reload. Use when you need to display plans, documentation, or notes alongside the terminal with rich rendering (headings, code blocks, tables, lists).

mosaic release workflow, version bumping, changelog updates, pretag guard, release tags, and release asset expectations. Use when preparing or troubleshooting a mosaic release.

View and edit mosaic settings in ~/.config/mosaic/mosaic.json. Use when the user wants to change mosaic preferences (appearance, sidebar, notifications, automation, browser, shortcuts), set a value by JSON path, validate the file, open it in an editor, or look up which keys mosaic recognizes. Triggers on '/mosaic-settings', 'change mosaic setting', 'set <something> in mosaic', 'mosaic config', 'mosaic.json', or 'rebind a mosaic shortcut'.

Shared behavior and mutation-path rules for mosaic. Use when a behavior is exposed through multiple entrypoints such as keyboard shortcuts, command palette, context menu, CLI, settings, debug menu, optimistic UI, or tests that previously missed a bug.

End-user control of mosaic topology and routing (windows, workspaces, panes/surfaces, focus, moves, reorder, identify, trigger flash). Use when automation needs deterministic placement and navigation in a multi-pane mosaic layout.

Socket command threading and focus policy for mosaic CLI/socket work. Use when adding or changing socket commands, CLI commands, telemetry commands, focus/select/open/close/send-key behavior, or automation that could steal app focus.

mosaic testing rules for Swift Testing, test target compilation, and package/refactor validation. Use when adding or changing tests, touching package/refactor code, or deciding whether reload.sh is enough validation.

Work inside the current mosaic workspace and terminal. Use for mosaic workspace, current workspace, caller surface, panes, surfaces, socket targeting, and non-interfering mosaic automation.