xmm-skills/skills/xmm-workstation/SKILL.md

name, description

name	description
xmm-workstation	Use when configuring, implementing, debugging, porting, or reviewing XMM or its compile-time workstation policy. Distinguish a local config.h edit from a new product capability, then rebuild and prove the real path. Do not use for requirements-only authoring, planning, orientation, or unrelated host dotfiles.

XMM workstation

One job

Make one XMM workstation behavior work through the smallest owning surface: existing typed config.h policy when possible, or one requirement-bound C11 product slice when the capability does not exist.

Choose the owner

Read AGENTS.md, the applicable REQUIREMENTS.md rows, and config.def.h or the owning production module.

• Local configuration: when the request changes only monitor profiles, wallpaper paths, commands, lock client, bindings, colors, inputs, app-id rules, or other already-supported policy, inspect the real host and edit only ignored config.h. Copy config.def.h first only when config.h is absent. Do not change requirements or tracked defaults.
• Default policy: when the user explicitly changes shipped defaults, revise requirements first, then config.def.h, proof, and orientation as applicable.
• Capability: when typed configuration cannot express the requested behavior, revise or obtain requirement authority before changing C11 code or protocols.

For local setup, inspect only evidence relevant to requested policy: connected output connector/EDID/modes, current compositor config, XKB settings, input capabilities, available command executables, lock client/authentication stack, audio control plane, and wallpaper files. Translate observed choices into XMM's typed tables in config.h; output profile and wallpaper selector/planning contracts are owned by src/output.h and their implementation by src/output.c; direct libseat/DRM ownership, EDID identity, logical-to-physical projection, physical wallpaper composition, atomic output state, bounded DRM hotplug intake/transaction rollback, and page-flip cleanup are owned by src/direct.c; src/xmm.c owns the single event-loop frame clock that coalesces damage behind one pending flip per output, while src/render.c must submit through implicit fences without waiting for GPU completion on that loop; direct libinput discovery, XKB compilation, typed device policy, and event normalization are owned by src/input.c; src/diagnostic_log.c owns the nonblocking stderr mirror and bounded XDG state log; src/render.c owns the fixed EGL/GLESv2 composition path, nested EGL target, and single-plane DMA-BUF EGLImage import; src/dmabuf.c owns the bounded linux-dmabuf v5 global, feedback, parameter validation, wl_buffer lifetime, and release handoff; src/presentation.c owns presentation-time feedback lifetime while src/direct.c supplies page-flip timestamps and refresh and src/xmm.c binds each presented surface commit to that observation; src/scaling.c owns viewporter and fractional-scale protocol resources and committed viewport state while src/xmm.c supplies per-surface preferred output scale and scene wiring; src/xmm.c owns wl_output/wl_seat publication, per-output rule/cache selection, and compositor-layer coverage; src/desktop.c owns stable output/workspace assignment, neighbor selection, visible-workspace swaps, and removed-output client migration. Do not assume the current host, package set, paths, keymap, commands, or monitor identities are product defaults. Convert a selected wallpaper once to bounded P6 outside the repository; never add PNG decoding or a converter to runtime. Translate Kanshi profiles to ordered selector/action rows using scale units of 1/120; preserve exact values such as Kanshi 1.9 as 228, and reject exec hooks rather than hiding them in profile policy. Configure an audio or lock tool as direct argv only after discovering it and obtaining the user's choice. Preserve local config.h across tracked default updates and report any newly required decision instead of guessing it.

Do not create a runtime config parser, migration layer, alias language, IPC, reload watcher, shell-string command format, or another configuration file.

Product slice

For a capability change, name the requirement, user-visible observation, real entry point, and external boundary. Trace pinned public XML when protocol order, lifetime, coordinates, or errors matter. Keep pinned source/data mechanisms (currently Spleen glyphs and the minimal libgrapheme UAX #29 implementation/tables) at their owning local seam with URL, revision/version, checksum, license, and modifications; do not replace them with ambient host font or locale behavior. Keep reusable server-global state machines such as activation and core data devices in their dedicated src/ modules, with seat/focus/surface policy supplied by the compositor owner in src/xmm.c. Pinned xdg-shell and xdg-decoration XML, scanner generation, and decoration negotiation remain one protocol slice; server-side mode suppresses client titlebars and must not grow a drawn decoration framework. Write the smallest failure/success assertion, then implement the cohesive C11 path with validation, checked arithmetic, bounded ownership, diagnostics, rollback, and cleanup at its owner. Do not introduce C++, Zig, a framework abstraction, helper daemon, callback registry, or test-only copy of production logic.

Proof

Use production objects, explicit clocks/seeds/events and failpoints, isolated runtime paths, and minimized fuzz regressions. Run the narrow proof, then make test; use make check when nested, sanitizer, hardware, portal, audio, output, or compatibility behavior is touched. For local configuration, validate every referenced path/argv and compile it, then exercise the affected profile/binding/wallpaper journey on the real target. Never substitute sleeps, blind retries, ambient config, mock-only platform claims, or line coverage for observable proof. The current make check nested journeys require a running Sway host plus swaymsg, grim, jq, xkbcli, and virtual-keyboard and virtual-pointer support; they also rebuild and repeat under ASan/UBSan. Direct frame-stage diagnostics are compile-time-only: rebuild with -DXMM_PERF_TRACE when a live timing journey needs input, spawn/surface-map, client SHM copy, latch, upload, KMS-submit, and page-flip timestamps; summarize stderr with tools/xmm-perf-report.sh <log>. A trace build also accepts SIGUSR1 to capture the current direct composed frame as P6 at XMM_CAPTURE_PPM (default /tmp/xmm-capture.ppm); inspect that artifact with tests/ppm_check or see instead of inferring rendered pixels from protocol logs. For load-sensitive input work, retain an exact short-tap press/release regression, saturate only normal-priority workers, and prove the current direct target has no event-loop GPU wait before restoring a normal build for delivery.

Inspect generated files, dependencies, git diff --check, Redgate impact, and repository status before handoff. Update this skill only when the ownership decision, configuration mechanism, implementation loop, or test gates change; never copy product semantics into it.

Handoff

Report owner: local config | shipped default | capability, requirement impact, changed anchors, tests and live journeys, and remaining target-specific risk. If the real boundary is unavailable, name the blocked proof rather than claiming support.