ai-instructions: Instructions file for GitHub Copilot

AI Customization Contract

Dependencies

• Read the workspace's copilot-instructions.md before creating or changing an AI customization file.
• Read the applicable domain instruction files before editing a file that they govern.
• Treat a missing required instruction, reference, or template as a blocker. Do not silently bypass it or invent a substitute.

Scope and ownership

• Keep workspace-wide behavior in copilot-instructions.md.
• Keep reusable authoring and review rules for AI customization files in this contract.
• Keep topic-specific implementation rules in the narrowest applicable instruction file.
• Keep one canonical owner for each shared policy. Reference that owner instead of duplicating the policy in other files.
• Limit each file to the behavior implied by its name, description, and routing pattern.

Metadata and routing

• Give every customization file the metadata required by its file type.
• Write description so the file's purpose and trigger conditions are discoverable.
• Add argument-hint when a prompt requires user-provided input.
• Use the narrowest applyTo pattern that covers the intended files without accidental matches.
• Check routing patterns for overlap with existing files before adding or changing them.
• Preserve technical literals exactly, including paths, commands, URLs, identifiers, configuration keys, and versions, unless they are demonstrably incorrect.

Authoring rules

• Use direct, imperative language for mandatory behavior.
• Mark optional behavior explicitly as optional.
• Keep one enforceable behavior per rule or bullet.
• Split compound rules when they contain independent decisions or conditions.
• Keep each section focused on one purpose, with a heading that matches its contents.
• Put rules in the order the governed workflow encounters them.
• Keep instruction contracts product-agnostic and reusable across real projects. Never reference tutorial repos, sample module paths, learning-catalog numbers, or project-specific folders/networks from teaching material.
• Remove filler only when doing so preserves the rule's meaning and enforceability.
• Preserve existing behavior when improving wording unless the user explicitly approves a behavior change.
• Do not turn a style preference or optional rewrite into a defect, requirement, or safety rule.