---
name: neru-add-platform-feature
description: "Implement or stub Neru functionality for a specific OS/backend: port contract, build-tagged file slots, factory wiring, CodeNotSupported stubs, capability matrix, contract tests, and the docs ownership table. Use for any change under internal/adapter/platform or any *_darwin/_linux/_windows file. Not for pure-Go domain logic."
---

# Platform work in Neru

Platform code carries Neru's strictest guardrails, and this is where agents
most often guess. A change that lands cleanly sits in an existing file slot,
crosses the boundary through a port, returns `CodeNotSupported` wherever it is
unimplemented, and reports itself honestly in the capability matrix.

## Before writing code

1. Read `internal/adapter/platform/AGENTS.md` — the single home for the rules
   this skill obeys: the One Rule, file slots, the factory and Linux's runtime
   compositor axis, loud stubs, capability honesty, coordinates, generated
   Wayland bindings. Add the `darwin/` or `linux/` guide for the native
   boundary you touch.
2. Read `internal/adapter/platform/profile.go`. It is the source of truth for
   each subsystem's backend family, primary-modifier expectations, and whether
   a backend needs CGO. CGO is a **per-backend** decision, not a per-OS one.
3. Read the port you're implementing in `internal/ports/`. If the capability
   doesn't have a port yet, define the interface there first and add a mock in
   `internal/ports/mocks`.

## Tests

- Unit tests with port mocks stay platform-neutral.
- Real-OS behavior goes in `*_integration_<os>_test.go` tagged
  `//go:build integration && <os>`.
- Contract tests pin `CodeNotSupported` per subsystem, not per stub. Update the
  subsystem's existing one if it has one, and write a new one when a caller
  could read the stub's `nil` as success, so a later "implementation" that
  silently no-ops fails a test. `internal/adapter/platform/AGENTS.md` names the
  ones that exist.

## Docs (same change, not a follow-up)

`docs/contributing/porting.md` has the ownership table ("Documentation Checklist") —
each fact has exactly one home. Capability status goes in
`docs/reference/platform-support.md`, the API or protocol behind it in
`docs/contributing/platform-internals.md`, and never either in
`docs/contributing/architecture.md` (shape only).
Linux setup specifics go in `docs/guide/linux.md` / `docs/guide/linux-desktops.md`.

## Verify

```bash
just lint                      # depguard enforces the One Rule
go test ./internal/architecture/
just test-foundation
```

Cross-compile the platforms you touched (`just build-linux`,
`just build-windows`) even when you can't run them — build tags hide breakage
from a darwin-only `just build`. Then the standard pre-commit gate, and ask a
maintainer to run integration tests on the target OS if you can't.