✨ - Make strict Copilot SDD adherence explicit in installed repository agent guidance #787

Is there an existing issue or feature request for this?

• I have searched the existing issues and feature requests. Native catalog support request786 is being withdrawn in favor of strict consumer adoption; this request concerns installer-generated agent guidance, not another catalog dialect or publication adapter.

What area does this improvement affect?

Documentation

What actions does this improvement affect?

Issue, Pull Request, Commit

Description of the idea or improvement

When Copilot is installed or its managed agent guidance is updated in a destination repository, include an explicit, prominent instruction that contributors and coding agents must follow Copilot's supported SDD system from the outset. Use the existing installed agent file/pointer, generated collaboration guide and repository skill as appropriate; keep them consistent rather than creating a parallel SDD mechanism.

The guidance should clearly say, in English:

Specifications and SDDs in this repository must strictly follow the SDD standard, template, supported catalog format and validation/publication workflow provided by Copilot. Read those sources before creating or changing an SDD. Do not invent alternative catalog schemas, readiness/status systems, validators or publication mechanisms. Improvements or extensions may be proposed in a new issue in vypdev/copilot; until adopted through Copilot's supported process, continue using the existing Copilot SDD system strictly. Do not bypass checks or fabricate implementation/test evidence to obtain compatibility.

Adapt the precise wording to the installed product vocabulary and supported paths, preserving the above intent. Link directly to the installed/canonical SDD standard/template/catalog guidance and the correct upstream issue route. A repository-specific product requirement may complement the content of an SDD, but an agent must not unilaterally replace the controlling Copilot format/workflow with a different mechanism.

Current limitations or challenges

The currently installed guidance explains issue forms, managed branch ownership and collaboration, but does not make this SDD-source-of-truth requirement explicit enough. In Symphonia, agents created a different catalog/status/validator system which later blocked pre-branch publication with configuration.unsupported / unsupported-profile. The owner has now directed strict adoption of Copilot, closing the unnecessary native-profile support request instead of preserving that divergence.

Observed installation/runtime:3.10.6, source f5e5a4c. Consumer issue32 and its safe diagnostic: vypdev/symphonia#32 (comment) . This request concerns future installation/update guidance; it does not authorize the reporter to modify Copilot code or deploy a release.

Expected impact

A newly installed repository gives both humans and agents one clear SDD source of truth before they author a competing standard. Proposed improvements are routed upstream while installed repositories remain compatible.

Suggested acceptance:

1. Fresh installation with the agent pointer enabled emits the strict SDD guidance and working canonical/installed links.
2. Installation/update routes that place instructions in the generated guide/skill expose the same requirement without relying on a pointer that was not selected.
3. Regeneration is idempotent and keeps the existing ownership/digest/backup checks; it does not duplicate the paragraph.
4. Existing user-authored AGENTS.md content outside the managed block is preserved; edited/unowned guidance follows the current reviewed conflict workflow.
5. Guidance covers supported SDD standard/template/catalog/validation/publication and forbids unilateral alternatives, bypasses or fabricated evidence.
6. The suggested upstream improvement route points to a new appropriate Copilot issue and does not instruct the agent to start implementation/deployment automatically.
7. Doctor/setup guidance, documentation and generation fixtures agree; positive/negative tests cover pointer selected/unselected, upgrade, preserved edits and stale/conflicting managed content.
8. Existing repository branch/approval/deployment protections and user-authored product requirements remain intact.

Alternatives considered

Relying on generic “read the repository guide” wording did not prevent a competing catalog mechanism. Supporting every ad-hoc consumer dialect is not the owner's chosen remedy. A concise explicit instruction in the existing installation-owned guidance is preferable to a new configuration system or a duplicate standards document.

Version of copilot

3.10.6; source/runtime f5e5a4c, checked2026-10-29.

Additional context or comments

Explicit owner request: destination agent instructions must state that SDDs respect Copilot strictly from the beginning; improvements/complements can be requested in a new issue, while agents continue to respect the original system and do not invent new mechanisms. Please handle through the Copilot team's normal triage. This report does not start an implementation branch, in-progress admission, setup mutation or deployment.