AGENTS.md ยท git:20260107.0787a0b ยท 2026-01-07 ยท sha256 6df93b051e5406a7

AGENTS.md git:20260107.0787a0bA

Immutable. This exact content never changes and is served at /api/v1/blob/6df93b051e5406a7.

# AGENTS.md

> AI Agent Instructions for this project. Didukung oleh GitHub Copilot, Cursor, Kiro, Antigravity, dll.
*Stats: 237 entries (59 gotchas, 110 patterns, 25 decisions, 41 context)*

---

## ๐Ÿ“‹ Project Overview

**Project:** andy-universal-agent-rules  
**Purpose:** Testing & documentation AI agent rules system  
**Stack:** Multi-platform (PHP, Node.js, Python) - See `.agent/context/environment.json` for detected versions.

---

## ๐Ÿ› ๏ธ Tech Stack & Environment

> **NOTE:** Actual versions are auto-detected in `.agent/context/environment.json`.

- **Backend:** PHP 8.4+, Node.js 20.x+
- **Database:** MySQL (3306), Oracle 11g (1521)
- **Tools:** Laragon (Win), Valet/Homebrew (Mac), Native (Linux)
- **OS:** Cross-Platform (Windows/Linux/macOS)

---

## ๐Ÿ˜ Multi-PHP Version Support

> **Available PHP Versions (Linux):** 5.6, 7.2, 8.3, 8.4, 8.5

### Per-Project PHP Version

```bash
# Check default PHP
php -v

# Use specific version
php5.6 script.php
php7.2 artisan serve
php8.4 composer install

# Check all available
ls /usr/bin/php*
```

### Project-Specific Configuration

Untuk project yang membutuhkan PHP tertentu, gunakan:

| Method | File/Command | Example |
|--------|--------------|---------|
| **Shebang** | Script header | `#!/usr/bin/php7.2` |
| **Composer** | `composer.json` | `"php": "^7.2"` |
| **Apache** | `.htaccess` | `SetHandler application/x-httpd-php72` |

### Gotchas per Version

| PHP Version | Known Issues |
|-------------|--------------|
| **5.6** | No arrow functions, MySQL charset issues |
| **7.2** | No typed properties, limited union types |
| **8.3+** | Full modern PHP features |

> ๐Ÿ“š **Related:** `.agent/memory/entries/gotchas/php72-arrow-function.md`

---

## โšก Quick Commands

```bash
# PHP Project
composer install
php artisan serve

# Node.js Project
npm install
npm run dev

# Knowledge Management
python .agent/.agent/scripts/save-knowledge.py --category gotchas "message"
python .agent/.agent/scripts/search-knowledge.py "oracle commit"
python .agent/.agent/scripts/validate-index.py --fix

# Backup (auto-timestamp & compression)
python .agent/.agent/scripts/backup-memory.py             # Quick backup
python .agent/.agent/scripts/backup-memory.py --list       # List backups
python .agent/.agent/scripts/backup-memory.py --restore <file>

# Environment
python .agent/.agent/scripts/detect-environment.py

# Python Testing & Validation
python .agent/context/python_capability_test.py
python .agent/context/test_new_packages.py
```

---

## ๐Ÿ Python Capabilities

Agent memiliki Python 3.13.5 dengan **11 third-party packages** untuk berbagai keperluan:

### Web & Data
| Package            | Kegunaan      | Example Use Case                       |
|--------------------|---------------|----------------------------------------|
| **requests**       | HTTP requests | API calls, download files              |
| **beautifulsoup4** | HTML parsing  | Web scraping, extract data dari HTML   |
| **lxml**           | XML parsing   | Parse XML configs, RSS feeds           |

### Data Processing
| Package    | Kegunaan            | Example Use Case                      |
|------------|---------------------|---------------------------------------|
| **pandas** | Data analysis       | Olah CSV/Excel, statistical analysis |
| **numpy**  | Numerical computing | Matrix operations, calculations       |

### Config & Formats
| Package    | Kegunaan    | Example Use Case                       |
|------------|-------------|----------------------------------------|
| **pyyaml** | YAML parser | Parse docker-compose.yml, k8s configs  |
| **toml**   | TOML parser | Parse pyproject.toml, modern configs   |

### Development Tools
| Package    | Kegunaan          | Example Use Case                   |
|------------|-------------------|------------------------------------|
| **pytest** | Testing framework | Unit tests, integration tests      |
| **pylint** | Code linter       | Check code quality, find bugs      |
| **black**  | Code formatter    | Auto-format Python code            |
| **pillow** | Image processing  | Resize, convert, manipulate images |

### ๐Ÿ’ก Use Cases untuk AI Agent

```python
# Web Scraping
from bs4 import BeautifulSoup
soup = BeautifulSoup(html, 'html.parser')
data = soup.find_all('div', class_='product')

# Data Analysis
import pandas as pd
df = pd.read_csv('data.csv')
summary = df.describe()

# Config Parsing
import toml
config = toml.load('config.toml')

# Image Processing
from PIL import Image
img = Image.open('photo.jpg')
img.thumbnail((800, 600))
```

> ๐Ÿ“š **Test Results:** `.agent/context/benchmark-results.txt`

---

## ๐ŸŽฏ Multi-Tech Quick Reference

> Agent dapat bekerja dengan berbagai jenis project. Gunakan referensi ini untuk menentukan tools yang tepat.

| Project Type | Primary Tech | Tools/Framework | Memory Reference |
|--------------|--------------|-----------------|------------------|
| **Web App (PHP)** | PHP 5.6-8.5 | Laravel, Yii, Native | See Multi-PHP section |
| **Web App (Node)** | Node.js 24.x | Express, Next.js, Vite | `npm run dev` |
| **Mobile (Android)** | Flutter/Dart | Android Studio, Firebase | `flutter-development-guide.md` |
| **Desktop** | Electron/Flutter | Cross-platform | Flutter Desktop |
| **Reports/Data** | Python | pandas, numpy, matplotlib | `python-automation-capabilities.md` |
| **API/Backend** | PHP/Node | REST, GraphQL | Native frameworks |

### Quick Start per Project Type

```bash
# Web PHP
php artisan serve              # Laravel
php -S localhost:8000          # Native

# Web Node
npm run dev                    # Vite/Next.js

# Mobile Android
flutter run -d android         # Flutter
flutter build apk --release    # Build APK

# Data/Reports
python3 scripts/generate-report.py
```

---

## ๐Ÿ“‚ Strict File Organization Rules

> **๐Ÿšจ CRITICAL:** Agent **DILARANG KERAS** membuat file baru sembarangan di ROOT directory project (`/`).
> Lihat struktur lengkap di: `PROJECT_STRUCTURE.md`.

### ๐Ÿšซ Forbidden Actions
1.  **NO Root Clutter:** Jangan pernah buat file testing, script one-off, atau log di root.
2.  **NO Temp Files:** Jangan tinggalkan file `test.py`, `output.txt`, atau `temp.json` di root.

