---
description: "Agent System Integration - How all instructions connect"
applyTo: "**"
---

# 🔗 Agent System Integration Guide

**Purpose:** Show how all agent instructions work together as one unified system.

---

## 🎯 System Architecture

All agents (GitHub Copilot, Claude, other AI coding tools) follow the same framework:

```
Entry Points:
├── .github/copilot-instructions.md ────────┐
│   └─ Session startup                       │
├── AGENTS.md ───────────────────────────────┤ These 3 guide
│   └─ Quick reference                       │ all decisions
└── .github/instructions/AGENT_BOOT_PROTOCOL.md ┤
    └─ Pre-coding checklist                   │
                                              ↓
                    .github/instructions/AGENT_AUTONOMOUS_PROTOCOL.md
                         ↓
                    5-Layer Decision Framework
                    (UNDERSTAND → VALIDATE → IMPLEMENT → DOCUMENT → VERIFY)
                         ↓
           Authority Sources (Order Matters):
           1. docs/technical/reference.md (ground truth)
           2. AGENTS.md (conventions)
           3. AGENT_AUTONOMOUS_PROTOCOL.md (process)
           4. FOCUS.instructions.md (quality)
           5. Actual code files (only after 1-4)
```

---

## 📚 How They Connect

### 1. **GitHub Copilot Instructions** (`.github/copilot-instructions.md`)
- **When:** Every Copilot session start
- **Why:** Provide unified protocol for session startup
- **Reads:** References all other instruction files
- **Outputs:** Workspace map protocol + lookup pattern
- **Next:** Opens AGENT_BOOT_PROTOCOL.md

### 2. **Agent Boot Protocol** (`.github/instructions/AGENT_BOOT_PROTOCOL.md`)
- **When:** 60 seconds BEFORE coding starts
- **Why:** Quick context checklist to load all authority sources
- **Reads:** AGENT_AUTONOMOUS_PROTOCOL.md + docs/technical/reference.md
- **Outputs:** Pre-coding checklist, decision guide
- **Next:** Applies 5-Layer framework from AGENT_AUTONOMOUS_PROTOCOL.md

### 3. **AGENTS.md** - Quick Reference
- **When:** During any lookup ("Where is X?")
- **Why:** Fast conventions reference without reading full docs
- **Reads:** Everything is condensed here
- **Outputs:** Domain mappings, search precedence, anti-patterns
- **Next:** Points to detailed authority sources when needed

### 4. **Agent Autonomous Protocol** (`.github/instructions/AGENT_AUTONOMOUS_PROTOCOL.md`)
- **When:** Decision-making on complex changes
- **Why:** Systematic 5-Layer framework for all work
- **Reads:** Authority sources + related files
- **Outputs:** Complete validation checklists, pattern library
- **Next:** Guides implementation + documentation updates

### 5. **Focus Instructions** (`.github/instructions/FOCUS.instructions.md`)
- **When:** Code quality checks
- **Why:** French instructions for your specific quality standards
- **Reads:** AGENT_AUTONOMOUS_PROTOCOL.md context
- **Outputs:** Code standards, documentation placement, anti-patterns
- **Next:** Validates all code against these standards

### 6. **Authority Sources** (In precedence order)
1. `docs/technical/reference.md` - Ground truth for architecture
2. `AGENTS.md` - Conventions and quick ref
3. `AGENT_AUTONOMOUS_PROTOCOL.md` - Complete process
4. `FOCUS.instructions.md` - Quality standards
5. Actual code files - Only after above

---

## 🔄 Decision Flow Example

**User asks:** "Fix the import dialog bug"

```
┌─ Agent starts session ──────────────────┐
│  ↓ Opens .github/copilot-instructions.md
│  ↓ Loads workspace map protocol
│  ↓ Reads AGENTS.md for quick ref
│  ↓ Opens AGENT_BOOT_PROTOCOL.md
│
├─ Agent enters decision mode ────────────┤
│  ↓ Question: "Where is the import dialog?"
│  ↓ Search precedence from AGENTS.md:
│    1. docs/technical/reference.md (find entry)
│    2. Grep component names
│    3. Map dependencies
│    4. Trace imports
│
├─ Agent applies 5-Layer Framework ──────┤
│  Layer 1 (UNDERSTAND):
│    ↓ Read AGENT_AUTONOMOUS_PROTOCOL.md § Layer 1 checklist
│    ↓ Map related files (5-10 minimum)
│    ↓ Build dependency graph
│
│  Layer 2 (VALIDATE):
│    ↓ Check end-to-end logic
│    ↓ Find all related files
│    ↓ Test against FOCUS standards
│
│  Layer 3 (IMPLEMENT):
│    ↓ Make code changes
│    ↓ Verify no side effects
│    ↓ Update all related files
│
│  Layer 4 (DOCUMENT):
│    ↓ Update docs/technical/reference.md if endpoints changed
│    ↓ Add inline comments for complex logic
│    ↓ Use subfolder structure in /docs
│
│  Layer 5 (VERIFY):
│    ↓ Run build: npm run build:frontend
│    ↓ Check for errors
│    ↓ Validate related imports still work
│
└─ Agent completes with confidence ──────┘
```

