Add/Update copilot instruction

.github/instructions/agent-skills.instructions.md

@@ -0,0 +1,57 @@
+---
+description: 'Guidelines for creating Agent Skills for GitHub Copilot in the WSL repo'
+applyTo: '.github/skills/**/SKILL.md'
+---
+
+# Agent Skills File Guidelines — WSL
+
+Instructions for creating Agent Skills that enhance GitHub Copilot with WSL-specific capabilities.
+
+## What Are Agent Skills?
+
+Self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities. Each skill lives in `.github/skills/<skill-name>/` and must contain a `SKILL.md` file.
+
+Key characteristics:
+- **Progressive loading**: Only loaded when relevant to the user's request
+- **Resource-bundled**: Can include scripts, templates, examples
+- **Portable**: Works across VS Code, Copilot CLI, and coding agent
+
+## Required SKILL.md Format
+
+### Frontmatter
+
+```yaml
+---
+name: wsl-debugging
+description: Toolkit for debugging WSL issues using ETL tracing, debug console, and log collection. Use when asked to diagnose WSL crashes, networking problems, filesystem issues, or collect diagnostic logs.
+---
+```
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | Yes | Lowercase, hyphens, max 64 chars |
+| `description` | Yes | Capabilities + triggers + keywords, max 1024 chars |
+
+### Description Best Practices
+
+The `description` is the PRIMARY mechanism for skill discovery. Include:
+1. **WHAT** the skill does
+2. **WHEN** to use it (triggers, scenarios)
+3. **Keywords** users might mention
+
+## Bundling Resources
+
+| Folder | Purpose | Example |
+|--------|---------|---------|
+| `scripts/` | Executable automation | `collect-traces.ps1` |
+| `references/` | Documentation the agent reads | `etl-providers.md` |
+| `templates/` | Starter code the agent modifies | `new-test.cpp` |
+
+Reference with relative paths: `See [ETL guide](./references/etl-providers.md)`
+
+## Content Guidelines
+
+- Imperative mood: "Run", "Create", "Configure"
+- Include exact commands with WSL-specific parameters
+- Keep SKILL.md body under 500 lines; split into `references/`
+- No hardcoded credentials or secrets

.github/instructions/agents.instructions.md

@@ -0,0 +1,90 @@
+---
+description: 'Guidelines for creating custom agent files for GitHub Copilot in the WSL repo'
+applyTo: '**/*.agent.md'
+---
+
+# Custom Agent File Guidelines — WSL
+
+Instructions for creating custom agent files that provide specialized expertise for WSL development tasks in GitHub Copilot.
+
+## File Basics
+
+- File format: Markdown with YAML frontmatter
+- Naming: lowercase with hyphens (e.g., `wsl-build-helper.agent.md`)
+- Location: `.github/agents/` directory (create this directory when adding the first agent file)
+- Purpose: Define specialized agents with tailored expertise for WSL development
+
+## Example Frontmatter
+
+```yaml
+---
+description: 'Brief description of the agent purpose and capabilities'
+# name: 'Agent Display Name'      # Optional
+# tools: ['read', 'edit', 'search']  # Optional
+# model: 'Claude Sonnet 4.5'      # Optional
+---
+```
+
+### Core Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `description` | **Yes** | Concise purpose statement (50–150 chars) |
+| `name` | No | Display name; defaults to filename |
+| `tools` | No | Tool list; omit for all tools |
+| `model` | Optional | AI model to use |
+| `target` | No | `'vscode'` or `'github-copilot'` |
+| `infer` | No | Auto-activate on context match (default: `true`) |
+| `handoffs` | No | Workflow transitions to other agents (VS Code 1.106+) |
+
+## Tool Configuration
+
+### Standard Tool Aliases
+
+| Alias | Description |
+|-------|-------------|
+| `execute` | Execute shell commands (PowerShell/Bash) |
+| `read` | Read file contents |
+| `edit` | Edit and modify files |
+| `search` | Search for files or text |
+| `agent` | Invoke other custom agents |
+| `web` | Fetch web content and search |
+
+### Tool Selection for WSL Agents
+
+- **Build agents**: `['read', 'search', 'execute']` — need shell for cmake/msbuild
+- **Code review agents**: `['read', 'search']` — read-only sufficient
+- **Test agents**: `['read', 'search', 'execute']` — need shell for TAEF
+- **Documentation agents**: `['read', 'edit', 'search']` — need edit for doc files
+
+## Agent Prompt Structure
+
+1. **Agent Identity and Role**: Primary expertise
+2. **Core Responsibilities**: Specific tasks
+3. **WSL Context**: Key paths, build system, platform constraints
+4. **Guidelines and Constraints**: What to do/avoid
+5. **Output Expectations**: Expected format
+
+## Handoffs (VS Code 1.106+)
+
+```yaml
+handoffs:
+  - label: Run Tests
+    agent: wsl-test-helper
+    prompt: 'Run the full test suite on the build we just completed.'
+    send: false
+```
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `label` | Yes | Button text shown in chat |
+| `agent` | Yes | Target agent identifier |
+| `prompt` | No | Pre-filled prompt for the target agent |
+| `send` | No | Auto-submit (default: `false`) |
+
+## Sub-Agent Invocation
+
+- Include `agent` in the orchestrator's `tools` list.
+- Pass paths and identifiers, not full file contents.
+- Sub-agents inherit tool ceiling from parent's `tools` list.
+- Limit to 5–10 sequential steps; use a single agent for bulk work.