### โœ… Mandatory Locations
File baru harus ditempatkan sesuai kategorinya:

| Tipe File | Lokasi Wajib | Keterangan |
| :--- | :--- | :--- |
| **Python Tests** | `test/python/` | Unit testing, pytest script |
| **PHP Database Tests** | `test/database/<db_name>/` | MySQL/Oracle connection tests |
| **Utility Scripts** | `scripts/` | Automation tools |
| **Temporary Files** | `test/temp/` | File debug/sementara (tidak di-commit) |
| **Dokumentasi** | `test/<category>/README.md` | Doc untuk script spesifik |

**Contoh Pelanggaran:**
- โŒ Membuat `calculator.py` di root โ†’ Pindah ke `test/python/`
- โŒ Membuat `debug_log.txt` di root โ†’ Pindah ke `test/temp/`

---

## ๐Ÿ“ Coding Conventions

### General
- Use **UTF-8** encoding for all files
- Use **4 spaces** for indentation (no tabs)
- Max line length: **120 characters**

### PHP
- Follow **PSR-12** coding standard
- Use **type hints** for all function parameters and return types
- All classes must have **docblocks**

### JavaScript/Node.js
- Use **ESLint** with recommended rules
- Prefer **const** over let, avoid var
- Use **async/await** over callbacks

### Python
- Follow **PEP 8** style guide
- Use **type hints** (Python 3.10+)
- Use **f-strings** for formatting

### Markdown Tables
- **Align columns** dengan padding spaces agar rata
- **Bold** item penting di kolom pertama (e.g., `**PHP**`)
- **Tambah emoji status** jika ada state (โœ… โŒ โš ๏ธ)
- Separator `|---|` harus sama panjang dengan header

```markdown
# โŒ SALAH - Tidak rata, tidak bold
| Platform | Status |
|---|---|
| PHP | Done |

# โœ… BENAR - Rata, bold, emoji
| Platform   | Status | Notes            |
|------------|--------|------------------|
| **PHP**    | โœ…     | Production ready |
| **Python** | โš ๏ธ     | Needs testing    |
```

### โš ๏ธ Python Execution

**Linux/macOS (Bash):**
```bash
# โœ… Single line
python3 -c "import os; print('hello')"

# โœ… Multiline (Heredoc)
python3 <<EOF
import os
print('hello')
EOF
```

**Windows (PowerShell):**
```powershell
# โŒ JANGAN - Multiline python -c akan STUCK!
python -c "
import os
print('hello')
"
```

# โœ… BENAR - Buat file .py terlebih dahulu
python .agent/context/temp_script.py

# โœ… ATAU - Single line dengan semicolon
python -c "import os; print('hello')"
```

> ๐Ÿ“š **Detail:** `.agent/memory/entries/gotchas/python-powershell-multiline-commands.md`

---

## โš ๏ธ Critical Gotchas

> **Full database:** lihat `.agent/memory/entries/gotchas/`

### Database

#### Oracle Transaction Commit Bug ๐Ÿšจ
```php
// โŒ SALAH - Data hilang setelah 15 menit!
$model->save();

// โœ… BENAR - Explicit COMMIT
$transaction->commit();
Yii::app()->db->getPdoInstance()->exec("COMMIT");
```

#### MySQL Windows Connection
```php
// โŒ SALAH - Bisa gagal di Windows
'host' => 'localhost'

// โœ… BENAR
'host' => '127.0.0.1'
```


### Git
- โŒ JANGAN `git reset --hard` tanpa backup
- โŒ JANGAN force push ke `main` atau `develop`
- โœ… SELALU buat branch untuk fitur baru
- โœ… **SELALU buat GitHub repo sebagai PRIVATE** (user preference)

### GitHub Repository Creation
```bash
# โœ… BENAR - Private by default
gh repo create NAMA_REPO --private --source=. --remote=origin --push

# โŒ SALAH - Public (hanya jika diminta eksplisit)
gh repo create NAMA_REPO --public --source=. --remote=origin --push
```

---

## ๐Ÿงญ Best Practices: Tool Selection Strategy

Untuk kinerja optimal, gunakan decision tree berikut saat memilih tool.

### 1. Web Browsing Hierarchy
*Goal: Hemat waktu & resource.*

1. **Butuh info dari dokumentasi/artikel statis?** โ†’ Gunakan `read_url_content` (Cepat, Text-only).
2. **Butuh solusi error umum?** โ†’ Gunakan `search_web`.
3. **Butuh login, UI visual, atau SPA dynamic?** โ†’ Gunakan `browser_subagent`.
4. **Butuh mass automation/testing?** โ†’ Gunakan `Playwright MCP`.

> ๐Ÿ“š **Detail:** `.agent/memory/entries/patterns/browsing-tool-hierarchy.md`

### 2. Scripting Language: Python vs Node.js
*Goal: Efisiensi coding & performance.*

| Kebutuhan | Pilih Bahasa | Alasan |
| :--- | :--- | :--- |
| **Data Processing (CSV/Excel)** | **Python** ๐Ÿ | Pandas jauh lebih cepat & mudah |
| **Simple Automation** | **Python** ๐Ÿ | Standard library (OS, Sys) robust |
| **API Batch Operations** | **Node.js** ๐Ÿ“ฆ | Native Async/Await non-blocking |
| **Project Integration** | **Node.js** ๐Ÿ“ฆ | Reuse existing project logic |

> ๐Ÿ“š **Detail:** `.agent/memory/entries/decisions/python-vs-nodejs-scripting.md`

### 3. External AI Tools: Gemini CLI vs Jules
*Goal: Pilih tool AI paling tepat untuk setiap task.*

> **๐Ÿšจ IMPORTANT HIERARCHY:**
> 1. **PRIMARY:** Built-in AI dari Code Editor (Gemini 3 / Claude Anthropic) โ†’ **GUNAKAN INI DULU!**
> 2. **SUPPORT:** Gemini CLI, Jules CLI, MCP โ†’ Gunakan sebagai **ASYNC/PARALLEL** support saja
>
> External tools JANGAN mengganggu responsivitas primary AI. Gunakan hanya untuk task spesifik yang memerlukan!

#### Kapan Gunakan External Tools (Async/Parallel)?

| Kondisi | Tool Support | Mode | Alasan |
| :--- | :--- | :--- | :--- |
| **Task berat yang butuh waktu lama** | `jules new` | ๐Ÿ”„ Async | Jalan di background, tidak block editor |
| **Quota primary AI habis** | `gemini -p` | ๐Ÿ”„ Async | Backup saat limit tercapai |
| **Butuh akses ke service eksternal** | MCP Servers | ๐Ÿ”„ Parallel | GitHub, Firebase, database |
| **Generate file batch** | `jules new` | ๐Ÿ”„ Async | Multi-file tanpa ganggu workflow |
| **Debug error kompleks** | `gemini -p` | ๐Ÿ”„ Quick | Second opinion cepat |

#### โŒ JANGAN Gunakan External Tools Untuk:
- Task yang bisa dikerjakan langsung oleh built-in AI
- Operasi simple yang mengganggu flow kerja
- Menggantikan primary AI untuk task standar

#### Use Cases untuk External Tools (Async Only):

| Task Type | Tool Support | Mode | Kapan Digunakan |
| :--- | :--- | :--- | :--- |
| **Multi-file Generation** | `jules new` | ๐Ÿ”„ Async | Banyak file sekaligus |
| **Refactoring Massal** | `jules new` | ๐Ÿ”„ Async | Complex changes |
| **Documentation Full** | `jules new` | ๐Ÿ”„ Async | Multiple docs |
| **Code Migration** | `jules new` | ๐Ÿ”„ Async | Language conversion |
| **Second Opinion** | `gemini -p` | ๐Ÿ”„ Quick | Debug/verify |
| **Quota Backup** | `gemini -p` | ๐Ÿ”„ Quick | Primary AI limit |

**Decision Tree (UPDATED):**
```
Butuh bantuan AI?
โ”‚
โ”œโ”€ Bisa dikerjakan built-in AI (Gemini 3 / Claude)?
โ”‚   โ””โ”€ โœ… GUNAKAN BUILT-IN AI (PRIMARY) โ† DEFAULT!
โ”‚
โ”œโ”€ Task berat / multi-file / butuh waktu lama?
โ”‚   โ””โ”€ โœ… Gunakan: jules new "..." (ASYNC, jalan di background)
โ”‚
โ”œโ”€ Quota primary AI habis?
โ”‚   โ””โ”€ โœ… Fallback: gemini -p "..." (External CLI)
โ”‚
โ””โ”€ Butuh akses service eksternal (GitHub, DB, etc)?
    โ””โ”€ โœ… Gunakan: MCP Servers (PARALLEL)
