PowerShell/openssh-portable

.github/ — AI-Assisted Development for OpenSSH-Portable (Windows Fork)

This folder contains everything needed to work on the PowerShell team's Windows fork of OpenSSH-Portable with AI assistance in VS Code (GitHub Copilot Chat / agent mode). It bundles together agents, prompts, instructions, skills, and a set of PowerShell tools exposed as an MCP server so that complex workflows (especially upstream merges) can be driven mostly by an AI agent with a human reviewer in the loop.

If you are new here, read the Overview first, set up the MCP server, then jump to Merging from upstream for the most common workflow.

Overview

What lives in .github/

How the pieces fit together

┌────────────────────────────────────────────────────────────────┐
│  VS Code + GitHub Copilot (chat / agent mode)                  │
│                                                                │
│   ├─ loads instructions/*.md  (auto, by applyTo)               │
│   ├─ can switch into an agent from agents/*.agent.md           │
│   ├─ can be launched via a prompt from prompts/*.prompt.md     │
│   ├─ can invoke skills from skills/*/SKILL.md                  │
│   └─ can call MCP tools ──────────────────┐                    │
└───────────────────────────────────────────┼────────────────────┘
                                            ▼
                            ┌─────────────────────────────┐
                            │  MCP server (openssh-server)│
                            │  defined in .vscode/mcp.json│
                            │  runs PowerShell from       │
                            │  .github/tools/*.ps1        │
                            └─────────────────────────────┘

Repository setup

Follow instructions/setup.instructions.md end-to-end. It covers cloning the fork, configuring the upstream and upstream-pwsh remotes, prerequisites (Visual Studio + Windows SDK), and cloning + bootstrapping vcpkg via Install-VcpkgDependencies.ps1. For the vendored dependency model itself, see instructions/vcpkg.instructions.md. Once setup is complete, do a baseline build per instructions/build.instructions.md.

MCP server setup (.vscode/mcp.json)

The PowerShell scripts in tools/ are exposed to Copilot via a small MCP (Model Context Protocol) server so the agent can call them as first-class tools (mcp_openssh-server_Start_OpenSSHBuild, mcp_openssh-server_Invoke_Git, etc.).

1. Install the MCP host module

The server is hosted by the MCPServerPS PowerShell module, which wraps each .ps1 in -ScriptRoot as an MCP tool. To install the module, run the following command:

Install-PSResource -Name MCPServerPS -Repository PSGallery

2. Configure VS Code

This repo already ships a working .vscode/mcp.json at the repo root. It uses a repo-relative ScriptRoot, so it works out of the box when VS Code is opened at the repository root — no editing required in that case:

{
    "servers": {
        "openssh-server": {
            "type": "stdio",
            "command": "pwsh",
            "args": [
                "-noprofile",
                "-c",
                "MCPServerPS\\Start-MyMCP -Name openssh-server -ScriptRoot ./.github/tools"
            ],
            "env": {
                "GITHUB_TOKEN": "${input:github_token}"
            }
        }
    },
    "inputs": [
        {
            "id": "github_token",
            "type": "promptString",
            "description": "GitHub Personal Access Token (used for commit-group CI status queries)",
            "password": true
        }
    ]
}

Path note: The relative ./.github/tools path resolves against the workspace root, so it works as-is when you open this repository as the VS Code workspace. Only switch to an absolute path (e.g. C:\repos\openssh-portable\.github\tools) if you run the server from a different working directory or a multi-root workspace where the relative path does not resolve.

3. Start the server in VS Code

• Open the MCP: List Servers command (Command Palette).
• Start openssh-server. You should see the tools become available to Copilot Chat (their names are prefixed with mcp_openssh-server_, e.g. mcp_openssh-server_Invoke_Git).
• In agent mode, the agent will discover and call them automatically.

4. Available MCP tools

All tools are PowerShell scripts under tools/. They are documented in detail inside their respective instruction files; here's a quick map:

Instructions, agents, prompts, and skills

Instructions (instructions/)

Markdown files with YAML frontmatter that the agent loads automatically based on applyTo globs. They encode the conventions and workflows of this repo so you don't need to repeat them in every prompt.

General:

• repository-overview.instructions.md — repo layout + Windows compatibility layer
• setup.instructions.md — clone, remotes, prerequisites, vcpkg
• build.instructions.md — building on Windows + warning policy
• testing.instructions.md — functional + full CI testing
• vcpkg.instructions.md — vendored dependency reference
• agent-communication.instructions.md — how the agent should talk to you

Merge-specific (under instructions/merge/):

• merge-process-overview.instructions.md — the two-phase workflow end-to-end
• merge-details.instructions.md — conflict resolution patterns + decision trees
• research.instructions.md — what to read before merging (release notes, prior PRs)
• agent-communication-merge.instructions.md — communication templates for batches

Agents (agents/)

Custom Copilot agent modes with curated tool sets and a system prompt tuned to a workflow.

• merge-upstream.agent.md — drives the upstream merge workflow end-to-end (analysis → batch merges → build → test → PR prep). Switch to it from the Copilot Chat agent picker.
• conflict-review.agent.md — review-only subagent the merge agent delegates to after resolving a batch's conflicts. Audits resolutions for leftover markers, prefer- upstream bias, balanced Windows guards, silently auto-merged changes needing Windows follow-up, and version sync; returns APPROVE or CHANGES-REQUIRED.

Prompts (prompts/)

Reusable prompt templates with documented inputs.

• merge.prompt.md — kicks off a merge with the right context. Provide a start ref (and optionally end ref, remotes, validation scenario), and the agent handles the rest.

Skills (skills/)

Self-contained workflow skills the agent reads on demand.

• update-vcpkg-port — bump a vendored vcpkg dependency (LibreSSL, libfido2, libcbor, zlib) with all the side effects (overlay portfile SHA512, LibreSSL resource patch) handled correctly.
• resolve-merge-conflict — conflict-resolution procedure for upstream merges (prefer-upstream + adapt for Windows, strategy preference order, silent auto-merge hunting, regress-test and version-resource sync) plus how to summarize the resolutions for the pull request.
• merge-retrospective — run after a merge PR lands to capture new conflict-resolution patterns and feed lessons back into the instructions, skills, agents, and tools.

Merging from upstream

Merging from openssh/openssh-portable is the headline workflow this folder is built around. It uses a two-phase approach (all incremental merges, conflict resolution, build fixes, and validation happen on a scratch branch; then a real merge branch is created from the same starting commit, a single git merge of the upstream target is performed, and any conflicts are resolved by copying the resolved files from the scratch branch). This preserves upstream commit history exactly. The full workflow lives in instructions/merge/merge-process-overview.instructions.md; conflict-resolution patterns are in merge-details.instructions.md; background reading is in research.instructions.md.

Driving the merge with AI (recommended)

1. Make sure the MCP server is running.
2. In Copilot Chat, switch to the merge-upstream agent (agents/merge-upstream.agent.md).
3. Invoke the merge prompt (prompts/merge.prompt.md) with at minimum a start ref — see that file for the full input list and examples.
4. Follow the phase checklist, use the tools under tools/, and surface documented blockers for human guidance when needed.
5. Approve each batch summary the agent presents; at the end, push the real branch and open the PR.

Driving the merge manually

Follow merge-process-overview.instructions.md phase by phase. Refer to the repository setup, build, and testing instructions as needed.

Validation

Default validation is end-to-end via mcp_openssh-server_Test_OpenSSHFunctionality. The full CI suite is documented in instructions/testing.instructions.md.

Other AI-assisted workflows

Bumping a vendored vcpkg dependency

Use the update-vcpkg-port skill. Ask Copilot something like "Bump LibreSSL to 4.1.1 using the update-vcpkg-port skill." The skill orchestrates Update-VcpkgPort.ps1 (manifest, overlay portfile SHA512, LibreSSL resource patch), validates via Install-VcpkgDependencies.ps1, then builds to confirm.

Building / testing / debugging

Even outside a merge, the MCP tools are useful day-to-day. See build.instructions.md and testing.instructions.md for the full parameter reference of Start-OpenSSHBuild, Test-OpenSSHBuild, Test-OpenSSHFunctionality, and Invoke-OpenSSHTests.