---

## ✅ How Agents Should Use This System

### Session 1: First Time
1. Read: `.github/instructions/README_AGENT_SYSTEM.md` (overview)
2. Read: `.github/instructions/AGENT_BOOT_PROTOCOL.md` (setup)
3. Read: `docs/technical/reference.md` (workspace) 
4. Read: `AGENTS.md` (conventions)
5. Read: `.github/instructions/AGENT_AUTONOMOUS_PROTOCOL.md` (full framework)

### Session 2+: Every New Task
1. Read: `.github/instructions/AGENT_BOOT_PROTOCOL.md` (reminder)
2. Skim: `docs/technical/reference.md` for your domain
3. Reference: `AGENTS.md` for quick lookup
4. Apply: 5-Layer framework from AGENT_AUTONOMOUS_PROTOCOL.md

### During Work: Authority Stack
```
If unsure about:
├─ "Where is X?" 
│  └─ Use AGENTS.md search precedence
├─ "What endpoints exist?"
│  └─ Check docs/technical/reference.md → Endpoints API
├─ "How do I structure this?"
│  └─ Read AGENT_AUTONOMOUS_PROTOCOL.md § Pattern Library
├─ "Is this code quality OK?"
│  └─ Check FOCUS.instructions.md standards
└─ "What's the process?"
   └─ Follow 5-Layer framework
```

---

## 🚨 Priority & Precedence

### When Instructions Conflict
1. **AGENT_AUTONOMOUS_PROTOCOL.md** wins (system-level)
2. **FOCUS.instructions.md** wins over general coding standards
3. **docs/technical/reference.md** wins over assumptions
4. **AGENTS.md** is tie-breaker for conventions

### When in Doubt
1. Check `docs/technical/reference.md` first (ground truth)
2. Read relevant section of AGENT_AUTONOMOUS_PROTOCOL.md
3. Ask user before guessing

---

## 📞 Links Between Files

### From: `.github/copilot-instructions.md`
→ Read next: `AGENT_BOOT_PROTOCOL.md`
→ Reference: `AGENT_AUTONOMOUS_PROTOCOL.md`
→ Reference: `FOCUS.instructions.md`
→ Reference: `docs/technical/reference.md`

### From: `AGENT_BOOT_PROTOCOL.md`
→ Read next: `AGENT_AUTONOMOUS_PROTOCOL.md`
→ Reference: `TRIGGER_RULES.md`
→ Reference: `docs/technical/reference.md`
→ Reference: `AGENTS.md`

### From: `AGENT_AUTONOMOUS_PROTOCOL.md`
→ Apply checklist from: `FOCUS.instructions.md`
→ Verify against: `docs/technical/reference.md`
→ Use patterns from: Pattern Library § (same file)
→ Update: `docs/technical/reference.md` when done

### From: `AGENTS.md`
→ Authority: `docs/technical/reference.md`
→ Process: `AGENT_AUTONOMOUS_PROTOCOL.md`
→ Standards: `FOCUS.instructions.md`
→ Integration: `AGENT_SYSTEM_INTEGRATION.md` (this file)

---

## 🎯 Success Metrics

An agent is using this system correctly when:

✅ **First check:** Opens `docs/technical/reference.md` before assuming anything
✅ **Related files:** Finds 5-10 related files before editing target
✅ **Dependencies:** Maps transitive imports with `@/` resolution
✅ **Documentation:** Updates only `/docs` subfolders with indexes
✅ **No testing:** Never runs `npm run dev` (user tests)
✅ **Authority:** When unsure, checks `docs/technical/reference.md` not guessing
✅ **Quality:** Every change passes `npm run build:*` tests
✅ **Completeness:** No dangling references or unfinished code
✅ **Communication:** Brief confirmations, no lengthy explanations
✅ **Escalation:** Asks user when truly ambiguous

---

## 🔧 Maintenance

This file updates when:
- New instruction files are created
- Process/workflow changes
- Authority precedence changes

**Owner:** Agent System Maintainer  
**Last Updated:** Per `.github/instructions/INDEX.md` version  
**Version:** 1.0