```

**Quick Commands (Support Tools Only):**
```bash
# Jules (background async - tidak block editor)
jules new "Buat unit test untuk semua file di src/"
jules remote list --session
jules remote pull --session ID --apply

# Gemini CLI (fallback/second opinion)
gemini -p "Fix error: [paste error]"
```

> ๐Ÿ“š **Detail:** `.agent/memory/entries/patterns/gemini-cli-*.md`, `jules-cli-*.md`

### 4. Complete Tool Priority Matrix
*Goal: Built-in AI FIRST, external tools sebagai SUPPORT.*

| Task | 1st Choice (PRIMARY) | 2nd Choice (SUPPORT) | 3rd Choice |
| :--- | :--- | :--- | :--- |
| **Code Generation** | **Built-in AI** | Jules (async) | - |
| **Code Review** | **Built-in AI** | Gemini CLI | - |
| **Error Debugging** | **Built-in AI** | Gemini CLI | - |
| **Refactoring** | **Built-in AI** | Jules (async) | - |
| **Documentation** | **Built-in AI** | Jules (async) | - |
| **GitHub PR/Issues** | MCP GitHub | `gh` CLI | - |
| **Database Query** | PHP PDO/OCI8 | MCP DBeaver | CLI |
| **Redis Cache** | `redis-cli` | MCP Redis | - |
| **Browser Testing** | MCP Playwright | browser_subagent | - |

> **INGAT:** External tools (Gemini CLI, Jules, MCP) = **ASYNC/PARALLEL SUPPORT ONLY!**
> Jangan block workflow primary AI dari code editor.

---

## ๐Ÿ” Safety Rules

### Konfirmasi Wajib Sebelum:
1. **Delete operations:** `rm`, `del`, `DROP TABLE`, `TRUNCATE`
2. **Git destructive:** `reset --hard`, `clean -fd`, force push
3. **Package install:** `npm install`, `composer require`
4. **External requests:** API calls ke production

### File Sensitif (NO ACCESS):
```
.env, .env.*, *.env
*.pem, *.key, id_rsa
config/database.php
credentials/*, secrets/*
```

---

## ๐Ÿ”Œ MCP Servers (Available Tools)

Agent memiliki akses ke 6 MCP servers. Gunakan sesuai kebutuhan:

| MCP Server              | Fungsi                    | Kapan Digunakan              |
|-------------------------|---------------------------|------------------------------|
| **GitHub**              | Repo, PR, Issues          | Git operations yang kompleks |
| **Firebase**            | Auth, Firestore, Hosting  | Firebase projects            |
| **Cloud Run**           | GCP deployment            | Deploy ke Google Cloud       |
| **Dart**                | Flutter/Dart projects     | Mobile app development       |
| **Redis**               | Cache, key-value store    | Data caching & sessions      |
| **Sequential Thinking** | Problem solving           | Complex reasoning tasks      |

### Local Custom MCP Servers

> **STATUS:** โœ… All 8 servers PASSED validation (Verified 2026-01-02 via `validate-servers.js`)

Server-server ini dijalankan via `start-mcp.ps1` atau config editor:

| MCP Server          | Type    | Function        | Status (Test 2026-01-02) |
|---------------------|---------|-----------------|---------------------------|
| **DBeaver**         | Python  | Multi-DB Access | โœ… Ready (Found venv)     |
| **Oracle**          | Node.js | Oracle DB       | โœ… Ready                  |
| **Postgres**        | Node.js | Postgres DB     | โœ… Ready                  |
| **Chrome DevTools** | Node.js | Browser Debug   | โœ… Ready                  |
| **Playwright**      | Node.js | Automation      | โœ… Ready                  |
| **Context7**        | Node.js | Context Mgmt    | โœ… Ready                  |
| **Blogger**         | Node.js | Blog Management | โœ… Ready                  |
| **LangChain**       | Node.js | AI Workflows    | โœ… Ready                  |

### Quick Reference (Built-in)

> **โš ๏ธ WARNING:** redis-mcp-server failed testing ("Client closed"). Use `redis-cli` instead.

```bash
# GitHub - Get user info
mcp_github-mcp-server_get_me()

# Redis - Cache operations
# โŒ MCP Fails ("Client closed")
# mcp_redis_set({key: "key", value: "value"}) (DO NOT USE)

# โœ… Workaround: Use redis-cli
# 1. Setup Alias (PowerShell):
#    Set-Alias redis-cli "path/to/redis-cli.exe"
# 2. Run commands:
redis-cli SET mykey "Hello"
redis-cli GET mykey

# Firebase - Get environment
mcp_firebase-mcp-server_firebase_get_environment()
```

### MCP vs Direct Access

| Task            | Gunakan MCP              | Gunakan Direct              |
|-----------------|--------------------------|-----------------------------|
| Git operations  | โœ… Complex (PR, Issues)  | โœ… Simple (commit, push)    |
| Redis cache     | โœ… MCP Redis             | โŒ PHP Redis (slower)       |
| Database query  | โŒ                       | โœ… PHP PDO/OCI8 (faster)    |
| Firebase admin  | โœ… MCP Firebase          | -                           |

> ๐Ÿ“š **Detail:** `.agent/memory/entries/context/mcp-server-status-configuration.md`

---

## ๐Ÿค– Model-Specific Guidelines

> **CRITICAL:** MCP server compatibility berbeda antar AI model di Antigravity editor

### Claude Sonnet (Claude 3.5/4)

**MCP Compatibility:**

| MCP Server              | Status       | Reason                 |
|-------------------------|--------------|------------------------|
| **Redis**               | โœ… **WORKS** | Local, no external API |
| **Sequential Thinking** | โœ… **WORKS** | Internal processing    |
| **GitHub**              | โŒ **HANGS** | External API timeout   |
| **Firebase**            | โŒ **HANGS** | External API timeout   |
| **Cloud Run**           | โŒ **HANGS** | External API timeout   |
| **Dart**                | โŒ **HANGS** | External API timeout   |

**Recommended Usage:**

```markdown
โœ… SAFE untuk Claude Sonnet:
- Local file operations (view_file, write_to_file)
- Terminal commands (run_command)
- Redis MCP (caching, sessions)
- Sequential Thinking MCP (reasoning)

โŒ AVOID dengan Claude Sonnet:
- GitHub MCP โ†’ Use: git CLI, gh CLI
- Firebase MCP โ†’ Use: firebase CLI
- Cloud Run MCP โ†’ Use: gcloud CLI
- Dart MCP โ†’ Use: flutter CLI
```

### Gemini 3 (Gemini 2.0 Flash/Pro)

**MCP Compatibility:**

| MCP Server            | Status       |
|-----------------------|--------------|
| **ALL 6 MCP Servers** | โœ… **WORKS** |

**Recommended Usage:**

```markdown
โœ… SAFE untuk Gemini 3:
- Semua MCP servers available
- External API-based MCP (GitHub, Firebase, Cloud Run, Dart)
- Complex MCP workflows
- Multiple parallel MCP calls
```

### Model Selection Strategy

| Task Type               | Recommended Model | Reason                            |
|-------------------------|-------------------|-----------------------------------|
| **GitHub operations**   | โœ… Gemini 3       | GitHub MCP required               |
| **Firebase deployment** | โœ… Gemini 3       | Firebase MCP required             |
| **Cloud Run deploy**    | โœ… Gemini 3       | Cloud Run MCP required            |
| **Flutter development** | โœ… Gemini 3       | Dart MCP required                 |
| **Code analysis**       | โœ… Claude Sonnet  | Superior reasoning, no MCP needed |
| **Local development**   | โœ… Claude Sonnet  | File ops + Redis MCP sufficient   |
| **Caching operations**  | โœ… Both           | Redis MCP works on both           |

### Hybrid Workflow Pattern

Untuk workflow yang memerlukan both MCP dan code analysis:

```markdown
Step 1: Use Gemini 3
โ”œโ”€ Fetch data via GitHub MCP
โ”œโ”€ Deploy via Cloud Run MCP
โ””โ”€ Setup via Firebase MCP

Step 2: Switch to Claude Sonnet
โ”œโ”€ Analyze fetched data
โ”œโ”€ Code review & refactoring
โ””โ”€ Generate solutions

Step 3: Back to Gemini 3
โ””โ”€ Execute deployment via MCP
```

### CLI Alternatives (For Claude Sonnet)

Jika menggunakan Claude Sonnet, gunakan CLI tools sebagai pengganti MCP:

```bash
# Instead of GitHub MCP
git log -n 10
gh pr list
gh issue list

# Instead of Firebase MCP
firebase projects:list
firebase deploy

# Instead of Cloud Run MCP
gcloud run services list
gcloud run deploy

# Instead of Dart MCP
flutter devices
flutter run
flutter test
```

> ๐Ÿ“š **Testing Results:** Verified 2025-12-29 via systematic MCP testing

---

## ๐Ÿณ Docker MCP Infrastructure

> **INFO:** Beberapa MCP servers berjalan di Docker containers

### Docker MCP Toolkit (Beta)

> **STATUS:** โœ… Active (Verified 2026-01-02 via `docker mcp server list`)

Docker Desktop kini memiliki **MCP Toolkit** built-in yang berfungsi sebagai gateway untuk berbagai MCP servers.

**Command Gateway:**
```bash
docker mcp gateway run
```
Command ini menghubungkan MCP Client (Editor) dengan server-server yang dimanage oleh Docker.

**Installed Servers (Docker):**
*   **Playwright** (Enabled) - Browser automation
*   **GitHub** (Active Container: `ghcr.io/github/github-mcp-server`)

### GitHub MCP Server (Docker Container)

**Architecture:**
```
Docker Environment:
โ”œโ”€ Image: ghcr.io/github/github-mcp-server
โ”œโ”€ Instances: 2 containers (redundancy/load-balancing)
โ”‚   โ”œโ”€ Container 1: Primary instance
โ”‚   โ””โ”€ Container 2: Fallback instance
โ”œโ”€ Network: Internal Docker network
โ”œโ”€ Communication: MCP protocol (stdio/HTTP)
โ””โ”€ Version: 0.26.3 (as of 2025-12-29)
```

**Management Commands:**

```bash
# Check running MCP containers
docker ps | grep mcp

# Check all MCP containers (including stopped)
docker ps -a | grep mcp

# View container logs
docker logs <container_id> --tail 50

# Restart container if stuck
docker restart <container_id>

# Check container resource usage
docker stats <container_id>
```

**Troubleshooting:**

| Problem | Solution |
|---------|----------|
| MCP hangs | Check `docker ps -a`, restart if needed |
| No response | Check logs: `docker logs <id>` |
| Auth error | Verify GitHub token still valid |
| Container exited | `docker start <container_id>` |

---

## ๐Ÿ–ฅ๏ธ Editor-Specific MCP Support

> **CRITICAL:** MCP availability berbeda antar code editors

### Complete MCP Compatibility Matrix

| MCP Server              | Antigravity (Gemini) | Antigravity (Claude) | VSCode (Copilot) | Cursor   | Kiro                    | **Windsurf** |
|-------------------------|----------------------|----------------------|------------------|----------|-------------------------|--------------|
| **Redis**               | โœ… Works             | โœ… Works             | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โŒ CLI only  |
| **Sequential Thinking** | โœ… Works             | โœ… Works             | โŒ N/A           | โš ๏ธ Check | โœ… Works (auto-approve)  | โœ… 3 tools    |
| **GitHub**              | โœ… Works             | โŒ Hangs             | โœ… PR Tools      | โš ๏ธ Check | โœ… Works (git MCP)       | โŒ CLI only  |
| **Firebase**            | โœ… Works             | โŒ Hangs             | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โŒ CLI only  |
| **Cloud Run**           | โœ… Works             | โŒ Hangs             | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โŒ CLI only  |
| **Dart**                | โœ… Works             | โŒ Hangs             | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โŒ CLI only  |
| **MySQL**               | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (auto-approve)  | โŒ CLI only  |
| **SQLite**              | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (auto-approve)  | โŒ CLI only  |
| **Filesystem**          | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (auto-approve)  | โŒ CLI only  |
| **Chrome DevTools**     | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (manual)        | โŒ CLI only  |
| **Puppeteer**           | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (manual)        | โŒ CLI only  |
| **Lighthouse**          | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (auto-approve)  | โŒ CLI only  |
| **Memory**              | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (knowledge graph)| โŒ CLI only  |
| **Fetch**               | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โœ… Works (manual)        | โŒ CLI only  |
| **Figma**               | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โœ… 5 tools    |
| **Slack**               | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โœ… 7 tools    |
| **Stripe**              | โŒ N/A               | โŒ N/A               | โŒ N/A           | โš ๏ธ Check | โŒ Not configured       | โœ… 9 tools    |

**Legend:**
- โœ… Works = Fully functional
- โŒ Hangs = Will cause hang/timeout
- โŒ N/A = Not available/configured
- โš ๏ธ Check = Verify before using

---

### Editor-Specific Configuration

#### Antigravity Editor

**Full MCP Support dengan catatan model:**

```markdown
Antigravity + Gemini 3:
โ”œโ”€ โœ… ALL 6 MCP servers available
โ”œโ”€ โœ… External API MCP works (GitHub, Firebase, Cloud Run, Dart)
โ”œโ”€ โœ… Local MCP works (Redis, Sequential Thinking)
โ””โ”€ โœ… Recommended untuk MCP-heavy workflows

Antigravity + Claude Sonnet:
โ”œโ”€ โœ… Local MCP only (Redis, Sequential Thinking)
โ”œโ”€ โŒ External API MCP HANGS (GitHub, Firebase, Cloud Run, Dart)
โ”œโ”€ โœ… Use CLI alternatives (git, firebase, gcloud, flutter)
โ””โ”€ โœ… Recommended untuk code analysis (no MCP needed)
```

#### VSCode + GitHub Copilot

**Limited MCP - GitHub only:**

```markdown
Available Tools:
โ”œโ”€ โœ… github-pull-request_activePullRequest()
โ”œโ”€ โœ… github-pull-request_issue_fetch()
โ”œโ”€ โœ… github-pull-request_openPullRequest()
โ”œโ”€ โœ… github-pull-request_doSearch()
โ”œโ”€ โœ… Workspace management tools
โ””โ”€ โœ… API request tools

Not Available:
โ”œโ”€ โŒ Firebase MCP
โ”œโ”€ โŒ Cloud Run MCP
โ”œโ”€ โŒ Dart MCP
โ”œโ”€ โŒ Redis MCP
โ””โ”€ โŒ Sequential Thinking MCP
```

**Workaround:** Use terminal commands untuk access services

#### Cursor AI

**Flexible MCP Support dengan Agent Mode:**

```markdown
Cursor Capabilities:
โ”œโ”€ โœ… Agent Mode (default) - Combines Chat, Composer, and Agent
โ”œโ”€ โœ… Built-in tools (file ops, terminal, code completion)
โ”œโ”€ โœ… Rules system (.cursor/rules.md or .mdc files)
โ”œโ”€ โœ… Web search (automatic, no explicit command)
โ”œโ”€ โœ… /Generate Cursor Rules command (from conversation)
โ””โ”€ โš ๏ธ MCP servers (configurable via workspace settings)

MCP Configuration:
โ”œโ”€ โš ๏ธ Status depends on user workspace setup
โ”œโ”€ โš ๏ธ Requires manual configuration in Cursor settings
โ”œโ”€ โš ๏ธ Test each MCP before heavy use
โ””โ”€ โœ… CLI fallbacks available when MCP unavailable

Workflow Priority:
1. Built-in Cursor tools (primary)
2. Project Rules (.cursor/rules.md)
3. MCP Servers (if configured)
4. CLI fallbacks (backup)
```

**Configuration:**
- Rules: `.cursor/rules.md` (enhanced) or `.cursor/rules/*.mdc` files
- MCP: Cursor Settings โ†’ MCP Servers (workspace-specific)
- User Rules: Global settings (applied to all projects)
- Agent Mode: Default since Feb 2025 update

#### Kiro AI

**Full MCP Support dengan 18 servers (12 active):**

```markdown
Kiro Capabilities:
โ”œโ”€ โœ… 18 MCP servers total (12 active, 6 disabled)
โ”œโ”€ โœ… Built-in tools (file ops, terminal, diagnostics)
โ”œโ”€ โœ… Kiro Powers (subagents: context-gatherer, general-task-execution)
โ”œโ”€ โœ… Auto-approve untuk read operations
โ””โ”€ โœ… Recommended untuk multi-tool workflows

Active MCP Servers (12):
โ”œโ”€ Database: mysql, sqlite
โ”œโ”€ Automation: git, filesystem, chrome-devtools, puppeteer
โ”œโ”€ Analysis: lighthouse, sequential-thinking, memory
โ”œโ”€ Network: fetch
โ””โ”€ Utility: time, everything

Disabled Servers (6):
โ”œโ”€ aws, sentry, jira, figma (need credentials)
โ””โ”€ youtube-transcript, playwright (package not found)

Workflow Priority:
1. Built-in Kiro tools (primary)
2. Kiro Powers (when available)
3. MCP Servers (parallel execution)
4. CLI fallbacks (backup)
```

**Steering Files (Always Included):**
- `structure.md` - File organization rules
- `tech.md` - Tech stack & capabilities
- `efficiency.md` - Efficiency guidelines
- `product.md`, `security.md` - Additional guidelines

**Configuration:**
- MCP config: `.kiro/settings/mcp.json` (workspace-specific)
- Rules: `.kiro/rules.md` (enhanced with 18 MCP servers)
- Steering: `.kiro/steering/*.md` (auto-included)

---

#### Windsurf Editor

**Advanced AI dengan Cascade & Memories:**

```markdown
Windsurf Capabilities:
โ”œโ”€ โœ… Cascade AI (GPT-5.1) - Advanced reasoning
โ”œโ”€ โœ… Memories (48h learning) - Pattern recognition
โ”œโ”€ โœ… MCP Support (21 tools) - Figma, Slack, Stripe
โ”œโ”€ โœ… Drag & Drop Images - Design-to-code
โ”œโ”€ โœ… Terminal Command - Natural language CLI
โ”œโ”€ โœ… Lint Fixing - Auto-fix 60% success rate
โ””โ”€ โœ… Continue My Work - Session persistence

MCP Tools Available:
โ”œโ”€ Design: Figma (5 tools)
โ”œโ”€ Communication: Slack (7 tools)  
โ”œโ”€ Payment: Stripe (9 tools)
โ””โ”€ Reasoning: Sequential Thinking (3 tools)

Workflow Priority:
1. Cascade AI (primary) - Built-in GPT-5.1
2. Memories (context) - Learned patterns
3. MCP Tools (21 available) - Third-party integrations
4. CLI Fallback (backup) - Manual operations
```

**Configuration:**
- Rules: `.windsurf/rules.md` (editor-specific)
- MCP: Windsurf Settings โ†’ MCP Servers (one-click setup)
- Memories: Auto-learn after 48h analysis
- AI Model: Cascade (GPT-5.1/GPT-5.1-Codex)

**Unique Features:**
- **Memories Learning:** 78% pattern consistency for 50K+ line projects
- **Lint Fixing:** Real-time ESLint/Prettier auto-fix
- **Drag & Drop:** Generate React from images/Figma
- **Turbo Mode:** Auto-execute terminal commands

---

### ๐ŸŽฏ Quick Decision Guide

**"Which model/editor should I use for this task?"**

| Task                      | Best Choice          | Reason                               |
|---------------------------|----------------------|--------------------------------------|
| **GitHub PR operations**  | Antigravity + Gemini | Full GitHub MCP                      |
| **Firebase deployment**   | Antigravity + Gemini | Firebase MCP required                |
| **Cloud Run deploy**      | Antigravity + Gemini | Cloud Run MCP required               |
| **Flutter development**   | Antigravity + Gemini | Dart MCP required                    |
| **Code analysis/review**  | Any Claude model     | Superior reasoning                   |
| **Local caching**         | Any model            | Redis MCP works everywhere           |
| **Complex reasoning**     | Any model            | Sequential Thinking works everywhere |
| **Simple git operations** | Any editor           | `git` CLI sufficient                 |
| **Quick PR review**       | VSCode Copilot       | Built-in PR tools                    |
| **Multi-file refactoring** | โœ… Cursor            | Composer mode for batch changes      |
| **Code completion**       | โœ… Cursor            | Superior inline editing & autocomplete|
| **Rules from conversation** | โœ… Cursor         | /Generate Cursor Rules command       |
| **Multi-tool workflows**  | โœ… Kiro              | 12 active MCP servers, built-in tools |
| **Database operations**  | โœ… Kiro              | MySQL/SQLite MCP with auto-approve   |
| **Browser automation**   | โœ… Kiro              | Chrome DevTools + Puppeteer MCP      |
| **Performance audit**    | โœ… Kiro              | Lighthouse MCP (auto-approve)        |
| **Knowledge graph**      | โœ… Kiro              | Memory MCP for context management    |
| **Design-to-code**       | โœ… Windsurf          | Figma MCP + Drag & Drop Images       |
| **Payment integration**   | โœ… Windsurf          | Stripe MCP (9 tools)                 |
| **Team notifications**    | โœ… Windsurf          | Slack MCP (7 tools)                  |
| **Pattern learning**     | โœ… Windsurf          | Memories feature (48h learning)     |
| **Natural language CLI** | โœ… Windsurf          | Terminal Command (80% success)       |

---

### ๐Ÿ”„ MCP Fallback Strategy

Jika MCP tidak tersedia atau hang, gunakan CLI alternatives:

```bash
# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
# FALLBACK: CLI Alternatives untuk MCP
# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

# โ”€โ”€ GitHub (instead of GitHub MCP) โ”€โ”€
git status
git log -n 10
git push origin main
gh pr list
gh pr create
gh issue list

# โ”€โ”€ Firebase (instead of Firebase MCP) โ”€โ”€
firebase login --reauth
firebase projects:list
firebase deploy
firebase deploy --only hosting
firebase deploy --only functions

# โ”€โ”€ Cloud Run (instead of Cloud Run MCP) โ”€โ”€
gcloud auth login
gcloud projects list
gcloud run services list
gcloud run deploy SERVICE_NAME --source .

# โ”€โ”€ Dart/Flutter (instead of Dart MCP) โ”€โ”€
flutter doctor
flutter devices
flutter run
flutter run -d chrome
flutter build apk
flutter test

# โ”€โ”€ Redis (if Redis MCP unavailable) โ”€โ”€
redis-cli ping
redis-cli SET key "value"
redis-cli GET key
redis-cli KEYS "pattern:*"
```

---

### โš ๏ธ Pre-Session MCP Check Protocol

**Sebelum mulai session baru, AI agent HARUS:**

```markdown
1. [ ] Identify current editor (Antigravity/VSCode/Cursor/Kiro)
2. [ ] Identify active model (Gemini/Claude/GPT)
3. [ ] Check MCP compatibility matrix above
4. [ ] For task requiring external MCP:
       - If Claude: Use CLI fallback or switch to Gemini
       - If Gemini: Proceed with MCP
       - If unsure: Test simple MCP call first (Redis SET/GET)
5. [ ] Warn user if MCP incompatibility detected
```

**Example Warning Message:**

```markdown
โš ๏ธ **MCP Compatibility Notice**

Anda menggunakan Claude Sonnet. Task ini memerlukan GitHub MCP 
yang tidak compatible dengan Claude.

**Options:**
1. Switch ke Gemini 3 model
2. Saya gunakan `git` CLI sebagai alternatif

Pilih opsi yang diinginkan?
```

---

## โšก Database Performance

> Berdasarkan benchmark 2026-01-04

### Hasil Benchmark

| Database   | PHP Library  | CLI Tool       | Difference      |
|------------|--------------|----------------|-----------------|
| **MySQL**  | PDO: 3.20ms  | mysql: ~75ms   | **23x faster**  |
| **Oracle** | OCI8: 2.25ms | SQLPlus: 355ms | **157x faster** |

### Guidelines

**โœ… SELALU gunakan PHP libraries untuk aplikasi:**
```php
// MySQL - PDO (recommended)
$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=db', 'root', '');

// Oracle - OCI8
$conn = oci_connect('user', 'pass', '//localhost:1521/ORCL');
```

**โš ๏ธ CLI tools hanya untuk admin tasks:**
```bash
# OK untuk interactive/one-off
mysql -h 127.0.0.1 -u root
sqlplus user/pass@ORCL
```

**โŒ JANGAN gunakan CLI dalam loops:**
```php
// SALAH - 157x lebih lambat!
for ($i = 0; $i < 100; $i++) {
    exec("sqlplus user/pass@ORCL @query.sql");
}
```

### Connection Info

| Database | Host      | Port | User    | Notes                                    |
|----------|-----------|------|---------|------------------------------------------|
| MySQL    | 127.0.0.1 | 3306 | root    | Password kosong                          |
| Oracle   | localhost | 1521 | testphp | Password: testphp123                     |

> ๐Ÿ“š **Detail:** `.agent/memory/entries/decisions/php-libraries-over-cli-tools.md`

---

## ๐ŸŽจ Web Apps UI/UX Guidelines

### Design Principles
- **Mobile-first** approach untuk semua development
- **Accessibility** compliance (WCAG 2.1)
- **Performance-oriented** design (Core Web Vitals)
- **Consistent** design system dengan reusable components

### CSS Best Practices

| Guideline | Example |
|-----------|---------|
| Use CSS Variables | `var(--primary-color)` |
| BEM Naming | `.card__title--active` |
| Mobile-first queries | `@media (min-width: 768px)` |
| Prefer flexbox/grid | Hindari float layouts |

```css
/* โœ… BENAR - CSS Variables + Modern Layout */
:root {
    --primary: #3b82f6;
    --radius: 0.5rem;
}
.card {
    display: grid;
    gap: 1rem;
    border-radius: var(--radius);
}
```

### JavaScript Guidelines
- **ES6+** features (arrow functions, destructuring, modules)
- **async/await** over callbacks
- **Event delegation** untuk dynamic content
- **Lazy loading** untuk performance

```javascript
// โœ… BENAR - Modern JS Pattern
const loadData = async () => {
    const { data } = await fetch('/api/items').then(r => r.json());
    return data;
};
```

### UI Framework Recommendations

| Project Type | Recommended Framework |
|--------------|----------------------|
| Simple landing | Vanilla CSS + JS |
| Medium webapp | Bootstrap 5 / TailwindCSS |
| Complex SPA | React / Vue + CSS-in-JS |
| E-commerce | Next.js / Nuxt.js |

### Browser Testing Checklist
- [ ] Chrome, Firefox, Safari, Edge
- [ ] Mobile: iOS Safari, Chrome Android
- [ ] Lighthouse score โ‰ฅ 90
- [ ] No console errors

---

## ๐Ÿš€ Node.js/PM2 Service Management

> Untuk project microservices dengan Kafka, Express, atau API services

### PM2 Quick Commands

```bash
# Start services
pm2 start ecosystem.config.js
pm2 start ecosystem.config.js --only service-name

