commit 90042d1d7b69ab147d6cf7404b7ae689b2a4b736 Author: tmk241 Date: Mon Aug 10 23:20:57 2026 +0200 Add XMM workstation skill diff --git a/README.md b/README.md new file mode 100644 index 0000000..da78880 --- /dev/null +++ b/README.md @@ -0,0 +1,22 @@ +# XMM skills + +Pi agent skills for configuring, implementing, debugging, porting, and reviewing +[XMM](https://git.tmk241.com/tmk241/xmm). + +## Install for the XMM checkout + +From `/opt/repositories/xmm`: + +```sh +mkdir -p .agents/skills +ln -s ../../../xmm-skills/skills/xmm-workstation .agents/skills/xmm-workstation +``` + +The link keeps the skill discoverable at the project-local path elected by +XMM's `AGENTS.md`, while this repository remains its canonical source. + +## Routing smoke + +- Positive: “Debug delayed keyboard release events in XMM” loads + `xmm-workstation` and requires proof on the real input path. +- Negative: “Revise XMM's product requirements” does not load the skill. diff --git a/skills/xmm-workstation/SKILL.md b/skills/xmm-workstation/SKILL.md new file mode 100644 index 0000000..f0865a8 --- /dev/null +++ b/skills/xmm-workstation/SKILL.md @@ -0,0 +1,122 @@ +--- +name: xmm-workstation +description: >- + 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 `. 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.