chore: treeland-protocol-templated wayland protocol authoring skill

.agents/skills/treeland-wayland-protocol/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: treeland-wayland-protocol
+description: Write or update Treeland Wayland protocol XML specifications. Use when the task is to design, draft, review, or version protocol files under xml/, following standard Wayland protocol conventions while correcting non-standard patterns in existing Treeland protocols.
+---
+
+Use this skill when working on Treeland Wayland protocol definitions in this repository.
+
+## Scope
+
+This skill is for:
+- creating a new protocol XML under `xml/`
+- extending an existing protocol in a backward-compatible way
+- preparing a new major version for a backward-incompatible change
+- reviewing protocol XML for naming, versioning, lifecycle, and wording issues
+
+This skill is not for compositor/server implementation details. It only covers the protocol spec layer.
+
+## Workflow
+
+1. Read [references/treeland-wayland-protocol-rules.md](references/treeland-wayland-protocol-rules.md).
+2. Open 2-3 nearby XML files under `xml/` that match the intended style or domain.
+3. Use Treeland-unstable naming by default and only diverge when maintainers explicitly require a stable file line.
+4. Draft or edit the XML using [assets/treeland-protocol-template.xml](assets/treeland-protocol-template.xml) as a starting point when useful.
+5. If adding a new XML file, update `CMakeLists.txt` so it is installed with the rest of the protocol set.
+6. Re-read the final XML once for protocol lifecycle correctness:
+   - object creation and destruction are explicit
+   - events vs requests are directionally correct
+   - error enums are specific and actionable
+   - additions in an existing major version use `since`
+   - naming is consistent across file name, protocol name, interface names, and enum references
+
+## Treeland-specific rules
+
+- Protocol XML files live in `xml/`, not in `stable/`, `staging/`, or `experimental/` directories.
+- Use unstable naming for new Treeland protocols by default: `xml/treeland-foo-unstable-v1.xml` with protocol name `treeland_foo_unstable_v1`.
+- Important repo convention: even for unstable files, interface names usually stay in the form `treeland_foo_bar_v1` rather than `treeland_foo_bar_unstable_v1`. Match neighboring Treeland XMLs unless the repo convention changes.
+- New protocol files must be added to the `XML` list in the top-level `CMakeLists.txt`.
+- Use the repo's SPDX copyright block style from neighboring files.
+- Existing Treeland XML may contain non-standard patterns. Prefer the rules in this skill over preserving those patterns.
+
+## Authoring guidance
+
+- Keep each protocol narrow in scope. If a request starts needing unrelated policy or multiple roles, split the protocol.
+- Prefer clear object lifetimes over implicit state machines.
+- Use `new_id` only when the compositor is creating a protocol object for the client.
+- Within one interface, prefer the order: `description -> enum -> destroy request -> other requests -> events`.
+- Interface descriptions should state the interface purpose and briefly describe the expected workflow when it is not obvious.
+- Manager-style interfaces should provide an explicit `destroy` request.
+- If an interface has a destroy-style request, place it as the first request in that interface.
+- Use `type="destructor"` on explicit destroy requests.
+- Keep all requests before all events inside one interface.
+- Request descriptions should document any required call scenarios, preconditions, and ordering constraints.
+- Put protocol errors in `enum name="error"` when clients can violate required rules.
+- Avoid XML comments for protocol semantics. Put normative and behavioral information in `<description>` blocks. If a short comment is needed for maintenance, keep it non-semantic.
+- Use `since` only for backward-compatible additions inside the same major version. Do not write `since="1"`.
+- If an existing interface gains a new request or event, increment that interface's `version`, append the new member at the end of the existing request or event section, and mark the new member with the matching `since="N"`.
+- For a breaking change, keep the old XML file, add a new `-vN+1` file, rename the protocol and interfaces to the new major suffix, reset interface `version` to `1`, and remove carried-over `since` attributes.
+- Prefer precise `summary` text and concrete descriptions over placeholders.
+- Event descriptions should explain event meaning and the compositor-side trigger timing for emission.
+- When writing normative behavior, use RFC 2119 keywords in lowercase and include the RFC 2119 paragraph in the top-level protocol description if the document relies on those terms normatively.
+
+## Validation
+
+Before finishing:
+- compare the XML against at least one standard Wayland reference spec for structure quality
+- compare against at least one Treeland XML for local naming and packaging conventions, but do not preserve non-standard patterns just because they already exist
+- ensure enum references are fully correct, especially `enum="interface.enum"` where needed
+- ensure nullable object args explicitly use `allow-null="true"`
+- ensure destroy ordering constraints are documented wherever misuse would be a protocol error

