Reconcile which agent pointer files a repository must carry

[MariusStorhaug]

Context and request

Two surfaces in this site disagree about which agent pointer files a repository carries, and a reader of one reaches a different conclusion than a reader of the other.

Ways of Working → Agentic Development describes the per-repository pointer files as AGENTS.md, the CLAUDE.md that imports it, and unnamed "path-scoped local-rule adapters". It never mentions .github/copilot-instructions.md.

The agentic development capability spec names .github/copilot-instructions.md explicitly as a client adapter that MAY add runtime-specific loading rules, and the design puts it in the example repository layout, in a worked prose example, and in the runtime adapter table for both VS Code Copilot and the Copilot coding agent — in each case without marking it optional.

Neither page says the file is required and neither says it is discouraged. The spec's MAY is correct; the problem is the silent omission on the narrative standard and the unmarked-as-optional presentation in the design.

The disagreement has already cost downstream work. A PSModule/Template-PSModule change added .github/copilot-instructions.md to the module template, was corrected by the maintainer on the grounds that AGENTS.md is the entry point and a per-runtime copy of the same pointer is drift-prone duplication, and had to be reverted. PSModule/Template-PSModule#33 then removed the file from the template. Adoption is thin: the file exists in 2 of 96 PSModule repositories. PSModule/docs#102 and PSModule/docs#101 had to reconstruct which MSX source says what before they could correct the PSModule page.

Separately, Repository Standard lists the baseline files every repository must carry and omits AGENTS.md altogether, so the file the whole model depends on is not in the required-files contract.

Desired outcome

One answer, stated once and consistent across every page in this repository that mentions per-repository agent files, so a downstream initiative can copy the rule instead of reconstructing it.

Acceptance criteria

• The Ways of Working standard states which agent files a repository is required to carry, names .github/copilot-instructions.md as an optional client adapter rather than omitting it, and gives the condition under which an adapter is warranted.
• The capability spec keeps its RFC-2119 MAY for client adapters and states that AGENTS.md is the one required pointer, so the spec's breadth relative to the standard is explicit rather than implicit.
• The design marks optional adapter files as optional wherever it presents the repository layout and the runtime adapter table.
• Repository Standard lists AGENTS.md among the required files, and records client adapters as optional.
• Every other page in src/docs that lists per-repository agent files uses the same phrasing. copilot-instructions, AGENTS.md, and CLAUDE.md are searched across the whole tree.
• Link validation and markdownlint pass.

Technical decisions

The rule. AGENTS.md is the required repository agent entry point. CLAUDE.md imports it. Other client adapters — .github/copilot-instructions.md and .github/instructions/*.instructions.md — are optional: permitted, not required, and not the default, because a duplicated pointer drifts from the file it points at.

The condition that makes an adapter warranted is verifiable rather than a matter of taste: an adapter is justified when a runtime surface the repository actually relies on does not read AGENTS.md. GitHub's own support matrix shows AGENTS.md is read by Copilot Chat in VS Code, the Copilot cloud agent, and Copilot code review on GitHub.com, but not by Copilot Chat on github.com, Visual Studio, JetBrains Chat, Eclipse, or Copilot code review in VS Code — all of which read .github/copilot-instructions.md. That is why the file is optional rather than forbidden, and why this repository legitimately carries one.

Scope boundary. This is a reconciliation. The agentic development model, the freshness gate, the context resolution contract, and the RFC-2119 semantics of the spec are not being rewritten.

Paths in scope (the capability moved out of Frameworks/ in #109):

• src/docs/Ways-of-Working/Agentic-Development.md
• src/docs/Capabilities/agentic-development/spec.md
• src/docs/Capabilities/agentic-development/design.md
• src/docs/Ways-of-Working/Repository-Standard.md
• src/docs/Ways-of-Working/Principles/AI-First-Development.md
• src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md

Implementation plan

• Search src/docs for copilot-instructions, AGENTS.md, and CLAUDE.md and confirm the full set of affected pages.
• State the rule in Ways-of-Working/Agentic-Development.md: required entry point, adapters optional, the runtime-coverage condition, and a link to the capability spec for the enumerated adapter list.
• Update Capabilities/agentic-development/spec.md so AGENTS.md is the MUST-carry pointer and the client-adapter requirement keeps MAY while stating that an adapter is not required by default.
• Update Capabilities/agentic-development/design.md: mark the optional files in the repository layout, adjust the adapter prose, and correct the runtime adapter table so it reflects which surfaces read AGENTS.md natively.
• Correct the stale Frameworks/Agentic-Development/ paths in the design's index example, left behind by 📖 [Docs]: Move Agentic-Development from Frameworks into Capabilities #109.
• Add AGENTS.md to the required-files table in Ways-of-Working/Repository-Standard.md and record client adapters as optional.
• Align the pointer-file phrasing in Principles/AI-First-Development.md and Workflow-Stages/Maintain-Guidance.md.
• Run pwsh .github/scripts/Test-DocumentationLink.ps1 and markdownlint over the changed files.
• Open the pull request as a draft and cross-link 📖 [Docs]: Module repository defaults match how PSModule repositories actually work PSModule/docs#101, Align Repository Defaults with the agent onboarding model, workflow filename, and supported Dependabot ecosystems PSModule/docs#102, and 🩹 [Patch]: New module repositories ship the required community and governance files PSModule/Template-PSModule#37 as the downstream churn this prevents.

References

• Align Repository Defaults with the agent onboarding model, workflow filename, and supported Dependabot ecosystems PSModule/docs#102 — the downstream issue that had to reconstruct which MSX source says what
• 📖 [Docs]: Module repository defaults match how PSModule repositories actually work PSModule/docs#101 — the downstream correction that documents the file as optional
• refactor: slim template scaffolding to minimum baseline PSModule/Template-PSModule#33 — removed the file from the module template
• 🩹 [Patch]: New module repositories ship the required community and governance files PSModule/Template-PSModule#37 — the template baseline work that surfaced the disagreement
• https://docs.github.com/en/copilot/reference/custom-instructions-support