179 lines
6.0 KiB
Markdown
179 lines
6.0 KiB
Markdown
# GitHub Copilot Integration
|
|
|
|
This guide explains how to integrate Agent Guardrails with GitHub Copilot using repo-level instructions.
|
|
|
|
## Overview
|
|
|
|
GitHub Copilot reads a file at `.github/copilot-instructions.md` for repo-level instructions. This file provides markdown-formatted guidance that applies to all Copilot completions, suggestions, and chat interactions in the repository.
|
|
|
|
There are no per-skill files -- all instructions live in one file.
|
|
|
|
## Setup
|
|
|
|
### 1. Run Setup Script
|
|
|
|
```bash
|
|
python scripts/setup_agents.py --install --platform copilot
|
|
```
|
|
|
|
This creates:
|
|
```
|
|
.github/
|
|
└── copilot-instructions.md
|
|
```
|
|
|
|
### 2. Manual Installation
|
|
|
|
If you prefer to install without the script:
|
|
|
|
```bash
|
|
# Copy from template
|
|
cp .github/copilot-instructions.md /path/to/your/project/.github/copilot-instructions.md
|
|
```
|
|
|
|
Copilot does not support symlinks for instructions -- use copy mode only.
|
|
|
|
### 3. Verify Installation
|
|
|
|
```bash
|
|
cat .github/copilot-instructions.md
|
|
```
|
|
|
|
You should see the guardrails instructions beginning with `# GitHub Copilot Instructions`.
|
|
|
|
## File Format
|
|
|
|
The `.github/copilot-instructions.md` file is a plain markdown document. GitHub Copilot reads this as project-level instructions injected into every chat session and code suggestion context.
|
|
|
|
### Structure
|
|
|
|
```markdown
|
|
# GitHub Copilot Instructions
|
|
|
|
These instructions apply to all Copilot completions, suggestions, and chat
|
|
interactions in this repository.
|
|
|
|
## The Four Laws of Agent Safety
|
|
|
|
1. **Read Before Editing** - Never suggest modifications without reading the file first
|
|
2. **Stay in Scope** - Only work on files within the authorized task scope
|
|
3. **Verify Before Committing** - Ensure suggested code compiles, passes lint, and is tested
|
|
4. **Halt When Uncertain** - Ask for clarification instead of guessing
|
|
|
|
## Code Generation Rules
|
|
...
|
|
|
|
## Forbidden Patterns
|
|
...
|
|
|
|
## Three Strikes Rule
|
|
...
|
|
```
|
|
|
|
### Key Sections
|
|
|
|
| Section | Purpose |
|
|
|---------|---------|
|
|
| The Four Laws | Core safety rules for all operations |
|
|
| Code Generation Rules | Scope, production-first, error handling, security |
|
|
| Forbidden Patterns | Code that must never be suggested |
|
|
| Three Strikes Rule | Failure recovery protocol |
|
|
| File Headers | Required header format for new files |
|
|
| Architecture Patterns | Clean Architecture, CQRS, SOLID for Go/MCP code |
|
|
|
|
## How It Applies
|
|
|
|
Copilot reads `.github/copilot-instructions.md` at the repository level. This means:
|
|
|
|
- All inline suggestions respect the scope and production-first rules
|
|
- Chat responses apply the Four Laws
|
|
- Forbidden patterns are never suggested
|
|
- Architecture patterns apply when working on `mcp-server/`
|
|
- File headers are included in new file suggestions
|
|
|
|
### Scope in Copilot
|
|
|
|
Unlike agentic tools (Claude Code, Cursor), Copilot operates at the suggestion level. The scope rules translate as:
|
|
|
|
- Only suggest changes in the file being edited
|
|
- Do not suggest refactoring unrelated code
|
|
- Do not suggest adding new files unless the user requests it
|
|
- When unclear about intent, do not assume -- suggest the minimal change
|
|
|
|
## Customization
|
|
|
|
### Adding Project-Specific Instructions
|
|
|
|
Append custom sections to `.github/copilot-instructions.md`:
|
|
|
|
```markdown
|
|
## Project-Specific Rules
|
|
|
|
- All new Python files must use type hints
|
|
- API endpoints must follow OpenAPI 3.1 spec
|
|
- Use pytest fixtures, not unittest classes
|
|
```
|
|
|
|
### Team-Level Instructions
|
|
|
|
Since this file lives in `.github/`, it is committed to the repository and shared with the entire team. All contributors get the same guardrails automatically.
|
|
|
|
### Combining with Personal Instructions
|
|
|
|
GitHub Copilot also supports personal instructions in your Copilot settings. Repo-level instructions (`.github/copilot-instructions.md`) take precedence over personal instructions for files in this repository.
|
|
|
|
## Shared Prompts Reference
|
|
|
|
The `copilot-instructions.md` file incorporates rules from the shared prompts directory:
|
|
|
|
| Shared Prompt | Rules Covered |
|
|
|---------------|---------------|
|
|
| `skills/shared-prompts/four-laws.md` | The Four Laws (canonical source) |
|
|
| `skills/shared-prompts/halt-conditions.md` | Full halt conditions checklist |
|
|
| `skills/shared-prompts/three-strikes.md` | Failure tracking and escalation |
|
|
| `skills/shared-prompts/production-first.md` | Production-before-tests ordering |
|
|
| `skills/shared-prompts/clean-architecture.md` | Clean Architecture patterns for Go/MCP |
|
|
| `skills/shared-prompts/cqrs.md` | CQRS command/query separation |
|
|
|
|
When shared prompts are updated, re-run the setup script to regenerate the instructions:
|
|
|
|
```bash
|
|
python scripts/setup_agents.py --install --platform copilot
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Instructions Not Applied
|
|
|
|
**Check:**
|
|
- File exists at `.github/copilot-instructions.md`: `ls -la .github/copilot-instructions.md`
|
|
- The `.github/` directory is committed to the repository
|
|
- Your IDE has the GitHub Copilot extension installed and enabled
|
|
- Copilot has indexed the repository (restart your IDE if needed)
|
|
|
|
### Outdated Instructions
|
|
|
|
**Fix:**
|
|
- Re-run: `python scripts/setup_agents.py --install --platform copilot`
|
|
|
|
### Conflicting Personal Instructions
|
|
|
|
If you have personal Copilot instructions that conflict with repo-level instructions, the repo-level file takes precedence for this repository. Remove conflicting personal settings or align them with the guardrails.
|
|
|
|
### Instructions Too Long
|
|
|
|
If the file becomes very long, Copilot may truncate it. Keep the file focused on the most critical rules. Move detailed patterns to referenced documents like `AGENT_GUARDRAILS.md` and `shared-prompts/`.
|
|
|
|
## Best Practices
|
|
|
|
1. **Regenerate after updates** - Re-run setup when shared prompts change
|
|
2. **Keep it concise** - Copilot has context limits; prioritize critical rules
|
|
3. **Commit to the repo** - All team members get guardrails automatically
|
|
4. **Reference, don't duplicate** - Point to shared-prompts/ for full details
|
|
|
|
## References
|
|
|
|
- [AGENT_GUARDRAILS.md](AGENT_GUARDRAILS.md) - Core safety protocols
|
|
- [AGENTS_AND_SKILLS_SETUP.md](AGENTS_AND_SKILLS_SETUP.md) - Unified setup guide
|
|
- [skills/shared-prompts/](../skills/shared-prompts/) - Canonical prompt definitions
|