UKHO.GitHubCopilot.ToolKit copilot-instructions.md

Copilot Instructions

Overview

These instructions standardize how Copilot-related assets are authored and maintained in this repository. They are intended for any change that touches instructions, prompts, templates, supporting documentation, or related repository guidance.

Scope

Applies to: **/*

General Guidelines

• Encourage established design and documentation principles such as clarity, separation of concerns, explicit dependencies, and reusable guidance.
• Prefer technology guidance that is applicable across Microsoft projects unless a file is explicitly scoped to a narrower stack or workflow.
• Keep repository assets adaptable so teams can reuse them in different Microsoft project contexts without inheriting assumptions from one specific solution.
• Treat ./AGENTS.md as the repository-level operating policy for agent execution style and ./lessons.md as the durable record of stable repository learnings.

Instructions

MUST

• Keep instructions, prompts, templates, and examples neutral enough to apply across Microsoft projects unless a file explicitly targets a narrower technology, framework, or workflow.
• Ground Microsoft-technology guidance in authoritative Microsoft documentation when practical, and periodically re-validate repository instruction files against those sources.
• Reuse and extend existing instructions, prompts, templates, and agents when they already cover the needed pattern closely enough, instead of creating near-duplicate repository assets.
• Use placeholders, examples, and workflow descriptions that describe patterns rather than repository-specific implementations.
• Keep documentation about repository workflows at the top level under docs/ when the guidance is intended for reuse across multiple work packages or teams.
• Review ./AGENTS.md when creating or updating reusable agents, prompts, instructions, templates, or workflow documentation so the repository operating style stays consistent.
• Update ./AGENTS.md when a stable repository-wide execution pattern or operating constraint emerges that should guide future agent behavior.
• Update ./lessons.md when implementation, validation, or maintenance work reveals a stable lesson that future contributors should not need to rediscover.
• For new or existing projects that begin using this repository workflow, create the wiki baseline first, then review .github/copilot-instructions.md and .github/instructions/*.instructions.md, identify uncovered areas, and add any missing scoped instruction files before creating work-package documentation.
• Treat docs/wiki/ as the current project source of truth for Copilot-assisted workflow decisions once the wiki baseline exists.
• In prompts, agents, templates, and workflow documentation that guide planning or project updates, require contributors to review the relevant wiki pages before drafting plans, requirements, specifications, implementation changes, or workflow updates.
• In prompts, agents, templates, and workflow documentation that guide planning or project updates, require contributors to update the affected wiki pages after changes are made so the wiki remains aligned with the current project state before the task is considered complete.
• Do not draft docs/00x-work/ work packages unless explicitly requested.
• When generating review reports in this repository, create a new report file instead of updating the existing report so prior report history remains visible.
• Use lowercase model identifiers such as gpt-5.4 in agent and prompt files to match repository conventions.