Skip to content

AI_GOVERNANCE.md

Latest commit

 

History

History
72 lines (58 loc) · 3.19 KB

AI_GOVERNANCE.md

File metadata and controls

72 lines (58 loc) · 3.19 KB

AI guidance governance

Purpose

This repo uses a tool-agnostic, agent-first documentation strategy:

  • Component knowledge lives with the component (Src/**/AGENTS.md).
  • A small set of scoped instruction files in .github/instructions/ provides prescriptive, enforceable constraints.
  • .github/AGENTS.md is the short “front door” that links to the right places.
  • Agent definitions in .github/agents/ and role chatmodes in .github/chatmodes/ describe behavior/persona, not system architecture.

Source of truth

  • Component architecture & entry points: Src/<Component>/AGENTS.md
  • Repo-wide workflow (how to build/test, safety constraints): .github/AGENTS.md
  • Non-negotiable rules (security, terminal restrictions, installer rules, etc.): .github/instructions/*.instructions.md

No duplication rule

  • Do not copy component descriptions into .github/instructions/.
  • Do not restate rules in multiple places. Prefer linking.
  • If a rule must be enforced by agents for a subtree, add a scoped .instructions.md; otherwise document it in the relevant AGENTS.md.

What goes where

.github/AGENTS.md

Use for:

  • One-page onboarding for agents: build/test commands, repo constraints, and links.
  • Pointers to the curated instruction set and the component docs.

.github/instructions/*.instructions.md

Use for:

  • Prescriptive constraints that must be applied during editing/review.
  • Cross-cutting rules that prevent expensive mistakes (security, terminal command restrictions, installer rules, managed/native boundary rules).

Curated keep set (intentionally small):

  • build.instructions.md
  • debugging.instructions.md
  • installer.instructions.md
  • managed.instructions.md
  • navigation.instructions.md
  • native.instructions.md
  • powershell.instructions.md
  • repo.instructions.md
  • security.instructions.md
  • terminal.instructions.md
  • testing.instructions.md

Src/**/AGENTS.md

Use for:

  • Where to start (entry points, key projects, typical workflows).
  • Dependencies and cross-component links.
  • Tests (where they live, how to run them).

Baseline expectations for a component agent doc:

  • Where to start (projects, primary entry points)
  • Dependencies (other components/layers)
  • Tests (test projects and the recommended ./test.ps1 invocation)

.github/agents/ and .github/chatmodes/

Use for:

  • Role definitions, boundaries, and tool preferences.
  • Do not put component architecture here; link to the component AGENTS.md.

External standards alignment (post-2025)

  • AGENTS.md: Supported as a simple, vendor-neutral instruction format by multiple tools (for example, Cursor’s project rules). Use plain Markdown with clear headings and concise rules.
  • MCP (Model Context Protocol): Use MCP for tool/data integration rather than vendor-specific plugins; MCP provides a standardized, versioned protocol for AI tool connectivity.

Adding a new scoped instruction file

Add a new .github/instructions/<name>.instructions.md only when:

  • The guidance is prescriptive (MUST/DO NOT), and
  • It applies broadly or to a subtree, and
  • It would be harmful if Copilot ignored it.

Otherwise, update the appropriate Src/**/AGENTS.md.