# Stop/Restart
pm2 stop service-name
pm2 restart all
pm2 reload service-name  # Zero-downtime reload

# Monitoring
pm2 list
pm2 monit
pm2 logs
pm2 logs service-name --lines 100
pm2 logs --err --lines 50  # Errors only

# Persist & Auto-start
pm2 save
pm2 startup
```

### โš ๏ธ Critical: Kafka Consumer Rules

```javascript
// ecosystem.config.js
{
  name: 'kafka-consumer',
  instances: 1,       // โš ๏ธ NEVER > 1! Causes message duplication
  exec_mode: 'fork',  // NOT cluster!
}
```

**Why?** Multiple Kafka consumers in same group cause message duplication due to partition rebalancing.

### API Instances (Can Scale)

```javascript
{
  name: 'api-server',
  instances: 2,       // Can scale as needed
  exec_mode: 'cluster' // Load balanced
}
```

### Portable Deployment Checklist

```
โœ… WAJIB COPY:
โ”œโ”€โ”€ package.json, package-lock.json
โ”œโ”€โ”€ .env.example (NOT .env!)
โ”œโ”€โ”€ ecosystem.config.js
โ”œโ”€โ”€ src/**/*.js
โ””โ”€โ”€ database/schema.sql

โŒ JANGAN COPY:
โ”œโ”€โ”€ node_modules/ (npm install ulang)
โ”œโ”€โ”€ .env (buat baru di server)
โ”œโ”€โ”€ logs/
โ””โ”€โ”€ .git/
```

> ๐Ÿ“š **Detail:** `.agent/memory/entries/patterns/pm2-ecosystem-startup-pattern.md`

---

## ๐Ÿ“ฑ Mobile Development (Android/Flutter)

### Flutter Environment
- **Flutter SDK:** Path verified in `.agent/context/environment.json`
- **Android Studio:** Emulator & SDK Support
- **MCP Server:** `dart-mcp-server` available

### Quick Commands

```bash
# Create new project
flutter create my_app

