treeland-wayland-protocol

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.
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 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".
• If an interface version is raised, review any nearby interface that creates it with new_id, returns it from a request, or exposes it from an event; if that dependency changes the observable contract for clients, raise the exposing interface version as well.
• 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