Skip to content

y3owk1n/neru / .agents/skills/neru-add-platform-feature

neru-add-platform-feature

Verified

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"), and 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

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, because 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.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall