qol-tools

architect

Run one task as the planning-only architect. Use when the user invokes /architect <task>. The architect scopes, scouts through lanes, writes the spec, fans out lanes, reviews, runs the single gate, and accepts; it never implements.

qol-adversarial-test

Plan, run, and productize adversarial test storms against real application surfaces. Use when the user asks to break, battle-harden, stress, chaos-test, fuzz, race, test-storm, or heavily test a feature, especially in VMs or containers or across lifecycle, concurrency, persistence, authentication, resource, UI-state, and platform boundaries, and expects failures to be preserved as regression tests and verified against the live product path.

qol-code-review

Use when the user asks to review code, review a patch/diff/PR, run security/correctness/performance/architecture/release/CI review, spin up reviewer agents, delegate reviewers, or synthesize pass/conditional/block findings with severity, confidence, actionability, and machine-parseable output.

qol-debug

Use when asked to locate, hunt for bugs, or find security vulnerabilities in a qol-tools repo (qol-monorepo, qol-skills) - first-pass identification, evidence-gathering, and high-confidence reporting without fixing. Triggers on "locate bugs", "find bugs", "bug hunt", "first pass", "hunt for defects", "report back what you found", "find security vulnerabilities", "security review", "hunt for vulnerabilities", "find exploits", or any read-only debugging or security sweep. Covers baseline verification (clippy + full test suite), live qol-dev session log mining, recent-fix and newest-feature prioritization, the static bug-shape and security grep catalogs, per-suspect source verification, multi-perspective review for high-value targets, guest-VM confirmation of runtime findings, and the report template that ships only high-confidence findings.

gpui-conventions

Use when writing gpui UI code in this workspace. Verified workspace patterns and gotchas for the GPUI dependencies selected by Cargo, built through hands-on exploration — NOT a generic gpui reference. Covers views, input, lists, focus, window management, testing, and source-checking version-sensitive behavior.

macos-window-activation

Use when a qol plugin (alt-tab, launcher, window-actions) must bring ANOTHER app's window to the front on macOS, or make its own popup key. Covers why NSRunningApplication.activate is inert on macOS 14+, why SkyLight `_SLPSSetFrontProcessWithOptions` is necessary but silently ignored against actively-front apps, the `kAXFrontmost` app attribute that actually foregrounds a fighting app, the generation-guarded re-assert loop that beats the picker-teardown race, AXRaise/unminimize ordering, reading the true frontmost window via CGWindowList, dlopen-ing a private framework, and the click-gesture / modifier-drop focus pitfalls. Built from a reproduced alt-tab focus bug, not generic docs. For our own popup's focus use gpui-conventions ("Eagerly stealing OS window focus"); this skill is about foregrounding a foreign app.

preact-conventions

Use when writing Preact + htm code in this workspace. Workspace-specific patterns and gotchas (no JSX, no build step, htm tagged templates from `lib/html.js`, keyboard-first hard rule, icon component extraction, toast/dissolve helpers, focus trapping, custom inputs, router guards, provider unmount/remount) — NOT a generic Preact reference. For canonical Preact docs, use context7. qol-tray-specific component hierarchy (Surface trait, plugin-config fields) lives in `qol-tray-ui-systems`.

rust-conventions

Use when writing Rust in this workspace: how Rust code should be written here. Workspace-specific style and gotchas (error handling, filesystem, process management, cross-platform code layout), NOT a generic Rust reference. For canonical Rust/library docs, use context7 instead. Plugin-specific and qol-tray-specific Rust gotchas live in their own skills (`qol-plugin-*`, `qol-tray-core`, `qol-tray-rust`, `qol-arch-code`, `qol-arch-cross-platform`).

qol-plugin-alt-tab

Use when working on the qol-tray alt-tab plugin, including its retained GPUI picker, OS window discovery, preview capture, window actions, daemon lifecycle, config, and shared settings surface.

qol-plugin-bluetooth

Use when working on the qol-tray Bluetooth plugin. Covers BlueZ adapter and device operations, discovery, the reconnect retry policy, audio-device readiness, live settings queries, daemon lifecycle, and doctor checks. Triggers on "plugin-bluetooth", "bluetooth", BlueZ, bluer, adapter power, pairing, trusting, reconnecting headphones, or Bluetooth discovery.

qol-plugin-cli-sessions

Use when working on the qol-tray CLI Sessions plugin. Covers live terminal session discovery, the per-tool interpretation strategy registry, the session status state machine, screen and title signals, the always-on-top gpui overview panel, snapshots, and daemon reconciliation. Triggers on "plugin-cli-sessions", "cli sessions", session overview, needs-you or your-turn status, Kitty remote control, or terminal attention tracking.

qol-plugin-controllers

