copilot-config

---
name: copilot-config
description: "Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'."
source: package
domain: process
---

# Copilot Skill

## When to use

Use this skill when:
- Editing `.github/copilot-instructions.md` to improve Copilot behavior
- Dealing with Copilot PR review comments (via `/fix-pr-bot-comments`)
- Analyzing Copilot's review patterns to identify recurring false positives
- Tuning Copilot's code suggestions for the project


Do NOT use when:
- Augment-specific behavior (use Augment rules and skills)
- Writing application code

## Procedure: Configure Copilot

### Configuration File

**`.github/copilot-instructions.md`** — the single source of truth for Copilot behavior.

### What Copilot Can and Cannot Read

| Context | Copilot Code Review (PR bot) | Copilot Chat (IDE) |
|---|---|---|
| `.github/copilot-instructions.md` | ✅ Reads automatically | ✅ Reads automatically |
| `.augment/rules/` | ❌ Cannot access | ✅ Can read if referenced |
| `.augment/skills/` | ❌ Cannot access | ✅ Can read if referenced |
| `.augment/guidelines/` | ❌ Cannot access | ✅ Can read if referenced |
| `AGENTS.md` | ❌ Cannot access | ✅ Can read if referenced |
| `agents/` | ❌ Cannot access | ✅ Can read if referenced |

**Key implication:** `copilot-instructions.md` must be **self-contained** for PR reviews.
It cannot reference `.augment/` files and expect Copilot Code Review to follow them.
For Copilot Chat users, a hint at the top of the file points to `.augment/` for deeper context.

### What Copilot Controls

| Area | How |
|---|---|
| Code suggestions | Follows coding standards, PHP 8.2 patterns, Laravel conventions |
| PR reviews | Reviews only modified lines + direct dependencies |
| Comment behavior | Deduplication rules, reply handling, scope control |
| Language | English code comments, bilingual PR comments (EN + DE) |

### Relationship to `.augment/`

`copilot-instructions.md` and `.augment/` serve different audiences:

| | `copilot-instructions.md` | `.augment/` |
|---|---|---|
| **Audience** | GitHub Copilot (bot + chat) | Augment Agent |
| **Scope** | Coding standards, review rules | Full agent infrastructure |
| **Self-contained?** | Yes (must be) | Yes (skills reference each other) |
| **Duplication** | Intentional — Copilot can't read `.augment/` | No duplication needed |

When updating coding rules, check if both files need the change:
- **Architecture/coding rules** → update both (Copilot needs them self-contained)
- **Agent workflows/commands** → only `.augment/` (Copilot doesn't use these)
- **PR review behavior** → only `copilot-instructions.md` (Augment uses `/fix-pr-*` commands)

## PR Review Comment Rules

Copilot is configured with strict comment behavior rules:

### Deduplication

Before creating a comment, Copilot must:
1. Check if it already commented on the same line/concern
2. Check if another reviewer already raised the same point
3. Skip if a duplicate would be created

### Reply Handling

| Developer response | Copilot action |
|---|---|
| Accepted suggestion | Acknowledge briefly or resolve |
| Rejected with reason | Accept the decision, do NOT re-raise |
| Asked a question | Answer with analysis and examples |
| Dismissed without explanation | Move on, do NOT re-raise |

### Key Principle

**One comment per concern per location.** Never duplicate, never re-raise rejected suggestions.

## Handling Copilot Bot Comments (as Augment Agent)

When the user asks to fix Copilot's PR review comments (via `/fix-pr-bot-comments`):

### 1. Evaluate Each Comment

For each Copilot comment, determine:

| Category | Action |
|---|---|
| **Valid and actionable** | Fix the code as suggested |
| **Valid but already handled** | Reply explaining it's already addressed (e.g., by ECS/Rector) |
| **False positive** | Reply explaining why the suggestion doesn't apply |
| **Style nitpick** | Reply that ECS/Rector handles this automatically |
| **Out of scope** | Reply that the comment is outside the PR's change scope |

### 2. Reply Format

When replying to Copilot comments on behalf of the user:

```markdown
{English explanation}

---

🇩🇪 {German translation}
```

### 3. Common False Positives

Copilot frequently suggests things that conflict with project conventions:

| Copilot suggests | Project convention | Response |
|---|---|---|
| Add `null !== $var` with `is_string()` | `is_string()` already excludes null | False positive — redundant check |
| Register events manually | Laravel 11 uses event discovery | Not needed since Laravel 11 |
| Use `float` for money | Use `Math` helper class | Project uses BCMath via `Math::*()` |
| Add PHPDoc repeating signature | Only add PHPDoc when types are insufficient | Redundant documentation |
| Suggest `array()` syntax | Short syntax `[]` enforced by ECS | Auto-fixed by ECS |
| Add `final` to mocked classes | Classes mocked by Mockery can't be final | Would break tests |

## Improving Copilot Instructions

When updating `.github/copilot-instructions.md`:

### Structure

- Each section starts with `## ✅ {Title}`
- Rules are bullet points, concise and actionable
- Code examples use `✅ Correct` / `❌ Wrong` pattern
- Keep sections focused — one concern per section

### When to Add New Rules

| Trigger | Action |
|---|---|
| Copilot repeatedly makes the same wrong suggestion | Add to "Known Issues" section |
| New project convention introduced | Add to the relevant section |
| Copilot ignores scope control | Strengthen "Code Review Scope" section |
| Copilot creates duplicate comments | Strengthen "Comment Behavior" section |

### When NOT to Add Rules

- Don't add rules for things ECS/Rector auto-fix (Copilot doesn't need to know)
- Don't add rules that duplicate `AGENTS.md` content (Copilot doesn't read `AGENTS.md`)
- Don't add overly specific rules for one-off situations

## Relationship to Other Tools

| Tool | Role | Config |
|---|---|---|
| **Copilot** | IDE suggestions + PR reviews | `.github/copilot-instructions.md` |
| **Augment** | Agent workflows + deep analysis | `.augment/` + `agents/` |
| **Greptile** | PR review bot (if enabled) | Separate config |
| **ECS** | Code style auto-fix | `ecs.php` (project root) |
| **Rector** | Code refactoring auto-fix | `rector.php` (project root) |
| **PHPStan** | Static analysis | `phpstan.neon` (project root) |

Copilot and Augment complement each other:
- **Copilot** handles real-time suggestions and automated PR reviews
- **Augment** handles complex workflows, deep analysis, and multi-step tasks

## Related

- **File:** `.github/copilot-instructions.md` — Copilot configuration
- **Command:** `/fix-pr-bot-comments` — fix bot review comments
- **Command:** `/fix-pr-comments` — fix all review comments
- **Skill:** `code-review` — PR review process and conventions


## Output format

1. Updated copilot-instructions.md or related config file
2. Summary of changes and which Copilot behavior is affected

## Gotcha

- copilot-instructions.md is for GitHub Copilot, NOT for Augment — don't mix audiences.
- Don't duplicate .augment/ content into copilot-instructions.md — it bloats the file and causes drift.
- Copilot reads the ENTIRE instructions file on every request — keep it under 500 lines.

## Do NOT

- Do NOT let Copilot generate code that violates project coding standards.
- Do NOT accept Copilot review comments without verifying them against the codebase.

## Auto-trigger keywords

- GitHub Copilot
- copilot instructions
- PR review
- copilot behavior