From 9aaa24d6a4094a8ad5c0194905f2ec0213837c8c Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Tue, 10 Feb 2026 15:46:24 -0600 Subject: [PATCH] docs: add key repo files section --- docs/ai/overview.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/ai/overview.md b/docs/ai/overview.md index fc72878..330fb97 100644 --- a/docs/ai/overview.md +++ b/docs/ai/overview.md @@ -48,6 +48,46 @@ Copilot is an AI coding assistant that integrates with editors and chats to help - Skills: Reusable knowledge or workflows the assistant can apply. - Tokens: The usage units that track AI consumption. +## Key Repo Files (Why They Exist) +These files explain how the AI docs are organized and how contributors should work. Each one has a different job. + +### Agents.md +What it is: The workflow rules for using AI in this repo. + +Why you create it: It keeps requests consistent so changes are scoped, reviewable, and repeatable. + +What to include: +- Request structure (goal, inputs, output, verification). +- Plan-first guidance for multi-step changes. +- Sync rule: keep PRD.md and README.md aligned when workflows or scope change. + +Project example: See [Agents.md](../../Agents.md) for the request template and contribution workflow used in this repo. + +### PRD.md +What it is: The product requirements for the documentation set. + +Why you create it: It anchors scope and success metrics so the docs do not drift. + +What to include: +- Problem statement, goals, and non-goals. +- Target audience and user stories. +- Content requirements (step-by-step guidance and examples). +- Definition of done and sync expectations. + +Project example: See [PRD.md](../../PRD.md) for the requirements and definition of done used here. + +### README.md +What it is: The entry point for contributors and readers who need quick orientation. + +Why you create it: It tells people what the repo is, where to start, and how to contribute. + +What to include: +- Repo purpose and audience. +- Where to start (index, overview, setup guides). +- Contribution habits and publishing steps. + +Project example: See [README.md](../../README.md) for the start-here links and local workflow. + ## Chat Types In Plain English Copilot chat has four modes. Pick the smallest one that fits the task.