Use when working on the qol-tray Controllers plugin or the host's reusable gamepad field, including browser Gamepad input, controller hardware profiles, Linux evdev supplementation, Bluetooth adapter and signal diagnostics, driver-specific fixes, and rumble or haptics testing.

qol-plugin-ide-checkout

Use when working on the qol-tray ide-checkout Task Runner plugin. Covers Rust supervision, the Python daemon boundary, config, status reporting, packaging, and synchronization with the browser-extension API contract.

qol-tray-task-runner-ide-checkout

Use when working on the qol-tray task runner IDE checkout API contract, actions, and execution flow.

qol-plugin-keyremap

Use when working on the qol-tray key remap plugin. Covers config-to-rule resolution, native event interception, per-app policy, hot reload, daemon lifecycle, editor integration, and target adapters.

qol-plugin-launcher

Use when working on the qol-tray launcher plugin, including retained GPUI behavior, discovery and ranking, launching, daemon activation, hotkey diagnostics, config, and tests.

qol-plugin-lights

Use when working on the qol-tray lights plugin. Covers backend adapters, Zigbee coordinator control, live color transport, daemon lifecycle, contract wiring, and native settings integration.

qol-plugin-os-themes

Use when working on the qol-tray OS themes plugin. Covers cursor effects, native theme control, daemon lifecycle, target-specific adapters, config contracts, and settings integration.

pointz-client

Use when working on the PointZ Flutter mobile client for discovery, gesture handling, settings, and UDP command transport. Pair with qol-plugin-pointz for desktop protocol changes.

qol-plugin-pointz

Use when working on the qol-tray PointZ desktop server plugin. Covers daemon IPC, UDP discovery and command transport, status queries, QoL settings integration, and target-specific input injection. Pair with the pointz-client skill when changes touch the mobile-side protocol.

qol-plugin-removeapp

Use when working on the qol-tray Remove App plugin. Covers installed-app inventory, leftover discovery and attribution, package-manager guards, the identity-snapshot recheck that makes deletion safe, trash-versus-delete disposal, and the gpui removal UI. Triggers on "plugin-removeapp", "removeapp", uninstall, leftovers, app removal, protected apps, or package-managed applications.

API & Backend Listed

qol-plugin-window-actions

Use when working on the qol-tray Window Actions plugin, including snapping, centering, minimize/restore, monitor movement, continuous glide actions, Cinnamon/X11 behavior, platform backends, or window-movement diagnostics.

qol-arch-channels

Use when adding any new piece of host-to-plugin or plugin-to-host communication in qol-tools (a new event, request, capability bit), deciding whether a tray-owned helper-process socket is a new channel, or exposing qol capability tools to terminal agents (pi, Claude Code, codex, kimi). Picks the right channel and stops re-deriving existing runtime infrastructure.

qol-arch-cicd

Use when authoring or modifying CI / release workflows (`.github/workflows/*.yml`), `Cargo.toml`, or `Cargo.lock` in the qol-monorepo. Encodes the cross-platform infrastructure contract that prevents CI/release parity failures: platform matrices derived from `plugin.toml` `platforms`, strictness parity between CI and release builds (both `-D warnings` and `--locked`), conditional dependencies expressed as `[target.'cfg(target_os = ...)'.dependencies]` rather than as cfg gates in source. Triggers on edits to workflow YAML, on changes to `Cargo.toml` `[dependencies]` / `[target...]` sections, on a stale or regenerated `Cargo.lock`, and on the words "release pipeline", "plugin CI", "matrix build", "RUSTFLAGS", "lockfile", "--locked". For the code patterns the matrix exists to catch, see `qol-arch-code` and `qol-arch-cross-platform`.

qol-arch-code

Use when designing or refactoring Rust plugins/libs that need clean source ownership, cross-platform support, capability-specific backend splits, native GPUI or web UI placement, or headless-first CLI/plugin contracts. Defines plugin source-root hygiene, the ui/ versus src/ui/ boundary, Rust module directory form, strategy-pattern compartmentalization (platform/ subfolders, trait + per-OS impls), capability-local backend boundaries, headless binary layering, mandatory help/doctor commands, what a plugin doctor command must report, and plugin doctor output contracts. Triggers on plugin directory structure, loose files under src/, module file-plus-folder hybrids, native or web UI placement, platform-specific code, multi-OS support, OS-named files, Linux X11/Wayland/compositor splits, headless CLI design, plugin runtime action design, doctor commands, or any time you see

qol-arch-cross-platform