# Run on device/emulator
flutter run

# Build release APK
flutter build apk --release

# Analyze & format code
flutter analyze
dart format .

# Run tests
flutter test
```

### Flutter Best Practices

| Practice | Description |
|----------|-------------|
| **const constructors** | Use const untuk widget statis |
| **State management** | BLoC/Provider/Riverpod |
| **Null safety** | Handle null dengan `?` dan `!` |
| **Widget extraction** | Split ke files terpisah |

```dart
// โœ… BENAR - Const + Clean Structure
class ProductCard extends StatelessWidget {
  const ProductCard({super.key, required this.product});
  final Product product;
  
  @override
  Widget build(BuildContext context) {
    return const Card(child: ...);
  }
}
```

### Project Structure

```
lib/
โ”œโ”€โ”€ main.dart
โ”œโ”€โ”€ models/          # Data models
โ”œโ”€โ”€ screens/         # Full page widgets
โ”œโ”€โ”€ widgets/         # Reusable components
โ”œโ”€โ”€ services/        # API, database
โ””โ”€โ”€ utils/           # Helpers, constants
```

### MCP Dart Tools Available

| Tool | Fungsi |
|------|--------|
| `launch_app` | Launch Flutter app |
| `hot_reload` | Apply code changes |
| `hot_restart` | Restart app state |
| `get_widget_tree` | Inspect widget hierarchy |
| `run_tests` | Execute Flutter tests |
| `flutter_driver` | UI automation |

---

## ๐Ÿ“ Responsive Design & Accessibility

### Breakpoints (Bootstrap 5)

| Breakpoint | Size | Target Device |
|------------|------|---------------|
| xs | <576px | Mobile portrait |
| sm | โ‰ฅ576px | Mobile landscape |
| md | โ‰ฅ768px | Tablet |
| lg | โ‰ฅ992px | Desktop |
| xl | โ‰ฅ1200px | Large desktop |
| xxl | โ‰ฅ1400px | Extra large |

### Media Query Pattern

```css
/* Mobile first - base styles untuk mobile */
.container { padding: 1rem; }