.agents/skills/treeland-wayland-protocol/assets/treeland-protocol-template.xml

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="treeland_example_v1">
+    <copyright><![CDATA[
+    SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd.
+    SPDX-License-Identifier: MIT
+    ]]></copyright>
+
+    <description summary="one-line protocol summary">
+        Replace this description with the protocol's purpose, object model, and
+        lifecycle guarantees.
+
+        If this specification uses RFC 2119 keywords normatively, include the
+        standard interpretation paragraph here.
+    </description>
+
+    <interface name="treeland_example_manager_v1" version="1">
+        <description summary="manager global">
+            Describe what this global creates, any singleton or binding rules,
+            and a brief high-level workflow for clients.
+        </description>
+
+        <enum name="error">
+            <entry name="invalid_argument" value="0"
+                summary="an invalid argument was provided"/>
+        </enum>
+
+        <request name="destroy" type="destructor">
+            <description summary="destroy the manager object">
+                Describe whether child objects must be destroyed first.
+            </description>
+        </request>
+
+        <request name="create_example">
+            <description summary="create an example object">
+                Describe ownership, required call scenarios, preconditions, and
+                lifetime expectations.
+            </description>
+            <arg name="id" type="new_id" interface="treeland_example_object_v1"/>
+            <arg name="surface" type="object" interface="wl_surface"/>
+        </request>
+    </interface>
+
+    <interface name="treeland_example_object_v1" version="1">
+        <description summary="example per-object interface">
+            Describe the object's state, lifetime, and relation to Wayland core objects.
+        </description>
+
+        <enum name="mode">
+            <entry name="default" value="0" summary="default mode"/>
+        </enum>
+
+        <request name="destroy" type="destructor">
+            <description summary="destroy the object">
+                Describe any ordering constraints with related objects.
+            </description>
+        </request>
+
+        <request name="set_mode">
+            <description summary="set pending mode">
+                Describe whether this is immediate or latched until commit.
+            </description>
+            <arg name="mode" type="uint" enum="mode" summary="requested mode"/>
+        </request>
+
+        <event name="configured">
+            <description summary="notify current state">
+                Describe event meaning, compositor-side trigger timing, and what
+                the client should do next.
+            </description>
+            <arg name="serial" type="uint" summary="configuration serial"/>
+        </event>
+    </interface>
+</protocol>

.agents/skills/treeland-wayland-protocol/references/treeland-wayland-protocol-rules.md