.github/instructions/architecture.instructions.md

@@ -0,0 +1,155 @@
+---
+description: 'WSL architecture overview — component map, boot sequence, communication patterns, and key source files'
+applyTo: 'src/**'
+---
+
+# WSL Architecture
+
+Reference: https://wsl.dev/technical-documentation/
+
+WSL is composed of Windows executables, Linux binaries, COM interfaces, and hvsocket communication channels.
+
+## Component Diagram
+
+Source: https://wsl.dev/technical-documentation/ (Mermaid flowchart)
+
+```
+┌─────────────────────────── Windows ───────────────────────────────┐
+│                                                                    │
+│  C:\Windows\System32\wsl.exe ──CreateProcess()──► wsl.exe         │
+│                                                     │ COM         │
+│  wslg.exe ──────────────── COM ──────────────►  wslservice.exe    │
+│  wslapi.dll ──────────────── COM ──────────────►    │             │
+│    ▲ LoadLibrary()                                  │             │
+│  debian.exe, ubuntu.exe, ...            CreateProcessAsUser()     │
+│                                          ┌──────────┴──────────┐  │
+│  Windows filesystem                 wslrelay.exe    wslhost.exe   │
+│  (\\\\wsl.localhost)                                                │
+│        │                                                          │
+└────────┼──────────────────────────────────────────────────────────┘
+         │ hvsocket              │ hvsocket          │ hvsocket
+         │                       │                   │
+┌────────┼───────────────────────┼───────────────────┼──── Linux ───┐
+│        │                       │                   │              │
+│        │              mini_init ◄──────────────────┘              │
+│        │                │  exec()    │ exec()    │ exec()         │
+│        │               gns          init       localhost          │
+│        │                             │                            │
+│        │          ┌── Linux Distribution ──────────────────┐      │
+│        │          │  init ──exec()──► plan9                │      │
+│        ▼          │    │──exec()──► session leader          │      │
+│      plan9 ◄──────│    │             │──exec()──► relay     │      │
+│                   │    │                          │         │      │
+│                   │    │               fork(),exec()        │      │
+│                   │    │                   ▼                │      │
+│                   │    │           User command (bash)      │      │
+│                   └────────────────────────────────────────┘      │
+└───────────────────────────────────────────────────────────────────┘
+
+Communication: wsl.exe ◄──hvsocket──► relay (stdin/stdout/stderr)
+               wslservice.exe ◄──hvsocket──► mini_init, gns, init
+               Windows filesystem ◄──hvsocket──► plan9
+```
+
+## Windows Components
+
+| Component | Source | Purpose | Docs |
+|-----------|--------|---------|------|
+| **wsl.exe** | `src/windows/wsl/` | Main CLI entrypoint. Parses args (`src/windows/common/WslClient.cpp`), calls wslservice via COM (`src/windows/common/svccomm.cpp`), relays stdin/stdout/stderr (`src/windows/common/relay.cpp`). | [wsl.exe](https://wsl.dev/technical-documentation/wsl.exe/) |
+| **wslservice.exe** | `src/windows/service/` | Session 0 service (SYSTEM). Manages WSL sessions, VM lifecycle, distribution registration. COM interface: `ILxssUserSession` (defined in `src/windows/service/inc/wslservice.idl`). | [wslservice.exe](https://wsl.dev/technical-documentation/wslservice.exe/) |
+| **wslhost.exe** | `src/windows/wslhost/` | Desktop notifications (`src/windows/common/notifications.cpp`) and background Linux process lifetime management. | [wslhost.exe](https://wsl.dev/technical-documentation/wslhost.exe/) |
+| **wslrelay.exe** | `src/windows/wslrelay/` | Relays localhost network traffic (NAT mode) and debug console output from Linux to Windows. | [wslrelay.exe](https://wsl.dev/technical-documentation/wslrelay.exe/) |
+| **wslg.exe** | `src/windows/wslg/` | Like wsl.exe but Win32 (not console) — for graphical Linux apps without a console window. | [wslg.exe](https://wsl.dev/technical-documentation/wslg.exe/) |
+| **wslconfig.exe** | (no standalone source directory) | Configure WSL distributions. Functionality integrated with other WSL executables. | [wslconfig.exe](https://wsl.dev/technical-documentation/wslconfig.exe/) |
+| **wslapi.dll / libwsl** | `src/windows/libwsl/` | Public WSL API DLL (used by distribution launchers like ubuntu.exe). | [wslapi.dll](https://learn.microsoft.com/windows/win32/api/wslapi/) |
+| **wslsettings** | `src/windows/wslsettings/` | WinUI 3 / C# settings app (MVVM, .NET 8.0, WindowsAppSDK). | — |
+| **wslinstall** | `src/windows/wslinstall/` | Installation executables. | — |
+
+## Linux Components
+
+| Component | Source | Purpose | Docs |
+|-----------|--------|---------|------|
+| **mini_init** | `src/linux/init/` (entrypoint) | First process in WSL2 VM. Mounts filesystems, configures logging, connects hvsockets to wslservice, launches gns and distributions. | [mini_init](https://wsl.dev/technical-documentation/mini_init/) |
+| **gns** | `src/linux/init/GnsEngine.cpp` | Networking configuration (IP, routing, DNS, MTU). Maintains hvsocket to wslservice. Handles DNS tunneling. | [gns](https://wsl.dev/technical-documentation/gns/) |
+| **init** | `src/linux/init/` | Top-level process per distribution. Mounts /proc, /sys, /dev; configures cgroups; registers binfmt; starts systemd; mounts drvfs; creates session leaders. | [init](https://wsl.dev/technical-documentation/init/) |
+| **session leader** | `src/linux/init/` | Forked from init. Creates Linux processes on behalf of users. Each is associated with a Windows console. | [session leader](https://wsl.dev/technical-documentation/session-leader/) |
+| **relay** | `src/linux/init/` | Created by session leader (WSL2). Creates hvsocket channels for stdin/stdout/stderr relay to wsl.exe. Forks into user process. | [relay](https://wsl.dev/technical-documentation/relay/) |
+| **plan9** | `src/linux/init/plan9.cpp` (server entrypoint) + `src/linux/plan9/` (protocol implementation) | Plan9 filesystem server for accessing Linux files from Windows (`\\wsl.localhost\<distro>`). Windows-side uses p9rdr.sys redirector driver. | [plan9](https://wsl.dev/technical-documentation/plan9/) |
+| **localhost** | `src/linux/init/localhost.cpp` | Forwards network traffic between WSL2 VM and Windows. NAT: watches TCP ports. Mirrored: BPF intercepts bind(). | [localhost](https://wsl.dev/technical-documentation/localhost/) |
+
+## Shared Code
+
+- `src/shared/` — Cross-platform code (config file parsing, message definitions)
+- `src/shared/inc/lxinitshared.h` — Message definitions for mini_init, init, gns channels
+
+## Communication Patterns
+
+- **Windows ↔ Linux**: hvsocket channels (Hyper-V sockets)
+- **Windows clients ↔ wslservice**: COM (`ILxssUserSession`)
+- **Linux files → Windows**: Plan9 protocol via p9rdr.sys (`\\wsl$`, `\\wsl.localhost`)
+- **Windows drives → Linux**: drvfs mounts under `/mnt/` (plan9/virtio-plan9/virtiofs per config)
+
+## WSL2 Boot Sequence
+
+1. `wsl.exe` → calls `CreateInstance()` on `wslservice.exe` via COM
+2. `wslservice.exe` → creates VM via Host Compute System (HCS) (`WslCoreVm.cpp`, `HcsCreateComputeSystem()`)
+3. VM kernel boots → executes `mini_init` from initramfs
+4. `mini_init` → mounts filesystems, receives `LxMiniInitMessageEarlyConfig` via hvsocket, launches `gns`
+5. `wslservice.exe` sends `LxMiniInitMessageLaunchInit` → `mini_init` mounts distro VHD, launches `init`
+6. `init` → configures distribution (cgroups, binfmt, systemd, drvfs), connects hvsocket to wslservice
+7. `wslservice.exe` sends `LxInitMessageCreateSession` → `init` forks session leader
+8. Session leader forks `relay` → relay creates hvsocket channels for stdio, forks user process (bash)
+9. `wsl.exe` receives stdio hvsocket handles, relays terminal I/O
+
+## Linux Entrypoint Dispatcher
+
+The `/init` binary serves multiple roles. `main()` in `src/linux/init/main.cpp` calls `WslEntryPoint()` in `src/linux/init/init.cpp`, which checks `argv[0]` (as `Argv[]`) to determine which logic to run:
+- `init` → distribution init
+- `plan9` → Plan9 filesystem server
+- `localhost` → network forwarding
+- `mount.drvfs` → drive mounting (`MountDrvfsEntry()` in `src/linux/init/drvfs.cpp`)
+- Anything else → Windows interop (binfmt, `src/linux/init/binfmt.cpp`)
+
+See `WslEntryPoint()` in `src/linux/init/init.cpp`.
+
+## Windows Interop (Running Windows Executables from Linux)
+
+- Binfmt interpreter registered at `/proc/sys/fs/binfmt_misc/WSLInterop`, points to `/init`
+- Interop servers listen at unix sockets under `/run/WSL/`, discovered via `$WSL_INTEROP` env var
+- `/init` sends `LxInitMessageCreateProcess` (WSL1) or `LxInitMessageCreateProcessUtilityVm` (WSL2) to Windows
+
+## Systemd Integration
+
+- Enabled via `/etc/wsl.conf` → `[boot] systemd=true`
+- When enabled, `init` forks: parent runs `/sbin/init` (systemd) as PID 1, child continues WSL config
+- WSL creates systemd config files under `/run` to protect binfmt interpreter and X11 socket
+
+## Drvfs (Accessing Windows Drives from Linux)
+
+- WSL maintains two mount namespaces per distribution: elevated and non-elevated
+- Plan9 file server started per session leader, mounted by `init`
+- Manual mounting: `mount -t drvfs C: /tmp/my-mount-point`
+
+## Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `src/windows/service/exe/WslCoreVm.cpp` | VM management |
+| `src/windows/service/exe/LxssUserSession.cpp` | COM session (per Windows user) |
+| `src/windows/service/exe/LxssUserSessionFactory.cpp` | COM factory |
+| `src/windows/service/exe/WslCoreInstance.cpp` | Per-distribution instance |
+| `src/windows/service/exe/DistributionRegistration.cpp` | Distribution registry lookup |
+| `src/windows/service/exe/Lifetime.cpp` | Process lifetime association |
+| `src/windows/common/GnsChannel.cpp` | Windows-side networking channel |
+| `src/windows/common/WslClient.cpp` | CLI argument parsing |
+| `src/windows/common/svccomm.cpp` | COM communication helpers |
+| `src/windows/common/relay.cpp` | Stdio relay logic |
+| `src/windows/common/hcs_schema.h` | HCS VM JSON schema |
+| `src/shared/inc/lxinitshared.h` | Message definitions |
+| `src/linux/init/main.cpp` | Linux main() entrypoint |
+| `src/linux/init/init.cpp` | WslEntryPoint() — argv[0] dispatcher |
+| `src/linux/init/GnsEngine.cpp` | Linux-side networking |
+| `src/linux/init/plan9.cpp` | Plan9 filesystem server |
+| `src/linux/init/binfmt.cpp` | Windows interop |
+| `src/linux/init/drvfs.cpp` | Drive mounting |
+| `src/linux/init/localhost.cpp` | Localhost network forwarding |

.github/instructions/azure-devops-pipelines.instructions.md

@@ -0,0 +1,63 @@
+---
+description: 'Best practices for WSL Azure DevOps pipeline YAML files'
+applyTo: '.pipelines/**/*.yml'
+---
+
+# Azure DevOps Pipeline YAML — WSL
+
+WSL CI/CD pipelines live under `.pipelines/` and use Azure DevOps (not GitHub Actions for builds). The pipelines handle PR validation, nightly builds, release builds, and localization through OneBranch.
+
+## Pipeline Inventory
+
+| Pipeline | Purpose |
+|----------|---------|
+| `wsl-build-pr.yml` / `wsl-build-pr-onebranch.yml` | PR validation builds |
+| `wsl-build-nightly-onebranch.yml` | Nightly builds |
+| `wsl-build-nightly-localization.yml` | Nightly localization sync |
+| `wsl-build-release-onebranch.yml` | Release builds |
+| `wsl-build-notice.yml` | NOTICE file generation |
+| `build-stage.yml` | Shared build stage template |
+| `test-stage.yml` / `test-job.yml` | Shared test stage/job templates |
+| `nuget-stage.yml` | NuGet package stage template |
+| `flight-stage.yml` | Flighting stage template |
+
+## General Guidelines
+
+- Use YAML syntax consistently with 2-space indentation.
+- Always include meaningful `displayName` values for stages, jobs, and steps.
+- Use templates (`build-stage.yml`, `test-stage.yml`, etc.) for reusable pipeline components.
+- Keep pipeline files focused and modular — split stages into separate template files.
+
+## WSL-Specific Build Considerations
+
+- WSL builds require Windows agents with Visual Studio and Windows SDK 26100.
+- Builds target both x64 and ARM64 — use matrix strategies or separate jobs.
+- Full builds take 20–45 minutes; set appropriate timeouts.
+- NuGet restore uses a custom Azure DevOps feed (see `nuget.config`).
+- MSIX and MSI packaging are part of the build pipeline.
+
+## Variable and Parameter Management
+
+- Use variable groups for shared configuration across pipelines.
+- Secure sensitive variables and mark them as secrets.
+- Use runtime parameters for flexible pipeline execution (e.g., build configuration, target platform).
+
+## Testing Integration
+
+- Tests use the TAEF framework and require a full build before execution.
+- Full test suite takes 30–60 minutes — set timeout to 90+ minutes.
+- Tests require Administrator privileges on the agent.
+- Publish test results in VSTest format.
+
+## Branch and Trigger Strategy
+
+- Use path filters to trigger builds only when relevant files change (exclude `doc/`, `README.md`).
+- Configure PR triggers for code validation.
+- Use scheduled triggers for nightly builds and localization syncs.
+
+## Common Anti-Patterns to Avoid
+
+- Hardcoding sensitive values directly in YAML files.
+- Using overly broad triggers that cause unnecessary builds.
+- Not using proper naming conventions for stages and jobs.
+- Creating monolithic pipelines instead of using template composition.