---
title: "Agent Smart System - Master Reference"
version: "1.0"
audience: "AI Agents / Copilot"
criticality: "SYSTEM_CRITICAL"
---

# 🤖 Agent Smart System - Master Reference

**Your personal knowledge base for writing quality code, maintaining docs, and making smart decisions.**

**Read this first:** AGENT_BOOT_PROTOCOL.md (2 minutes)  
**Then reference:** This file as needed

---

## 📚 Document Hierarchy

### 🎯 When You Need...

| I Need... | Read This | Time | Location |
|-----------|-----------|------|----------|
| **To start a session** | AGENT_BOOT_PROTOCOL.md | 2 min | `.github/instructions/` |
| **To understand the framework** | AGENT_AUTONOMOUS_PROTOCOL.md | 5 min | `.github/instructions/` |
| **To decide WHEN to apply rules** | TRIGGER_RULES.md | 3 min | `.github/instructions/` |
| **To update documentation** | DOCUMENTATION_SYNC.md | 2 min | `.github/instructions/` |
| **To find a symbol/file** | docs/technical/reference.md | <5 min | `docs/` |
| **To understand workspace** | AGENTS.md | 2 min | Root |
| **To navigate this entire system** | THIS FILE | 3 min | Root |

---

## 🎓 Core System Concepts

### The 5-Layer Protocol

Every code change follows this:

```
Layer 1: UNDERSTAND    (5 mins)  → Read docs, find related files, trace data flow
Layer 2: VALIDATE      (3 mins)  → Check single responsibility, validate logic
Layer 3: IMPLEMENT     (var)     → Code following patterns, build immediately
Layer 4: DOCUMENT      (2-3 min) → Update docs/technical/reference.md, index.ts, AGENTS.md
Layer 5: VERIFY        (2 mins)  → Build passes, 0 errors, no regressions
```

**Golden Rule:** Skip no layer. Every change follows all 5.

---

### Smart Documentation Sync

After code, update docs:

```
Create new file? → Add to docs/technical/reference.md + index.ts
Modify structure? → Update docs/technical/reference.md + AGENTS.md
Delete something? → Remove from docs/technical/reference.md
Build and verify → 0 errors required

Total: 2-3 minutes (automatic)
```

---

### Trigger-Based Decisions

Know your request type → Know your approach:

```
CREATE → Full 5-Layer (careful)
FIX → Fast 5-Layer (quick)
REFACTOR → Full 5-Layer (very careful)
QUESTION → Read only (no changes)
REVIEW → Analyze + Selective (pick Tier 1)
```

See **TRIGGER_RULES.md** for decision matrix.

---

## 🗂️ System Architecture

```
.github/instructions/
├─ AGENT_AUTONOMOUS_PROTOCOL.md    ← How to work (the framework)
├─ TRIGGER_RULES.md                ← When to apply what (decision logic)
├─ DOCUMENTATION_SYNC.md            ← How to keep docs current (sync protocol)
└─ AGENT_BOOT_PROTOCOL.md           ← Quick start (2-min onboarding)

docs/
├─ REFERENCE.md                     ← Authority document (all symbols mapped)
└─ ... (other domain docs)

Root
├─ AGENTS.md                        ← Workspace map (by domain)
└─ THIS FILE                        ← You are here

Code Structure
├─ components/[domain]/
│  ├─ [Section]Section.vue         ← Reusable business UI (250-350 lines)
│  └─ index.ts                      ← Exports all components
│
├─ composables/
│  ├─ use[Feature][Logic].ts        ← Shared logic (30-50 lines)
│  └─ index.ts                      ← Exports all composables
│
├─ pages/[domain]/(mobile|web)/
│  └─ [Page]Page.vue                ← Thin wrapper (20-40 lines, uses composables)
│
└─ styles/
   ├─ _section-base.scss            ← SCSS foundation (breakpoints, utilities)
   └─ ... (other styles)
```

---

## 🎯 Request → Action Flowchart

```
User Request
    ↓
Is it code change?
├─ NO → Answer from docs (no code touch)
└─ YES → What TYPE of change?
        ├─ CREATE → Full 5-Layer AAP
        ├─ FIX → Fast 5-Layer AAP  
        ├─ REFACTOR → Full 5-Layer AAP (very careful)
        ├─ QUESTION → Search docs/technical/reference.md
        └─ REVIEW → Analyze + Selective implementation
              ↓
        Follow 5-Layer Protocol:
        1. UNDERSTAND (read, grep, trace)
        2. VALIDATE (check logic)
        3. IMPLEMENT (code + build)
        4. DOCUMENT (update refs)
        5. VERIFY (0 errors)
              ↓
        COMPLETE ✅
```

---

## 🚀 Quick Start by Request Type

### 1. "Create something new"
```
1. Read: TRIGGER_RULES.md → Scenario A (Create)
2. Read: docs/technical/reference.md → Find similar patterns
3. Follow: 5-Layer Protocol
4. Result: New file + updated docs
```