@@ -0,0 +1,167 @@
+# Treeland Wayland Protocol Rules
+
+This reference condenses standard Wayland protocol conventions together with the packaging and naming conventions used in this repository.
+
+## 1. Source of truth
+
+When drafting a protocol:
+- use standard Wayland reference protocols as the style reference for XML structure and protocol evolution
+- use `xml/` as the source of Treeland-specific naming and packaging conventions
+
+Do not copy a reference protocol mechanically. Reuse its structure only when the lifecycle matches.
+
+## 2. Naming and versioning
+
+Treeland protocol defaults for this repo:
+- file: `xml/treeland-foo-unstable-v1.xml`
+- protocol: `treeland_foo_unstable_v1`
+- interfaces usually still end with `_v1` and usually do not include `_unstable`
+- if maintainers later stabilize a protocol line, follow the naming convention requested in that stabilization review
+
+Backward-compatible extension:
+- keep the same file
+- keep the same interface major version suffix
+- raise interface `version`
+- add `since="N"` on each new request, event, enum entry, or arg introduced in version `N`
+- never write `since="1"`
+- append newly added requests or events after the existing ones instead of reordering old members
+
+Backward-incompatible extension:
+- create a new file with the next major version
+- keep the old file in the tree for compatibility
+- rename the protocol and interfaces to the new major suffix
+- reset interface versions to `1`
+- remove old `since` attributes unless needed again within the new major line
+
+## 3. XML structure
+
+Recommended order:
+1. XML declaration
+2. `<protocol>`
+3. `<copyright><![CDATA[ ... ]]></copyright>`
+4. optional top-level `<description>`
+5. one or more `<interface>`
+
+Recommended interface order:
+1. interface description
+2. enums, if any
+3. destroy request, if the interface has one
+4. constructor-style requests
+5. regular requests
+6. events
+
+Within one interface, keep enums before requests, and keep requests before events. Existing Treeland files vary, but new or updated protocol work should follow this ordering.
+
+## 4. Description quality
+
+Descriptions should answer:
+- who owns the object
+- who creates it
+- when it becomes invalid
+- which sequencing constraints are illegal
+- whether the compositor or client defines a behavior
+
+Good protocol text is concrete:
+- say what triggers an event
+- say whether state is latched, pending, or immediately applied
+- say whether an object is singleton, per-output, per-surface, or per-session
+
+Description minimums by member type:
+- interface description should explain the interface purpose and, when useful, the high-level workflow
+- request description should explain required call scenarios and ordering/precondition constraints
+- event description should explain event meaning and compositor-side trigger timing
+
+Avoid:
+- vague summaries like "do something"
+- implementation detail that does not affect the wire contract
+- undocumented one-shot objects or hidden lifecycle rules
+- semantic requirements hidden in XML comments
+
+## 5. Requests, events, and errors
+
+Use requests for client-to-compositor actions.
+
+Use events for compositor-to-client notifications.
+
+Manager-style interfaces should generally expose `destroy`.
+
+Create a dedicated error enum when the client can violate protocol rules such as:
+- using an object after required destruction ordering
+- passing an invalid role target
+- calling a one-shot request multiple times
+- providing out-of-range values
+
+Prefer specific error entries over a generic `failed`.
+
+## 6. Object model heuristics
+
+Prefer manager/object splits:
+- manager global creates session/object instances
+- per-object interfaces own ongoing state and events
+
+Prefer separate objects when:
+- lifetime differs from the manager
+- events only make sense after setup
+- the API would otherwise need ad-hoc request ordering rules
+
+Avoid turning one interface into a grab-bag of unrelated features.
+
+## 7. Arg conventions
+
+Use:
+- `new_id` for created protocol objects
+- `object` for existing protocol objects such as `wl_output`, `wl_surface`, `wl_buffer`, `wl_callback`, `wl_compositor`, `wl_seat`, `wl_pointer`, `wl_touch`, and `wl_keyboard`
+- `allow-null="true"` only when null is explicitly valid
+- `enum="..."` on integer args that reference enums
+- `bitfield="true"` on enum definitions used as flag sets
+
+Add `summary` for args when it materially improves readability.
+
+## 8. XML comments
+
+Reference protocols do use XML comments in a few places, most commonly to mark versioned additions. However, comments are not a good place for protocol semantics.
+
+Rule for Treeland skills:
+- do not place normative behavior, sequencing rules, or lifecycle requirements in XML comments
+- prefer `<description>` blocks for anything a protocol reader must understand
+- use comments only sparingly for short maintenance markers
+
+## 9. RFC 2119 usage
+
+If the protocol text relies on words like `must`, `should`, or `may` normatively, add a top-level protocol description that includes the RFC 2119 interpretation paragraph used by standard Wayland protocol specifications.
+
+Do not add that paragraph if the protocol text is otherwise non-normative.
+
+## 10. Treeland repo integration
+
+When adding a new protocol file:
+- place it under `xml/`
+- add it to the `XML` list in the repository `CMakeLists.txt`
+- follow the local SPDX block:
+
+```xml
+<copyright><![CDATA[
+SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd.
+SPDX-License-Identifier: MIT
+]]></copyright>
+```
+
+Match the year range used by neighboring files when editing an existing protocol family.
+
+## 11. Review checklist
+
+Before considering the XML finished, check:
+- file name, protocol name, and interface suffixes all agree
+- interface `version` matches the highest supported additive version
+- new additions in an existing interface have `since`
+- no member is annotated with `since="1"`
+- newly added requests and events were appended without reordering older members
+- destructor requests are marked `type="destructor"`
+- enums, if present, appear before requests
+- if an interface has a destroy request, it is the first request
+- requests appear before events
+- object lifetime constraints are documented
+- event ordering constraints are documented where required
+- all enum references resolve correctly
+- nullable args are intentional
+- the protocol is added to `CMakeLists.txt` if it is new