From 674d092884dc2251ffb152bdee37944c69a70de6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20CORTIER?= Date: Mon, 10 Aug 2026 02:57:22 +0900 Subject: [PATCH 1/4] chore(agents): add reusable review skills Port reusable compression, documentation, prose, and attribution skills for Gateway agents. Add a contract-aware review orchestrator that routes only applicable changes through authoritative contract checks. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .agents/skills/code-compressor/SKILL.md | 19 +++++++++++ .agents/skills/docs-compressor/SKILL.md | 17 ++++++++++ .agents/skills/docs-writer/SKILL.md | 22 +++++++++++++ .../external-contract-reviewer/SKILL.md | 33 +++++++++++++++++++ .agents/skills/llm-comment-footer/SKILL.md | 22 +++++++++++++ .agents/skills/markdown-writer/SKILL.md | 18 ++++++++++ .agents/skills/prose-verifier/SKILL.md | 12 +++++++ .agents/skills/prose-writer/SKILL.md | 21 ++++++++++++ .agents/skills/skeptical-reviewer/SKILL.md | 22 +++++++++++++ .github/skills/code-review/SKILL.md | 29 ++++++++++++++++ 10 files changed, 215 insertions(+) create mode 100644 .agents/skills/code-compressor/SKILL.md create mode 100644 .agents/skills/docs-compressor/SKILL.md create mode 100644 .agents/skills/docs-writer/SKILL.md create mode 100644 .agents/skills/external-contract-reviewer/SKILL.md create mode 100644 .agents/skills/llm-comment-footer/SKILL.md create mode 100644 .agents/skills/markdown-writer/SKILL.md create mode 100644 .agents/skills/prose-verifier/SKILL.md create mode 100644 .agents/skills/prose-writer/SKILL.md create mode 100644 .agents/skills/skeptical-reviewer/SKILL.md create mode 100644 .github/skills/code-review/SKILL.md diff --git a/.agents/skills/code-compressor/SKILL.md b/.agents/skills/code-compressor/SKILL.md new file mode 100644 index 000000000..07487a3cb --- /dev/null +++ b/.agents/skills/code-compressor/SKILL.md @@ -0,0 +1,19 @@ +--- +name: code-compressor +description: Aggressively review changed code for unnecessary complexity and propose smaller, clearer, behavior-preserving alternatives. Use for code reviews, refactor assessments, or any diff where simplification, deletion, reuse, flatter control flow, or fewer abstractions may improve the implementation. +--- + +# Code compressor + +Treat every added branch, state, abstraction, helper, conversion, and dependency as complexity that must earn its place. +Look for duplicated logic, speculative generality, needless indirection, over-modeled state, tangled control flow, verbose data transformations, and code that existing APIs can replace. + +Be aggressive in searching, but evidence-driven in reporting. +Recommend a simplification only when you can describe a concrete, smaller alternative and explain why it preserves required behavior. +Account for error handling, ownership, lifetimes, performance, public API stability, and repository conventions. +Do not trade explicit correctness or necessary protocol detail for fewer lines. + +Report each opportunity with its location, the complexity it removes, the proposed shape, and any meaningful tradeoff. +Separate optional compression opportunities from correctness defects. +Omit formatting, naming preferences, and vague rewrite requests. +If the code is already close to the simplest correct form, return no findings. diff --git a/.agents/skills/docs-compressor/SKILL.md b/.agents/skills/docs-compressor/SKILL.md new file mode 100644 index 000000000..209c35328 --- /dev/null +++ b/.agents/skills/docs-compressor/SKILL.md @@ -0,0 +1,17 @@ +--- +name: docs-compressor +description: Review documentation changes for concise, human-readable prose without losing technical meaning. Use whenever READMEs, guides, reference docs, rustdoc, explanatory comments, release notes, or other instructional prose is added or edited. +--- + +# Documentation compressor + +Invoke `docs-writer`, then use its rules as review criteria without following its generation workflow. +Challenge every paragraph, heading, example, and aside that does not add information or help the reader act. +Look for the same meaning expressed with less structure, repetition, or wording while preserving the writer rules. +For substantial rewrites, compare word counts before and after. +Prefer no net growth when the task adds no information. +Accept small growth only when it materially improves clarity or navigation without duplicating information, and explain why. + +Report only material readability gains. +For each finding, cite the location, explain what obstructs the reader, and provide a concise replacement or a precise deletion. +Combine repeated edits into one finding when the same rewrite addresses them. diff --git a/.agents/skills/docs-writer/SKILL.md b/.agents/skills/docs-writer/SKILL.md new file mode 100644 index 000000000..2308d418b --- /dev/null +++ b/.agents/skills/docs-writer/SKILL.md @@ -0,0 +1,22 @@ +--- +name: docs-writer +description: Write clear, concise technical documentation that helps readers complete a task or understand an interface. Use whenever creating or substantially rewriting READMEs, guides, tutorials, reference docs, rustdoc, explanatory comments, or release notes. +--- + +# Documentation writer + +For Markdown, invoke `markdown-writer`; otherwise invoke `prose-writer`. +Apply the selected writer's rules throughout. +Identify the intended reader, their goal, and the prerequisites they need. +Before restructuring existing documentation, inventory its unique facts so none are lost or restated. +Present the outcome or shortest successful path before internal mechanics and edge cases. +Use only the headings needed to answer distinct reader questions. +Explain one path completely before introducing alternatives, and link to existing material instead of repeating it. +Keep examples minimal, realistic, and responsible for unique information. +Place warnings and constraints beside the step they affect. +Preserve established terminology and verify technical claims against the implementation. + +Write the requested documentation directly. +Prefer no net word-count growth when restructuring existing documentation without adding requested information. +New structure should replace or consolidate prose; allow small justified growth when it materially improves navigation without duplication. +Before finishing, remove repetition and confirm that a reader can find the next action without reconstructing it from implementation details. diff --git a/.agents/skills/external-contract-reviewer/SKILL.md b/.agents/skills/external-contract-reviewer/SKILL.md new file mode 100644 index 000000000..73eecb1e4 --- /dev/null +++ b/.agents/skills/external-contract-reviewer/SKILL.md @@ -0,0 +1,33 @@ +--- +name: external-contract-reviewer +description: Review Devolutions Gateway changes against authoritative external contracts. Use when a diff may affect HTTP or OpenAPI behavior, WebSocket behavior, relay or tunneling semantics, configuration schemas, or agent and platform protocols. +--- + +# External contract reviewer + +First decide whether the change materially affects an externally visible contract. +Do not force this review onto internal refactors, tests, tooling, or implementation details that preserve observable behavior. + +Review applicable surfaces: + +- HTTP routes, methods, authentication, headers, status codes, request and response bodies, and OpenAPI definitions. +- WebSocket handshakes, subprotocols, messages, framing, session behavior, closure, and errors. +- Relay and tunneling establishment, routing, framing, multiplexing, shutdown, and failure behavior. +- Configuration names, types, formats, defaults, validation, compatibility, and `config_schema.json`. +- Gateway-to-agent communication and operating-system or vendor platform protocols. + +Identify the governing source before judging the implementation. +Prefer normative standards and vendor specifications for standardized behavior, and checked-in schemas or explicitly canonical repository documentation for Gateway-defined contracts. +Treat generated files and existing implementation behavior as evidence, not authority, unless the repository declares them canonical. +Use the `windows-protocols` skill when Microsoft Open Specifications govern the changed behavior. +When no authoritative source is available, state the evidence gap instead of inventing a requirement. + +Map each contract-relevant change to its governing requirement and attempt to falsify compliance. +Check versioning, capability negotiation, sequencing, endpoint roles, security requirements, compatibility guards, and error semantics when applicable. +For encoded or structured data, check field order, widths, signedness, constants, reserved values, optional fields, lengths, bounds, encode/decode symmetry, and malformed-input handling. +For schemas, compare implementation defaults and validation with the declared schema and verify that generated companions remain consistent. + +Separate normative requirements from informative guidance, product-specific behavior, and inference. +Cite the governing source precisely, including a section, URL, or repository path. +Report only contract-relevant findings with a concrete location, observable impact, and actionable correction. +Do not propose general architectural refactors unless conformance requires them. diff --git a/.agents/skills/llm-comment-footer/SKILL.md b/.agents/skills/llm-comment-footer/SKILL.md new file mode 100644 index 000000000..ff76ca1f6 --- /dev/null +++ b/.agents/skills/llm-comment-footer/SKILL.md @@ -0,0 +1,22 @@ +--- +name: llm-comment-footer +description: Add required LLM attribution to GitHub issue bodies and issue or pull request comments. Use whenever drafting, creating, or replying to this content, including agent-merge review-thread replies and helper-driven GitHub comment replies. Do not use for pull request bodies. +--- + +# LLM comment footer + +Include exactly one attribution. +Append one of these footers to the issue body or comment Markdown after a blank line unless using a helper-managed byline: + +- `> [!NOTE]` + `> LLM-assisted auto-reply (no human feedback).` +- `> [!NOTE]` + `> Human-tuned, LLM-assisted reply.` + +Use the auto-reply footer only when the comment is posted without human review, edits, or feedback. +Use the human-tuned footer when a human reviews, edits, or provides feedback that shapes the final comment. + +For app-owned `agent-merge` and other helper-driven replies, use an allowed footer in the reply Markdown or the helper's configured app-managed byline. +Ensure the chosen attribution is actually inserted; never assume the helper will add it or include both. + +Do not add the footer to pull request bodies because it conflicts with pull request guidelines. diff --git a/.agents/skills/markdown-writer/SKILL.md b/.agents/skills/markdown-writer/SKILL.md new file mode 100644 index 000000000..5de38fd08 --- /dev/null +++ b/.agents/skills/markdown-writer/SKILL.md @@ -0,0 +1,18 @@ +--- +name: markdown-writer +description: Write clean, readable Markdown with concise prose and maintainable source formatting. Use whenever creating or substantially rewriting Markdown files, including READMEs, guides, release notes, issue templates, and Markdown-based documentation. +--- + +# Markdown writer + +Invoke `prose-writer` before drafting and apply its rules throughout. +Use the shallowest heading hierarchy that makes the document easy to scan. +Prefer short paragraphs and lists only when items are easier to compare or follow separately. +Use fenced code blocks with a language identifier and keep explanatory prose outside the fence. + +Prefer reference-style links so URLs do not interrupt the source text. +Place link definitions near the end of the document and reuse them for repeated destinations. +Keep inline links when the literal URL is meaningful, the surrounding format requires one, or the link appears in a badge, raw HTML, generated content, or a compact table. + +Preserve valid embedded HTML and repository-specific Markdown conventions. +Before finishing, check heading order, code fences, link definitions, and one sentence per source line. diff --git a/.agents/skills/prose-verifier/SKILL.md b/.agents/skills/prose-verifier/SKILL.md new file mode 100644 index 000000000..67e381110 --- /dev/null +++ b/.agents/skills/prose-verifier/SKILL.md @@ -0,0 +1,12 @@ +--- +name: prose-verifier +description: Verify edited prose is concise, human-first, and written one sentence per source line. Use whenever Markdown, AsciiDoc, plain-text documentation, release notes, or other hand-maintained prose is changed, especially when reviewing documentation style or line-oriented diffs. +--- + +# Prose verifier + +Invoke `prose-writer` and use its rules as review criteria without following its generation workflow. +Review only the touched prose and pay particular attention to concise, human-first phrasing and one sentence per source line. +Report exact locations and replacement text for violations; group mechanical instances that share one fix. +Prefer localized corrections over rewriting compliant surrounding prose. +Return no findings when the touched prose already complies. diff --git a/.agents/skills/prose-writer/SKILL.md b/.agents/skills/prose-writer/SKILL.md new file mode 100644 index 000000000..5f7360dd9 --- /dev/null +++ b/.agents/skills/prose-writer/SKILL.md @@ -0,0 +1,21 @@ +--- +name: prose-writer +description: Write concise, human-first prose with one sentence per source line. Use whenever generating or substantially rewriting Markdown, AsciiDoc, plain-text documentation, release notes, user-facing explanations, or other hand-maintained prose. +--- + +# Prose writer + +Lead with what the reader needs to know or do. +Use direct sentences, concrete verbs, familiar words, and the shortest phrasing that preserves meaning. +Remove throat-clearing, repetition, inflated wording, and details already clear from context. +Keep each paragraph focused on one idea and order ideas by reader need rather than implementation history. +Preserve necessary nuance, technical terms, warnings, and the document's established voice. + +In source formats where newlines render as spaces, start each sentence on its own line and do not hard-wrap a sentence. +Do not apply that convention to code blocks, tables, headings, link definitions, generated files, or formats where line breaks affect rendering. + +Write the requested prose directly instead of discussing these rules unless the user asks. +Prefer no net word-count growth when rewriting existing prose without adding requested information. +Accept small growth only when it materially improves clarity without duplicating information. +Treat source line breaks as formatting, not justification for growth. +Before finishing, reread from the reader's perspective and remove anything that does not help them understand or act. diff --git a/.agents/skills/skeptical-reviewer/SKILL.md b/.agents/skills/skeptical-reviewer/SKILL.md new file mode 100644 index 000000000..9b6ebb464 --- /dev/null +++ b/.agents/skills/skeptical-reviewer/SKILL.md @@ -0,0 +1,22 @@ +--- +name: skeptical-reviewer +description: Perform an evidence-driven, change-averse Devolutions Gateway code review. Use when assessing the correctness, necessity, scope, or design of a proposed change. +--- + +# Skeptical reviewer + +Use the existing code as the baseline. +Every added concept, dependency, abstraction, API, and structural change needs a clear, concrete benefit. +Attempt to falsify correctness, necessity, and design through counterexamples, failure modes, hidden assumptions, misuse cases, and simpler alternatives. +Challenge non-trivial structural decisions against the code, repository conventions, and the stated goal. +Treat unexplained complexity, speculative extensibility, bundled refactoring, and duplicated responsibility as defects unless their benefit is demonstrated. +Prefer deletion, reuse, localization, and narrower changes. +Tests and documentation substantiate claims; they do not justify unclear design. + +When an immediate fix bundles a cross-cutting public abstraction that needs broader compatibility, ownership, or lifecycle decisions, recommend a separate PR if the fix can be isolated. +Remain evidence-driven: do not manufacture objections, demand personal preferences, or reject unfamiliar designs. +A change passes only after reasonable attempts to disprove it fail and its complexity is justified. + +When external-contract analysis evidence is supplied, independently verify it against the change. +Keep, refine, or reject each concern with a concrete rationale. +Report material contract concerns missed by the analysis without implying that you consulted sources you did not inspect. diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md new file mode 100644 index 000000000..16a2a13f3 --- /dev/null +++ b/.github/skills/code-review/SKILL.md @@ -0,0 +1,29 @@ +--- +name: code-review +description: Review Devolutions Gateway pull requests and diffs using focused contract, compression, documentation, prose, and skeptical passes. Use whenever Copilot code review is requested or a proposed change needs review. +--- + +# Code review + +Inspect the diff, its stated goal, and repository guidance before selecting conditional reviewers: + +- Run `external-contract-reviewer` only when the change may affect HTTP or OpenAPI behavior, WebSocket behavior, relay or tunneling semantics, configuration schemas, or agent and platform protocols. +- Run `code-compressor` for every diff, limiting it to changed code. +- Run `docs-compressor` when documentation, rustdoc, explanatory comments, or instructional prose changes. +- Run `prose-verifier` when hand-maintained prose changes in a format where source line breaks are stylistic. +- Run `skeptical-reviewer` last for every diff. + +Prefer one `rubber-duck` sub-agent per applicable skill. +Run the contract, compression, documentation, and prose reviews in parallel. +Give every agent the change goal, review scope, base and head references, relevant repository guidance, and an instruction to invoke its named skill, inspect the diff itself, make no edits, and return only evidence-backed findings. +If sub-agents or skill invocation are unavailable, apply the same skills directly and keep the ordering. + +Before the skeptical pass, normalize the initial results. +Drop claims that lack a concrete location or mechanism, merge findings with the same root cause, and retain disagreements instead of resolving them by vote. +Give the skeptical reviewer the diff plus the retained findings and ask it to independently review the change, verify or reject each supplied concern, and identify material issues the focused passes missed. + +Evaluate the final evidence yourself. +Report correctness and external-contract findings first, ordered by severity, then optional compression suggestions. +Each retained item needs a location, concrete impact, and actionable correction or simplification. +Merge duplicates across reviewers and do not inflate a maintainability preference into a defect. +Briefly name skipped conditional reviewers and why; if nothing material remains, say that no findings were identified. From 32085695a80e314303be0d4573d0c50ca389a63b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20CORTIER?= Date: Mon, 10 Aug 2026 03:14:30 +0900 Subject: [PATCH 2/4] refactor(agents): generalize skeptical reviewer Remove repository-specific wording and make review handoff language generic across review pipelines. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .agents/skills/skeptical-reviewer/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/skills/skeptical-reviewer/SKILL.md b/.agents/skills/skeptical-reviewer/SKILL.md index 9b6ebb464..33a930d66 100644 --- a/.agents/skills/skeptical-reviewer/SKILL.md +++ b/.agents/skills/skeptical-reviewer/SKILL.md @@ -1,6 +1,6 @@ --- name: skeptical-reviewer -description: Perform an evidence-driven, change-averse Devolutions Gateway code review. Use when assessing the correctness, necessity, scope, or design of a proposed change. +description: Perform an evidence-driven, change-averse code review. Use when assessing the correctness, necessity, scope, or design of a proposed change. --- # Skeptical reviewer @@ -17,6 +17,6 @@ When an immediate fix bundles a cross-cutting public abstraction that needs broa Remain evidence-driven: do not manufacture objections, demand personal preferences, or reject unfamiliar designs. A change passes only after reasonable attempts to disprove it fail and its complexity is justified. -When external-contract analysis evidence is supplied, independently verify it against the change. -Keep, refine, or reject each concern with a concrete rationale. -Report material contract concerns missed by the analysis without implying that you consulted sources you did not inspect. +When other review passes supply findings, independently verify them against the change. +Keep, refine, or reject each finding with a concrete rationale. +Report material concerns missed by those passes without implying that you consulted sources you did not inspect. From 8820daa77a61fe7e5c5ff44cb0a2640147f0e7aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20CORTIER?= Date: Mon, 10 Aug 2026 03:16:37 +0900 Subject: [PATCH 3/4] refactor(agents): generalize LLM attribution Use content instead of reply so required footers accurately cover both issue bodies and comments. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .agents/skills/llm-comment-footer/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/skills/llm-comment-footer/SKILL.md b/.agents/skills/llm-comment-footer/SKILL.md index ff76ca1f6..faf166475 100644 --- a/.agents/skills/llm-comment-footer/SKILL.md +++ b/.agents/skills/llm-comment-footer/SKILL.md @@ -9,12 +9,12 @@ Include exactly one attribution. Append one of these footers to the issue body or comment Markdown after a blank line unless using a helper-managed byline: - `> [!NOTE]` - `> LLM-assisted auto-reply (no human feedback).` + `> LLM-assisted content (no human feedback).` - `> [!NOTE]` - `> Human-tuned, LLM-assisted reply.` + `> Human-tuned, LLM-assisted content.` -Use the auto-reply footer only when the comment is posted without human review, edits, or feedback. -Use the human-tuned footer when a human reviews, edits, or provides feedback that shapes the final comment. +Use the no-human-feedback footer only when the content is posted without human review, edits, or feedback. +Use the human-tuned footer when a human reviews, edits, or provides feedback that shapes the final content. For app-owned `agent-merge` and other helper-driven replies, use an allowed footer in the reply Markdown or the helper's configured app-managed byline. Ensure the chosen attribution is actually inserted; never assume the helper will add it or include both. From 9b19b183888eece3894b570c3304dedf9f3b6067 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20CORTIER?= Date: Mon, 10 Aug 2026 03:18:11 +0900 Subject: [PATCH 4/4] fix(agents): make protocol skill optional Fall back to the governing specification when windows-protocols is unavailable in a repository-only agent environment. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .agents/skills/external-contract-reviewer/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/external-contract-reviewer/SKILL.md b/.agents/skills/external-contract-reviewer/SKILL.md index 73eecb1e4..5e3274674 100644 --- a/.agents/skills/external-contract-reviewer/SKILL.md +++ b/.agents/skills/external-contract-reviewer/SKILL.md @@ -19,7 +19,7 @@ Review applicable surfaces: Identify the governing source before judging the implementation. Prefer normative standards and vendor specifications for standardized behavior, and checked-in schemas or explicitly canonical repository documentation for Gateway-defined contracts. Treat generated files and existing implementation behavior as evidence, not authority, unless the repository declares them canonical. -Use the `windows-protocols` skill when Microsoft Open Specifications govern the changed behavior. +When Microsoft Open Specifications govern the changed behavior, use the `windows-protocols` skill if available; otherwise consult the specification directly. When no authoritative source is available, state the evidence gap instead of inventing a requirement. Map each contract-relevant change to its governing requirement and attempt to falsify compliance.