/* Tablet ke atas */
@media (min-width: 768px) {
    .container { padding: 2rem; }
}

/* Desktop ke atas */
@media (min-width: 1024px) {
    .container { max-width: 1200px; }
}
```

### Accessibility Checklist (WCAG 2.1)

| Requirement | Implementation |
|-------------|----------------|
| **Alt text** | Semua `<img>` punya `alt` |
| **Color contrast** | Ratio โ‰ฅ 4.5:1 |
| **Keyboard nav** | `tabindex`, focus states |
| **ARIA labels** | Interactive elements |
| **Focus indicator** | Visible `:focus` styles |

```html
<!-- โœ… BENAR - Accessible Button -->
<button 
    aria-label="Close dialog"
    class="btn-close"
    tabindex="0">
    <span aria-hidden="true">&times;</span>
</button>
```

---

## ๐Ÿงช Testing Strategy

> **๐Ÿ“ Test Location:** `test/` - Lihat [`test/README.md`](test/README.md) untuk panduan lengkap.

### Project Test Structure

```
test/
โ”œโ”€โ”€ database/       โ† Database testing (Oracle, MySQL, benchmarks)
โ”œโ”€โ”€ server/         โ† Server-side testing (PHP, Redis, HTTP)
โ”œโ”€โ”€ python/         โ† Python testing (pytest, unit tests)
โ””โ”€โ”€ temp/           โ† Temporary test files (not committed)
```

### Testing Levels

| Type | Tools | Location | When to Run |
|------|-------|----------|-------------|
| **Unit** | pytest, PHPUnit | `test/python/`, `test/server/` | Setiap commit |
| **Database** | PHP PDO/OCI8 | `test/database/` | Sebelum deploy |
| **Integration** | Postman, Cypress | - | Setiap PR |
| **E2E** | Playwright, Selenium | - | Before release |

### Quick Test Commands

```bash
# Python Tests
cd test/python && pytest -v

