RomanNum3ral
/
claw-code
mirror of https://github.com/instructkr/claw-code.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
claw-code/.guardrails/docs/COPILOT_INTEGRATION.md

6.0 KiB
Raw Blame History

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

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:

# 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

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

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

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

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