From 34d1ffd26bdcb091e281ca17cd10c52e69f75683 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 9 Jul 2026 15:46:01 -0700 Subject: [PATCH 1/4] AGENTS.md: add Supported Development Platforms rule (#228 s0) Encode the retrospective's headline cross-platform decision framework: cross-platform (Win+macOS+Linux via WSL2/devcontainer) by default; narrow a repo's platform only for a hard runtime ceiling set by its dependencies (e.g. a Home Assistant integration is Linux-only), decided per repo and recorded in the repo. The narrowing axis is where code executes for dev/testing, not where editing happens. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 770d9f73..2760e5e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -245,6 +245,12 @@ The CI lint job runs these tools (workflow YAML and Markdown), but run them loca When pulling a public image fails on a Docker-Desktop/WSL credential-helper error (`docker-credential-desktop.exe: exec format error`), retry with an empty Docker config: `DOCKER_CONFIG=$(mktemp -d) docker run ...` after writing `{}` to `$DOCKER_CONFIG/config.json`. +## Supported Development Platforms + +- **Cross-platform by default - Windows + macOS + Linux.** The devcontainer (WSL2 on Windows) gives every contributor the same Linux toolchain, and editing is cross-platform through the GUI regardless of where code runs. Assume this default. +- **A repo's platform ceiling is set by its dependencies, not tooling effort; decide it per repo before writing dev tooling.** Narrow below the default only for a hard runtime ceiling - the code can only execute or test on one platform (e.g. a Home Assistant integration is Linux-only: HA Core has POSIX-only dependencies and will not run natively on Windows, so even maximal tooling yields only lint-only there). The narrowing axis is where code *executes* for dev/testing (where the VS Code Server engine runs), never where editing happens. +- **Record a narrowed platform and its reason in the repo** (README/AGENTS) so the restriction reads as a deliberate dependency ceiling, not an omission. + ## Devcontainer Contributors commit to this repo with signed commits; the SSH-signing setup lives in [docs/ssh-signing.md](./docs/ssh-signing.md), host prerequisites in [docs/host-setup.md](./docs/host-setup.md), and devcontainer SSH-agent forwarding in [docs/devcontainer.md](./docs/devcontainer.md). This repo ships no application toolchain; the per-language devcontainer definitions it once used are kept as reference under [`catalog/snippets/devcontainer/`](./catalog/snippets/devcontainer/). From 70a4ec5bae0c5ff20fb975acc2693575eefeb05d Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 9 Jul 2026 15:48:16 -0700 Subject: [PATCH 2/4] AGENTS.md: clarify Linux can be native, not only WSL2/devcontainer Linux dev runs natively (Linux desktop, or SSH/remote into a Linux host) as well as via WSL2 or a devcontainer; the latter two carry their own nuances but deliver the same toolchain. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2760e5e5..2d2880bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -247,7 +247,7 @@ When pulling a public image fails on a Docker-Desktop/WSL credential-helper erro ## Supported Development Platforms -- **Cross-platform by default - Windows + macOS + Linux.** The devcontainer (WSL2 on Windows) gives every contributor the same Linux toolchain, and editing is cross-platform through the GUI regardless of where code runs. Assume this default. +- **Cross-platform by default - Windows + macOS + Linux.** Linux runs natively (a Linux desktop, or SSH/remote into a Linux host) or through WSL2 or a devcontainer on Windows/macOS - the latter two carry their own nuances (mounts, path translation, SSH-agent forwarding) but deliver the same toolchain. Editing is cross-platform through the GUI regardless of where code runs. Assume this default. - **A repo's platform ceiling is set by its dependencies, not tooling effort; decide it per repo before writing dev tooling.** Narrow below the default only for a hard runtime ceiling - the code can only execute or test on one platform (e.g. a Home Assistant integration is Linux-only: HA Core has POSIX-only dependencies and will not run natively on Windows, so even maximal tooling yields only lint-only there). The narrowing axis is where code *executes* for dev/testing (where the VS Code Server engine runs), never where editing happens. - **Record a narrowed platform and its reason in the repo** (README/AGENTS) so the restriction reads as a deliberate dependency ceiling, not an omission. From 32c65eadf75d1538d7a3b4d1dcee5153bacdde7d Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 9 Jul 2026 15:50:34 -0700 Subject: [PATCH 3/4] AGENTS.md: fix platform routes - WSL2 is Windows-only, devcontainer Win/mac Correct wording that implied WSL2 runs on macOS. Devcontainer covers Windows and macOS; WSL2 is Windows-only. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2d2880bd..9ad9f586 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -247,7 +247,7 @@ When pulling a public image fails on a Docker-Desktop/WSL credential-helper erro ## Supported Development Platforms -- **Cross-platform by default - Windows + macOS + Linux.** Linux runs natively (a Linux desktop, or SSH/remote into a Linux host) or through WSL2 or a devcontainer on Windows/macOS - the latter two carry their own nuances (mounts, path translation, SSH-agent forwarding) but deliver the same toolchain. Editing is cross-platform through the GUI regardless of where code runs. Assume this default. +- **Cross-platform by default - Windows + macOS + Linux.** Linux runs natively (a Linux desktop, or SSH/remote into a Linux host), through a devcontainer on Windows or macOS, or through WSL2 on Windows - the devcontainer and WSL routes carry their own nuances (mounts, path translation, SSH-agent forwarding) but deliver the same toolchain. Editing is cross-platform through the GUI regardless of where code runs. Assume this default. - **A repo's platform ceiling is set by its dependencies, not tooling effort; decide it per repo before writing dev tooling.** Narrow below the default only for a hard runtime ceiling - the code can only execute or test on one platform (e.g. a Home Assistant integration is Linux-only: HA Core has POSIX-only dependencies and will not run natively on Windows, so even maximal tooling yields only lint-only there). The narrowing axis is where code *executes* for dev/testing (where the VS Code Server engine runs), never where editing happens. - **Record a narrowed platform and its reason in the repo** (README/AGENTS) so the restriction reads as a deliberate dependency ceiling, not an omission. From d1bb6424696dd5fa053c08d4fed152b3f4f95a15 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 9 Jul 2026 15:52:22 -0700 Subject: [PATCH 4/4] AGENTS.md: make the execution axis tool-agnostic Drop the VS Code Server parenthetical; dev/test execution is native, SSH-remote, container, or CI - not tied to VS Code Remote. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9ad9f586..a1ffc6ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -248,7 +248,7 @@ When pulling a public image fails on a Docker-Desktop/WSL credential-helper erro ## Supported Development Platforms - **Cross-platform by default - Windows + macOS + Linux.** Linux runs natively (a Linux desktop, or SSH/remote into a Linux host), through a devcontainer on Windows or macOS, or through WSL2 on Windows - the devcontainer and WSL routes carry their own nuances (mounts, path translation, SSH-agent forwarding) but deliver the same toolchain. Editing is cross-platform through the GUI regardless of where code runs. Assume this default. -- **A repo's platform ceiling is set by its dependencies, not tooling effort; decide it per repo before writing dev tooling.** Narrow below the default only for a hard runtime ceiling - the code can only execute or test on one platform (e.g. a Home Assistant integration is Linux-only: HA Core has POSIX-only dependencies and will not run natively on Windows, so even maximal tooling yields only lint-only there). The narrowing axis is where code *executes* for dev/testing (where the VS Code Server engine runs), never where editing happens. +- **A repo's platform ceiling is set by its dependencies, not tooling effort; decide it per repo before writing dev tooling.** Narrow below the default only for a hard runtime ceiling - the code can only execute or test on one platform (e.g. a Home Assistant integration is Linux-only: HA Core has POSIX-only dependencies and will not run natively on Windows, so even maximal tooling yields only lint-only there). The narrowing axis is where code *executes* for dev and testing - native, SSH-remote, container, or CI - never where editing happens. - **Record a narrowed platform and its reason in the repo** (README/AGENTS) so the restriction reads as a deliberate dependency ceiling, not an omission. ## Devcontainer