# Database Tests
php test/database/oracle/test-oracle-final.php
php test/database/mysql/test-mysql-connection.php

# Server Tests
php test/server/redis-test.php
php test/server/mysql-test.php

# Benchmarks
php test/database/benchmarks/benchmark-mysql-access.php
```

### ๐Ÿค– AI Agent Test Guidelines

1. **Python tests** โ†’ `test/python/test_*.py`
2. **PHP database tests** โ†’ `test/database/<db_name>/`
3. **PHP server tests** โ†’ `test/server/`
4. **Temporary files** โ†’ `test/temp/` (auto-cleanup)

> โš ๏ธ **JANGAN buat test files di ROOT!** Selalu gunakan struktur `test/` di atas.

---

## ๐Ÿž Debugging & Troubleshooting Patterns

> **NEW:** Comprehensive debugging guides for all platforms.

| Platform | Pattern File | Key Capabilities |
|----------|--------------|------------------|
| **Python** | [python-debug-workflow.md](.agent/memory/entries/patterns/python-debug-workflow.md) | `pdb`, logging, traceback, automation |
| **PowerShell** | [powershell-debug-pattern.md](.agent/memory/entries/patterns/powershell-debug-pattern.md) | Error handling, strict mode, script debug |
| **Browser** | [browser-devtools-integration.md](.agent/memory/entries/patterns/browser-devtools-integration.md) | Console logs, network inspection, overlays |
| **Node.js** | [nodejs-debug-pattern.md](.agent/memory/entries/patterns/nodejs-debug-pattern.md) | `--inspect`, PM2 logs, async error handling |

### Quick Debug Checklist

1. **Python**: Gunakan `python script.py` jangan `python -c` multiline.
2. **PowerShell**: Set `$ErrorActionPreference = "Stop"` di awal script.
3. **Browser**: Gunakan `browser_subagent` untuk capture console logs.
4. **Node.js**: Cek `pm2 logs --err` untuk production errors.

---

## ๐Ÿง  Memory System

Agent memiliki akses ke knowledge base di `.agent/memory/`.

### Available Scripts:

| Script | Fungsi |
|--------|--------|
| `save-knowledge.py` | Simpan knowledge baru (dengan duplicate detection) |
| `search-knowledge.py` | Cari knowledge by keyword/tag/category |
| `validate-index.py` | Validasi & fix index consistency |
| `backup-memory.py` | Backup/restore (ZIP compressed, auto-timestamp) |
| `detect-environment.py` | Deteksi environment project |
| `sync-agents-stats.py` | Auto-sync statistics di AGENTS.md |


### Kategori Memory:
- **gotchas/** - Production bugs & fixes (๐Ÿšจ CRITICAL)
- **patterns/** - Code patterns yang works
- **decisions/** - Architectural decisions
- **context/** - Project guides & references

### Cari Knowledge:
- **Via Script:** `python .agent/.agent/scripts/search-knowledge.py "keyword"`
- **Manual:** Cek `.agent/memory/index.json` untuk daftar semua entries

### Backup:
Semua backup tersimpan di `_backups/` dengan format `memory_backup_YYYYMMDD_HHMMSS.zip`.

---

## ๐Ÿ“ Project Structure

```
project-root/
โ”œโ”€โ”€ AGENTS.md              โ† Entry point (You are here)
โ”œโ”€โ”€ .github/
โ”‚   โ””โ”€โ”€ copilot-instructions.md  โ† GitHub Copilot support
โ”œโ”€โ”€ .cursor/
โ”‚   โ””โ”€โ”€ rules.md           โ† Cursor AI support
โ”œโ”€โ”€ .kiro/
โ”‚   โ””โ”€โ”€ rules.md           โ† Kiro AI support
โ”œโ”€โ”€ .agent/
โ”‚   โ”œโ”€โ”€ memory/            โ† Knowledge persistence
โ”‚   โ”‚   โ”œโ”€โ”€ index.json     โ† Searchable index
โ”‚   โ”‚   โ””โ”€โ”€ entries/
โ”‚   โ”‚       โ”œโ”€โ”€ gotchas/   โ† Critical bugs
โ”‚   โ”‚       โ”œโ”€โ”€ patterns/  โ† Code patterns
โ”‚   โ”‚       โ”œโ”€โ”€ decisions/ โ† Arch decisions
โ”‚   โ”‚       โ””โ”€โ”€ context/   โ† Project guides
โ”‚   โ”œโ”€โ”€ context/           โ† Environment detection
โ”‚   โ””โ”€โ”€ workflows/         โ† AI workflows
โ”œโ”€โ”€ scripts/               โ† Automation scripts
โ””โ”€โ”€ _backups/              โ† Auto-compressed backups
```

---

## ๐Ÿ”— Related Files

- [Memory Index](./.agent/memory/index.json)
- [Project Context](./.agent/context/project-context.json)
- [Session Init](./.agent/context/session-init.md)

---

## ๐Ÿš€ Session Initialization Protocol

**UNTUK AI AGENT:** Saat membuka project ini, WAJIB baca file-file berikut:

### 1. Critical Files (MUST READ!)
```
.agent/context/session-init.md       โ† Initialization protocol
.agent/context/project-context.json  โ† Project info
.agent/memory/index.json             โ† Knowledge index
.agent/memory/entries/gotchas/*.md   โ† Critical gotchas
```

### 2. Auto-Load Behavior

AI agent akan otomatis:
- โœ… Load project context & environment
- โœ… Load semua critical gotchas
- โœ… Load top 5 patterns yang sering dipakai
- โœ… Siap bekerja tanpa perlu dijelaskan ulang

### 3. End of Session Protocol

Sebelum session berakhir:
- โœ… Simpan semua learnings baru
- โœ… Update memory index
- โœ… Buat summary report

**Detail lengkap:** Lihat `.agent/workflows/cara-simpan-pengetahuan-dari-chat.md`

---

*Last Updated: 2026-01-07*  
*Stats auto-sync: `python .agent/.agent/scripts/sync-agents-stats.py`*