### 2. "Fix an error"
```
1. Find: Error source
2. Read: TRIGGER_RULES.md → Scenario B (Fix)
3. Follow: Fast 5-Layer Protocol
4. Result: Error fixed, build passes
```

### 3. "Refactor duplicated code"
```
1. Find: Duplication with grep
2. Read: TRIGGER_RULES.md → Scenario C (Refactor)
3. Follow: 5-Layer Protocol (very careful)
4. Result: Clean code + updated docs
```

### 4. "I need to find something"
```
1. Read: docs/technical/reference.md (Ctrl+F)
2. If not found: Check AGENTS.md
3. If still not found: grep for it
4. Result: Answer with path
```

### 5. "Review code quality"
```
1. Read: TRIGGER_RULES.md → Scenario E (Review)
2. Analyze: Document findings
3. Implement: Only Tier 1 (high impact, low effort)
4. Result: Quality improvements + documentation
```

---

## ✅ Never Skip These Steps

### Before Writing Code:
```
□ Layer 1: UNDERSTAND
  ├─ Read docs/technical/reference.md for domain
  ├─ Find 5-10 related files
  ├─ Trace data flow (input → output)
  └─ Understand patterns

□ Layer 2: VALIDATE
  ├─ Check: Single responsibility?
  ├─ Check: Data flow complete?
  ├─ Check: Breaking changes?
  └─ GO/NO-GO decision
```

### While Writing Code:
```
□ Layer 3: IMPLEMENT
  ├─ Follow patterns from similar files
  ├─ Use proper types/interfaces
  ├─ Build immediately: npm run build:frontend
  ├─ Fix any errors
  └─ NO broken builds allowed
```

### After Writing Code:
```
□ Layer 4: DOCUMENT (2-3 mins)
  ├─ Update docs/technical/reference.md (add entry)
  ├─ Update index.ts (add export)
  ├─ Update AGENTS.md (if structure changed)
  └─ Verify: No broken links

□ Layer 5: VERIFY
  ├─ Build passes? (0 errors)
  ├─ TypeScript clean? (0 errors)
  ├─ Related files work? (imports resolve)
  └─ Documentation complete?
  
  All YES? → Mark COMPLETE ✅
```

---

## 🎓 Pattern Reference

### Component Pattern (UI + Logic)
```
Location: components/[domain]/[Section]Section.vue
Size: 250-350 lines
Example: components/season/SeasonSection.vue

Structure:
  - Props interface (with types)
  - Emits definition
  - Setup/reactive state
  - Computed properties
  - Methods/handlers
  - Template (responsive)
```

### Page Pattern (Thin Wrapper)
```
Location: pages/[domain]/(mobile|web)/[Page]Page.vue
Size: 20-40 lines (NOT 50+)
Example: pages/season/mobile/MobileSeasonPage.vue

Structure:
  - Import composable with logic
  - Import Section component
  - Setup (no logic, just composition)
  - Template (render section + layout)
```

### Composable Pattern (Shared Logic)
```
Location: composables/use[Feature][Logic].ts
Size: 30-50 lines
Example: composables/useSeasonPageLogic.ts

Structure:
  - Import stores/router/utils
  - Define computed properties
  - Define event handlers
  - Return object with all exports
```

### SCSS Pattern (Foundation)
```
Location: styles/_[system]-base.scss
Content:
  - Variables (colors, spacing, breakpoints)
  - Base classes (grid, flex, responsive)
  - Dark mode support
  - Utilities

Example: styles/_section-base.scss (260 lines)
```

---

## 🚨 Red Flags - Stop and Fix These

### Code Red Flags
```
❌ File > 300 lines → Break into smaller pieces
❌ Function > 30 lines → Extract helpers
❌ Imports from 5+ services → Over-coupled
❌ No TypeScript types → Add interfaces
❌ CSS without dark mode → Add @media query
❌ Build errors → Fix before proceeding
```

### Process Red Flags
```
❌ Can't find related files → Incomplete Layer 1
❌ Not sure data flow works → Read more (Layer 2)
❌ "I'll document this later" → Document NOW
❌ "This is special case" → Probably not, use pattern
❌ Multiple breaks during work → Too much scope
```

### Documentation Red Flags
```
❌ docs/technical/reference.md not updated → Update now
❌ New file not in index.ts → Add export
❌ Related files scattered → Link them properly
❌ Out of sync references → Fix them
❌ "I'll catch this later" → Fix now
```

---

## 📊 Success Metrics

A task is DONE when:

```
✅ Code compiles (0 errors, 0 warnings)
✅ TypeScript strict mode passes (0 errors)
✅ Data flow is complete and valid
✅ Related files updated
✅ docs/technical/reference.md has entry
✅ index.ts files have exports
✅ Established patterns followed
✅ Comments explain WHY (not HOW)
✅ Dark mode ready
✅ Responsive design implemented
✅ Build verified
✅ Documentation complete
```

---

## 🔄 Daily Workflow