Use when adding or refactoring symbols (functions, types, constants, use statements) that *might* be consumed by only one platform's backend, even when the symbol itself looks platform-neutral. Prevents the most common qol-tools cross-platform regression: code that compiles green on Linux but emits dead_code / unused_imports / unused_mut errors on macOS or Windows under `-D warnings`. Triggers on edits to shared modules that border `platform/` directories, on `#[allow(dead_code)]` / `#[allow(unused_mut)]` reaches, on `#[cfg(target_os)]` attributes attached to `use` statements, and any time you find yourself "quieting a lint" on one OS. For the strategy-pattern code layout that this skill builds on, see `qol-arch-code`. For CI-side enforcement that catches the failures across all three OSes, see `qol-arch-cicd`.

qol-cicd

Use when authoring or modifying CI, versioning, or release workflows in the qol-monorepo (.github/workflows/*.yml, .github/scripts/*), or when a release or version bump does not behave as expected.

qol-cli

Use when answering questions about `qol` CLI commands or changing `tools/qol-cli` behavior. Stable ownership model only; command facts come from `qol --help`, never from memory.

qol-dev-environments

Operate, debug, and evolve the `qol dev` Sandbox panel and its disposable OS environments. Use for typed sandbox workers, artifact-backed `qol dev` guests, host-built bundle transport, verified qcow2 import, `qol env`, `qol flow`, prepared desktop images, guest control, QEMU lifecycle or recovery, resource admission, clean-session plugin testing, and parallel guest work that must stay off the user's active desktop session. Also use whenever a task reproduces, debugs, or verifies qol runtime desktop behavior — plugin windows, hotkeys, previews, popups, tray actions — which happens in a guest, not on the host session.

qol-mission

Use when weighing trade-offs that touch the mission of qol-tools — what the product is, who it's for, the Portable and Resident host-ownership contracts, and the non-negotiable user-facing promises that any feature, bug fix, or architecture decision must respect. Covers the user experience, portability, persistent host policy, host-OS interaction, hotkeys, settings, sync, and "what qol-tools should do for the user".

qol-plugin-gpui-surfaces

Use when giving a qol plugin a native gpui surface - a contract-driven settings panel, toast, picker, or other summonable window - instead of or beside the web auto-config page. Covers the tray-owned singleton settings host, the shared qol-gpui surface kit, capability routing and fallbacks, runtime queries/actions, and placement/focus/dismiss invariants.

qol-plugin-template

Use when bootstrapping a new qol-tray plugin from the template plugin or updating that template. Covers source-driven customization, contract identity, architecture growth, shared settings, platform adapters, and verification.

qol-shared-libs

Use when adding functionality, dependencies, native UI, runtime contracts, or platform-specific code to any qol plugin. Requires source-driven discovery of existing shared capability owners before adding plugin-local code.

qol-tools

Use when working anywhere in the qol-tools world - the qol-monorepo (apps/, libs/, plugins/, tools/, docs/) or the qol-skills repo. Covers org-level conventions, monorepo layout, dependency model, branch and commit policy, and pointers to more specific skills.

qol-sessions

Use when an architect must create or drive an implementation agent in another terminal through event-signalled implementation and review rounds until a feature is accepted. Also use for cross-terminal handoffs, relays, bridges, or independent agent sessions. The agent surface is sessions_list, session_spawn, session_bridge, and session_loop_close; product, model, and session names are never part of the workflow contract.

qol-shot

Use when working on the qol-shot screenshot and screen-recording plugin, including capture lifecycle, native overlays, retained GPUI surfaces, output, clipboard, config, and platform adapters.

qol-trace-discipline

Use when writing, reviewing, debugging, or testing code in any qol-tools repo, especially when behavior changes touch runtime flows, persistence, IPC, plugin actions, UI state, production-only paths, or a bug was found. Requires the agent to ask: is this a potential new qol trace target, or maybe time to enrich this qol trace target with more details?

qol-apps-testing

Use when adding, updating, or reviewing tests for qol apps and plugins in this workspace. Covers when a property test wins, when to use parameterized tests with dense case sets, and how to avoid low-value tests.

qol-tray-core

Use when working on the core qol-tray application - the plugin system, tray, feature architecture, and the plugin contract formats (plugin.toml / qol-config.toml / qol-runtime.toml). Rust internals, UI systems, world canvas, and the Profile feature have their own skills.

qol-tray-data-migrations

Use when a qol-tray release breaks the on-disk config layout or cloud-backed user data, when adding a new migration between releases, or when debugging missing, duplicated, or stomped user data after startup. Defines the two-phase sliding-window migration pattern in the monorepo qol-migrations crate: PreFlight runs synchronously before any feature reads config, PostAuth runs asynchronously after GitHub auth loads, and old migrations are pruned once they fall outside the supported upgrade window.

qol-tray-dev-logging

Use when adding diagnostic logs to qol-tray frontend (ui/) code. Enforces the createDebug namespace convention and message-style rules instead of raw console.log. Triggers when working on camera, nav, wedge, world, spatial, or app-level state in qol-tray.

qol-tray-dev-recompile

Use when you debug whether a qol-tray or plugin change reached the running process. Covers the canonical dev recompile/restart path, daemon teardown, plugin build provenance, and evidence needed before blaming stale code.

qol-tray-feature-profile

Use when working on qol-tray's Profile feature, including profile export/import, sync providers, backups, profile UI, and plugin config or lock reconciliation.

qol-tray-page-creation

Use when adding a qol-tray world-canvas page, dive target, sub-page, Component Gallery showcase, or reusable user-facing UI component that must be represented in the gallery. Trigger on gallery source-of-truth, gallery/production parity or drift, and requests to prevent plugin-local or stray UI implementations. Covers page registration, dive contracts, content sizing, and the 1:1 production/gallery test-bed rule.

qol-tray-release-flow

Use when cutting, tagging, or preparing a release for qol-tray or any plugin release unit in the monorepo, or when release CI does not trigger as expected.

API & Backend Listed

qol-tray-rust

Use when working on qol-tray's Rust backend — plugin system, daemon supervision, hosted settings surfaces, IPC/runtime endpoints, feature modules, shared qol-* crate placement, cross-platform strategy pattern, tokio concurrency and thiserror/anyhow error handling. Use when modifying files under src/plugins/, src/settings_surface/, src/daemon/, src/runtime/, src/features/, src/sync/, src/menu/, src/tray/, src/app/, src/updates/, or src/profile/, or when adding socket/HTTP endpoints, wiring a new feature module, touching Cargo.toml dependencies, deciding whether logic belongs in qol-tray or a shared qol-* crate, or reviewing Rust concurrency and error-handling patterns in qol-tray.

qol-tray-ui-systems

Use when adding or modifying qol-tray UI components, reusable or shared UI, Component Gallery entries, modals, keyboard navigation, dropdowns, toggles, focus management, or selection wedge behavior. Trigger on UI component reuse, stray UI components, gallery/production drift, and changes under ui/views/, ui/components/, ui/lib/components/, ui/lib/hooks/, ui/app/, or ui/styles/. Do not trigger for generic non-UI uses of "component".

qol-world-canvas

Use when working on divable elements, dive traits (confined, peripheral-preview, atmosphere), world navigation, the dive stack, plugin spatial layout, or the minimap in qol-tray. Use when touching ui/lib/world-*, ui/lib/minimap-*, ui/components/shell/WorldViewport.js, Minimap.js, PeripheralPreview.js, AtmosphereLayer.js, plugin-trait-overrides.js, or ui/styles/atmosphere.css / peripheral-preview.css.

qol-voice

Use when working on the qol-voice plugin. Covers audio capture and utterance segmentation, the engine-neutral transcription provider registry, local and remote speech-to-text backends, the pure turn coordinator and its policy, routing completed turns to live terminal sessions, voice session lifecycle, and doctor checks. Triggers on "qol-voice", voice, speech-to-text, transcription, whisper, utterance, turn taking, or dictating into a terminal session.

qol-workflow-nodes

Personal workflow-automation discipline for KMRH47. Use when a task has repeated commands, multi-step tool chains, fragile manual instructions, build/export/test loops, human verdict loops, performance optimization workflows, performance measurement ledgers, before/after metric comparisons, or any chance to convert agentic tool calls into deterministic scripts with explicit inputs, outputs, reports, and composable workflow nodes. Also use when the user asks for a one-command lane, scriptification, orchestration, reproducibility, token reduction, or making a workflow easier for humans and AI.

qol-gpui-theme

Use when designing, building, reviewing or restyling any native gpui surface in qol - settings panel, launcher, alt-tab, cli-sessions, remove-app, qol-shot, toasts, gamepad diagram. Defines Bone and Amber V2: the surface token set for light, dark and unfocused, the spacing/height/type/radius ladders, one definition per state, the component register, and the delta between the qol-theme palette and this spec. Companion to qol-plugin-gpui-surfaces, which owns wiring and placement rather than looks.

qol-artifact-identity

Use when building, installing, updating, staging, or executing a deployable qol native binary, or when a consumer needs to locate an artifact it did not build. Defines the identity contract, which crate owns which layer, why a filesystem path is never identity, and how opaque non-Rust payloads stay covered. Triggers on qol-conventions, qol-build-identity, qol-artifact, build-script emission, artifact resolution from a target/ or profile directory, install/update/staging handoffs, and content digests for scripts and assets.

qol-memory

Use when a session needs a settled fact from earlier work in this workspace, when the user references a past decision, fix, or path the agent does not remember, or when a settled outcome should be captured for later sessions.