Make agent guidance audience-aware

[Nikola Metulev (nmetulev)]

Summary

• Define separate audience contracts for user documentation and review/author communication, with example-first explanations that pass a junior-developer reader test.
• Set backward compatibility at the latest supported published release and require a published version, public contract or persisted data, and real external consumer before adding a shim.
• Replace repetitive PR/spec review reports with compact, human-first decision templates while preserving independent research, validation, model diversity, and the existing gut check internally.
• Correct architecture guidance so file size is a signal, DI does not imply an interface, and cohesive implementations are preferred over one-caller wrappers.

Validation

• scripts\validate-plugin-package.ps1
• git diff --check
• Focused Markdown structure and changed-file scope checks

No dedicated validator exists for the .github/skills/pr-review or .github/skills/spec-review guidance. This is a documentation-only change, so no product build was run.

[Copilot]

Pull request overview

Makes agent guidance audience-aware and simplifies review output while preserving internal rigor.

Changes:

• Adds audience and compatibility contracts.
• Replaces verbose review reports with human-first templates.
• Refines architecture and documentation guidance.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
AGENTS.md	Adds audience, compatibility, documentation, and architecture guidance.
.github/skills/spec-review/SKILL.md	Simplifies spec-review reporting.
spec-review/dimensions/_shared-contract.md	Defines reader-focused finding contracts.
spec-review/dimensions/approach-and-alternatives.md	Aligns architecture review guidance.
spec-review/dimensions/dx-and-user-impact.md	Applies the compatibility boundary.
spec-review/dimensions/feasibility-vs-reality.md	Refines compatibility verification.
spec-review/dimensions/multi-model.md	Keeps model bookkeeping internal.
spec-review/dimensions/necessity-and-scope.md	Clarifies scope ownership.
spec-review/dimensions/risks-unknowns-edge-cases.md	Updates compatibility and proof terminology.
.github/skills/pr-review/SKILL.md	Introduces compact, human-first PR reports.
pr-review/dimensions/_shared-contract.md	Defines the new finding schema.
pr-review/dimensions/alternative-solution.md	Replaces line limits with cohesion guidance.
pr-review/dimensions/cli-ux.md	Limits compatibility aliases to published contracts.
pr-review/dimensions/necessity-and-simplicity.md	Clarifies when implementation scope is reopened.
pr-review/dimensions/ship-surfaces.md	Targets only affected shipping surfaces.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

⏳ Build in progress — metrics below are from a previous commit and will update when the current build finishes.

Build Metrics Report

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	38.63 MB	38.63 MB	✅ 0.0 KB (0.00%)
CLI (x64)	38.75 MB	38.75 MB	✅ 0.0 KB (0.00%)
MSIX (ARM64)	16.02 MB	16.02 MB	📈 +0.0 KB (+0.00%)
MSIX (x64)	17.02 MB	17.02 MB	📈 +0.1 KB (+0.00%)
NPM Package	33.43 MB	33.43 MB	📈 +0.2 KB (+0.00%)
NuGet Package	33.47 MB	33.47 MB	📈 +0.5 KB (+0.00%)

Test Results

✅ 4612 passed, 5 skipped out of 4617 tests in 616.0s (+66.6s vs. baseline)

Test Coverage

✅ 89.1% line coverage, 82.5% branch coverage · ✅ no change vs. baseline

CLI Startup Time

45ms median (x64, winapp --version) · ✅ no change vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 786

Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 786

Run winapp-pr with no arguments to pick from a list of open PRs.

---

Updated 2026-08-25 23:08:27 UTC · commit 909288b · workflow run