AGENTS.md ยท diff
git:20260111.dbe4845 to git:20260112.09b90d6
131 added, 1365 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# 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)*
+ > AI Agent Instructions for this project. Supported by GitHub Copilot, Cursor, Kiro, Windsurf, Antigravity.
+ *Stats: 0 entries (start building your knowledge base!)*
+
---
## ๐ 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.
+ **Project:** [Your Project Name]
+ **Purpose:** [What this project does]
+ **Stack:** Auto-detected in `.agent/context/environment.json`
---
## ๐ ๏ธ 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
+ > **NOTE:** Actual versions are auto-detected. Run `python .agent/scripts/detect-environment.py` to update.
+ Check your environment:
```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*
+ python .agent/scripts/detect-environment.py
+ cat .agent/context/environment.json
```
- ### 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>
+ # Knowledge Management (Core Features)
+ python .agent/scripts/save-knowledge.py --category gotchas "Your gotcha here"
+ python .agent/scripts/search-knowledge.py "search term"
+ python .agent/scripts/validate-index.py --fix
- # Environment
- python .agent/.agent/scripts/detect-environment.py
+ # Backup & Environment
+ python .agent/scripts/backup-memory.py
+ python .agent/scripts/detect-environment.py
- # Python Testing & Validation
- python .agent/context/python_capability_test.py
- python .agent/context/test_new_packages.py
+ # Interactive CLI (Recommended - No Python needed!)
+ bash .agent/scripts/agent-cli.sh # Linux/Mac
+ powershell .agent/scripts/agent-cli.ps1 # Windows
```
---
- ## ๐ 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 |
+ ## ๐ Workflows (AI-Powered)
- ### ๐ก Use Cases untuk AI Agent
+ Tell your AI assistant to run these workflows:
- ```python
- # Web Scraping
- from bs4 import BeautifulSoup
- soup = BeautifulSoup(html, 'html.parser')
- data = soup.find_all('div', class_='product')
+ | Workflow | Command | What It Does |
+ |----------|---------|--------------|
+ | **Maintenance** | "Run maintenance workflow" | Validate, backup, update environment |
+ | **Save from Chat** | "Save learnings from this chat" | Extract & save knowledge from session |
+ | **Search** | "Search for [topic]" | Find existing knowledge |
- # Data Analysis
- import pandas as pd
- df = pd.read_csv('data.csv')
- summary = df.describe()
+ > ๐ Workflow files: `.agent/workflows/`
- # Config Parsing
- import toml
- config = toml.load('config.toml')
+ ---
- # Image Processing
- from PIL import Image
- img = Image.open('photo.jpg')
- img.thumbnail((800, 600))
- ```
+ ## ๐ง Supported Editors
- > ๐ **Test Results:** `.agent/context/benchmark-results.txt`
+ | Editor | Status |
+ |--------|--------|
+ | **VSCode + GitHub Copilot** | โ
|
+ | **Cursor AI** | โ
|
+ | **Kiro AI** | โ
|
+ | **Windsurf Editor** | โ
|
+ | **Antigravity (Gemini/Claude)** | โ
|
---
- ## ๐ฏ 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 |
+ ## โ ๏ธ Critical Gotchas
- ### Quick Start per Project Type
+ > **Your knowledge base starts here!** Add gotchas as you discover them.
- ```bash
- # Web PHP
- php artisan serve # Laravel
- php -S localhost:8000 # Native
+ ### Example Format:
- # Web Node
- npm run dev # Vite/Next.js
+ ```markdown
+ ### [Short Title] ๐จ
- # Mobile Android
- flutter run -d android # Flutter
- flutter build apk --release # Build APK
+ **Problem:** What went wrong
+ **Solution:** How to fix it
- # Data/Reports
- python3 scripts/generate-report.py
+ // Code example if applicable
```
- ---
-
- ## ๐ 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 |
+ ### Your Gotchas:
- **Contoh Pelanggaran:**
- - โ Membuat `calculator.py` di root โ Pindah ke `test/python/`
- - โ Membuat `debug_log.txt` di root โ Pindah ke `test/temp/`
+ <!-- Add your gotchas below as you discover them -->
---
- ## ๐ 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
+ ## โ
Patterns That Work
- ### Python
- - Follow **PEP 8** style guide
- - Use **type hints** (Python 3.10+)
- - Use **f-strings** for formatting
+ > Save patterns that work well in your project.
- ### 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
+ ### Example Format:
```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')"
+ ### [Pattern Name]
- # โ
Multiline (Heredoc)
- python3 <<EOF
- import os
- print('hello')
- EOF
- ```
+ **When to use:** Condition
+ **How:** Implementation
- **Windows (PowerShell):**
- ```powershell
- # โ JANGAN - Multiline python -c akan STUCK!
- python -c "
- import os
- print('hello')
- "
+ // Code example
```
- # โ
BENAR - Buat file .py terlebih dahulu
- python .agent/context/temp_script.py
-
- # โ
ATAU - Single line dengan semicolon
- python -c "import os; print('hello')"
- ```
+ ### Your Patterns:
- > ๐ **Detail:** `.agent/memory/entries/gotchas/python-powershell-multiline-commands.md`
+ <!-- Add your patterns below -->
---
- ## โ ๏ธ Critical Gotchas
-
- > **Full database:** lihat `.agent/memory/entries/gotchas/`
-
- ### Database
+ ## ๐ Architecture Decisions
- #### Oracle Transaction Commit Bug ๐จ
- ```php
- // โ SALAH - Data hilang setelah 15 menit!
- $model->save();
+ > Document important decisions and why you made them.
- // โ
BENAR - Explicit COMMIT
- $transaction->commit();
- Yii::app()->db->getPdoInstance()->exec("COMMIT");
- ```
+ ### Example Format:
- #### MySQL Windows Connection
- ```php
- // โ SALAH - Bisa gagal di Windows
- 'host' => 'localhost'
+ ```markdown
+ ### [Decision Title]
- // โ
BENAR
- 'host' => '127.0.0.1'
+ **Decision:** What was decided
+ **Reason:** Why this choice
+ **Date:** YYYY-MM-DD
```
-
- ### 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
+ ### Your Decisions:
- # โ SALAH - Public (hanya jika diminta eksplisit)
- gh repo create NAMA_REPO --public --source=. --remote=origin --push
- ```
+ <!-- Add your decisions below -->
---
- ## ๐งญ 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.*
-
- | Requirement | Choose Language | Reason |
- | :--- | :--- | :--- |
- | **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`
+ ## ๐ Coding Conventions
- ### 4. Complete Tool Priority Matrix
- *Goal: Built-in AI FIRST, external tools sebagai SUPPORT.*
+ ### General
+ - Use **UTF-8** encoding for all files
+ - Use **4 spaces** for indentation (no tabs)
+ - Max line length: **120 characters**
- | 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 | - |
+ ### Language-Specific
- > **INGAT:** External tools (Gemini CLI, Jules, MCP) = **ASYNC/PARALLEL SUPPORT ONLY!**
- > Jangan block workflow primary AI dari code editor.
+ | Language | Style Guide | Key Rules |
+ |----------|-------------|-----------|
+ | **PHP** | PSR-12 | Type hints, docblocks |
+ | **JavaScript** | ESLint | const > let, async/await |
+ | **Python** | PEP 8 | Type hints, f-strings |
---
## ๐ Safety Rules
- ### Konfirmasi Wajib Sebelum:
- 1. **Delete operations:** `rm`, `del`, `DROP TABLE`, `TRUNCATE`
+ ### โ ๏ธ Always Confirm Before:
+ 1. **Delete operations:** `rm`, `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
+ 4. **External requests:** API calls to production
- ### File Sensitif (NO ACCESS):
+ ### ๐ซ Sensitive Files (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; }
- }
- ```
+ ## ๐ File Organization
- ### Accessibility Checklist (WCAG 2.1)
+ > Keep your project clean!
- | 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 |
+ | File Type | Location | Notes |
+ |-----------|----------|-------|
+ | **Tests** | `test/` | Unit tests, integration tests |
+ | **Scripts** | `scripts/` or `.agent/scripts/` | Automation tools |
+ | **Temp files** | `test/temp/` | Debug files (gitignored) |
+ | **Documentation** | `docs/` | Project docs |
- ```html
- <!-- โ
BENAR - Accessible Button -->
- <button
- aria-label="Close dialog"
- class="btn-close"
- tabindex="0">
- <span aria-hidden="true">×</span>
- </button>
- ```
+ ### โ Don't create files in project root unless necessary!
---
- ## ๐งช Testing Strategy
-
- > **๐ Test Location:** `test/` - Lihat [`test/README.md`](test/README.md) untuk panduan lengkap.
+ ## ๐ง Memory System
- ### Project Test Structure
+ Your AI's knowledge is stored in:
```
- 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)
+ .agent/
+ โโโ memory/
+ โ โโโ index.json # Knowledge index
+ โ โโโ entries/
+ โ โโโ gotchas/ # Bugs & how to avoid
+ โ โโโ patterns/ # Code patterns that work
+ โ โโโ decisions/ # Architecture decisions
+ โ โโโ context/ # Project information
+ โโโ context/
+ โ โโโ environment.json # Auto-detected environment
+ โโโ workflows/ # AI workflow definitions
```
- ### 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
+ ### Adding Knowledge
```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
+ # Via script
+ python .agent/scripts/save-knowledge.py --category gotchas "Your learning here"
- # Benchmarks
- php test/database/benchmarks/benchmark-mysql-access.php
+ # Or create file manually
+ # .agent/memory/entries/gotchas/your-gotcha.md
```
- ### ๐ค 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
+ ## ๐ก Getting Started
- ```
- 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
- ```
+ 1. **Run environment detection:**
+ ```bash
+ python .agent/scripts/detect-environment.py
+ ```
- ---
+ 2. **Try the interactive CLI:**
+ ```bash
+ bash .agent/scripts/agent-cli.sh
+ ```
- ## ๐ Related Files
+ 3. **Start saving knowledge!**
+ - When you solve a bug โ Save as gotcha
+ - When you find a good pattern โ Save as pattern
+ - When you make a decision โ Save as decision
- - [Memory Index](./.agent/memory/index.json)
- - [Project Context](./.agent/context/project-context.json)
- - [Session Init](./.agent/context/session-init.md)
+ 4. **Run maintenance weekly:**
+ ```bash
+ python .agent/scripts/validate-index.py --fix
+ python .agent/scripts/backup-memory.py
+ ```
---
- ## ๐ 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
+ ## ๐ Learn More
- **Detail lengkap:** Lihat `.agent/workflows/cara-simpan-pengetahuan-dari-chat.md`
+ - **README:** Project overview and installation
+ - **Workflows:** `.agent/workflows/` - Detailed workflow instructions
+ - **Scripts:** `.agent/scripts/README.md` - Script documentation
---
- *Last Updated: 2026-01-07*
- *Stats auto-sync: `python .agent/.agent/scripts/sync-agents-stats.py`*
+ *Made with โค๏ธ by [andy-universal-agent-rules](https://github.com/andiupn/andy-universal-agent-rules)*