UKHO.GitHubCopilot.ToolKit agentic-assets.instructions.md

Lean authoring rules for Copilot assets

Overview

These instructions define how to author and maintain the repository's reusable Copilot governance files, agents, prompts, and templates. They keep assets focused, economical, and evidence-based without weakening quality, wiki alignment, or reviewer clarity.

Scope

Applies to: AGENTS.md, lessons.md, .github/copilot-instructions.md, .github/agents/**/*.agent.md, .github/prompts/**/*.prompt.md, .github/templates/**/*.template.md

• Applies when creating or updating root governance files, repo-wide Copilot guidance, custom agents, prompt files, and reusable templates.
• Complements ./AGENTS.md, ./lessons.md, and the existing repo-wide and scoped instruction files.
• Does not require human-facing explanatory documentation to become unnaturally terse; apply the strictest output-minimization rules to executable asset workflows.

Instructions

MUST

• Give each asset one clear primary outcome and keep the file name, title, description, and workflow aligned to that outcome.
• Require plan-first behavior for tasks that are more than trivial or need more than two steps.
• Prefer the smallest set of repository reads, searches, and tool calls needed to complete the task safely.
• Prefer semantic or code-graph search before iterative plain-text grep when those capabilities are available and appropriate.
• Cap investigation output deliberately by using targeted file reads, narrow search scopes, line ranges, and structured results.
• Prefer reusable scripts or automation for repeatable inventory, validation, transformation, or consistency checks.
• Use precise repository evidence, preferably file:line references, when citing implementation details, review findings, or non-obvious repository facts.
• State model choice intentionally and prefer cheaper models for routine workflows only when that choice has been validated; otherwise keep the current validated model.
• Direct contributors to review ./AGENTS.md and ./lessons.md when authoring or changing reusable repository assets.
• Update ./AGENTS.md when a stable repository-wide operating rule emerges.
• Update ./lessons.md when implementation, validation, or maintenance reveals a stable lesson worth preserving.
• Stop after three failed attempts at the same approach and surface the blocker, evidence, and recommended next move.
• Prefer targeted diff-style edits over full-file rewrites unless replacement is genuinely required.