### Every Session (2 mins)
```
1. Read: AGENT_BOOT_PROTOCOL.md
2. Read: docs/technical/reference.md (for your domain)
3. Read: Relevant .github/instructions/ file for your task
4. Ready? → Start coding with Layer 1
```

### Every Code Change (variable)
```
1. Follow: 5-Layer Protocol
2. Total time: 10-45 mins depending on scope
3. Include: Layer 4 documentation (2-3 mins)
4. Verify: Layer 5 checklist (2 mins)
```

### End of Session (2 mins)
```
□ Build passes? YES
□ Docs updated? YES
□ No broken imports? YES
□ Can I trace all changes? YES

All YES? Mark COMPLETE ✅
All NO? Fix before leaving
```

---

## 🎯 Emergency Quick Reference

**Stuck? Use this:**

| Problem | Solution | Time |
|---------|----------|------|
| "Where do I start?" | AGENT_BOOT_PROTOCOL.md | 2 min |
| "How do I make this change?" | AGENT_AUTONOMOUS_PROTOCOL.md | 5 min |
| "When do I apply what?" | TRIGGER_RULES.md | 3 min |
| "How do I update docs?" | DOCUMENTATION_SYNC.md | 2 min |
| "Where is X?" | docs/technical/reference.md | <5 min |
| "I broke something" | Build output + grep | <5 min |
| "Build won't pass" | TypeScript errors → fix | <5 min |

---

## 📞 System Architecture Map

```
Autonomous Agent System
│
├─ Guidance Layer (How to work)
│  ├─ AGENT_AUTONOMOUS_PROTOCOL.md (5-Layer framework)
│  ├─ TRIGGER_RULES.md (When to apply what)
│  ├─ DOCUMENTATION_SYNC.md (Keep docs current)
│  └─ AGENT_BOOT_PROTOCOL.md (2-min onboarding)
│
├─ Authority Layer (Truth about workspace)
│  ├─ docs/technical/reference.md (All symbols mapped)
│  ├─ AGENTS.md (Workspace structure)
│  └─ This file (Quick reference)
│
├─ Code Layer (Patterns to follow)
│  ├─ components/ (UI + business logic)
│  ├─ composables/ (Shared logic)
│  ├─ pages/ (Page wrappers)
│  └─ styles/ (SCSS foundation)
│
└─ Execution Layer (Your work)
   ├─ Layer 1: UNDERSTAND
   ├─ Layer 2: VALIDATE
   ├─ Layer 3: IMPLEMENT
   ├─ Layer 4: DOCUMENT
   └─ Layer 5: VERIFY
```

---

## 🚀 Final Checklist Before Coding

```
□ Do I know what to do? (request type clear)
□ Do I know how to do it? (protocol understood)
□ Do I know where to find things? (docs read)
□ Do I know the patterns? (examples reviewed)
□ Am I ready to follow 5-Layer? (committed)
□ Is build currently passing? (baseline stable)

All YES? → You're ready! Start Layer 1: UNDERSTAND
Any NO? → Spend 5 more minutes reading above sections
```

---

## 📈 System Continuous Improvement

This system evolves. When you discover:

- **New pattern that works** → Update AGENT_AUTONOMOUS_PROTOCOL.md
- **New trigger scenario** → Update TRIGGER_RULES.md  
- **Better way to sync docs** → Update DOCUMENTATION_SYNC.md
- **New symbol/file to track** → Update docs/technical/reference.md
- **Structure change** → Update AGENTS.md

**Rule:** Documentation is living. Keep it current. You maintain this system.

---

## 🎓 Knowledge Retention

**These concepts should be second nature:**

1. **5-Layer Protocol** (can recite from memory)
2. **When to apply what** (automatic decision making)
3. **Document sync workflow** (2-3 minutes, automatic)
4. **Where to find things** (doc refs, AGENTS.md, patterns)
5. **Red flags** (stop and fix automatically)

**Goal:** Make good decisions autonomously. This system removes guesswork.

---

## 🌟 The Agent Mindset

Work like this:

```
CLARITY ← Read docs first, understand completely
         └─ Don't touch code until Layer 1 complete

VALIDATION ← Check logic before implementing
            └─ Catch issues early (Layer 2)

EXECUTION ← Code that works immediately
           └─ Follow patterns, build passes first try

DOCUMENTATION ← Update right away
               └─ 2-3 minutes, worth every second

VERIFICATION ← Verify completeness before leaving
              └─ 0 errors, all references updated
```

---

## ✨ Success Pattern

```
Every Good Task:
  ✅ Clear understanding (read docs)
  ✅ Validated approach (check layer 2)
  ✅ Working code (layer 3)
  ✅ Updated docs (layer 4)
  ✅ Verified complete (layer 5)

Result: Code + Documentation + References all in sync
Time: Usually 20-30 mins for typical change
Quality: Enterprise-grade, maintainable, traceable
```

---

**Version:** 1.0  
**Status:** Active  
**Updated:** Oct 24, 2025  
**Authority:** System Critical  

**Remember:** You're not just coding. You're building a system that future agents and developers can understand, maintain, and extend.

**Now go build something amazing! 🚀**
