# AI Overview

## Start Here
AI tools help with drafting, refactoring, explaining code, and accelerating routine tasks. They are not a replacement for engineering judgment, security review, or domain knowledge.

## What To Expect In The First 30 Minutes
1. Confirm you have access to GitHub Copilot Enterprise.
2. Install the editor plugin for your platform.
3. Run a simple prompt to verify suggestions appear.
4. Read the usage and token guidance to avoid accidental overuse.

## What AI Is and Is Not
- AI is a productivity assistant that can suggest code, summarize context, and propose solutions.
- AI is not a source of truth. Always validate outputs with tests, code review, and domain checks.

### Example (Good vs Risky)
Example prompts:
```text
Good: Summarize this file and list the top 3 risks.
Risky: Rewrite this subsystem without review.
```

## GitHub Copilot Enterprise
### What It Is
Copilot is an AI coding assistant that integrates with editors and chats to help you write and understand code.

### Access Requirements
- You must be provisioned for Copilot Enterprise by the org.
- You must sign in with your GitHub account that has access.

### Setup Steps (High-Level)
1. Confirm access with your team or admin.
2. Sign in to GitHub in your editor or plugin.
3. Verify Copilot is enabled in editor settings.
4. Run a quick prompt to validate it works.

### What You Should See
- A Copilot icon or status indicator in your editor.
- Inline code suggestions as you type.
- A chat panel that can answer questions.

### Quick Access Checklist
- GitHub account is linked to the org.
- SSO or required auth flow is completed.
- Copilot is enabled in the editor or plugin settings.

## Terminology
- Copilot: The AI assistant integrated into your editor.
- Chat: The conversational interface in your editor.
- Agents: Structured workflows that break work into steps.
- Skills: Reusable knowledge or workflows the assistant can apply.
- Tokens: The usage units that track AI consumption.

## Instructions (Repo Rules)
Instructions are repo-scoped rule files that auto-apply based on file patterns. They set coding or documentation standards the assistant must follow when editing matching files.

Where they live:
- The repo-level instructions directory (for example, [instructions/](../../instructions/))
- Editor or org-level instruction files when configured by your team

Instructions are always-on defaults. Agents and skills are optional and only used when you explicitly invoke them.

## Agents vs Skills (Where They Live)
Agents are full personas or modes (for example, Task Researcher) that control how the assistant behaves end-to-end. Skills are focused, reusable workflows (for example, webapp-testing) that the assistant can load for a specific task.

Where they live:
- Agents can be stored in a repo (project-specific) or in a user-level folder for global reuse.
- Skills are typically installed globally via the approved skills directory and synced with a manifest.

If you need the official agent assets repo, ask your team lead or check your internal setup docs.

## 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.

Ask: Quick questions, summaries, or explanations.
Edit: Small, specific changes with constraints.
Plan: A step-by-step plan before edits.
Agent: Multi-step work across files with checks.

Example prompts:
```text
Ask: Summarize this file in 5 bullets and list 2 risks.
Edit: Update this function to return nil when the input is empty. Keep behavior the same otherwise.
Plan: Give me a 6-step plan to add caching to this service. Wait for approval before edits.
Agent: Refactor these two files, update unit tests, then summarize the changes and test results.
```

### Example: Chat vs Agents
Example prompts:
```text
Chat: What does this function do?
Agent: Plan and refactor this module, then list tests to add.
```

## First Prompt (Safe)
Try a small, safe prompt to confirm everything is working:

```text
Summarize what this file does in 3 bullet points.
```

## Guardrails And Good Habits
- Keep prompts scoped to a single task.
- Ask for a plan before large changes.
- Verify outputs with tests and review.
- Avoid sharing secrets or sensitive data.

### Example: Safe Prompt
Example prompt:
```text
Refactor only the validation logic in this file. Keep behavior the same and list tests to update.
```

## Getting Help
- Ask your team lead or the AI docs owner.
- Use the escalation guidance in [Troubleshooting and FAQ](troubleshooting.md).