AGENTS.md ยท git:20260112.09b90d6 ยท 2026-01-12 ยท sha256 1566bc552cc61924

AGENTS.md git:20260112.09b90d6A

Immutable. This exact content never changes and is served at /api/v1/blob/1566bc552cc61924.

# AGENTS.md

> 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:** [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. Run `python .agent/scripts/detect-environment.py` to update.

Check your environment:
```bash
python .agent/scripts/detect-environment.py
cat .agent/context/environment.json
```

---

## โšก Quick Commands

```bash
# 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

# Backup & Environment
python .agent/scripts/backup-memory.py
python .agent/scripts/detect-environment.py

# Interactive CLI (Recommended - No Python needed!)
bash .agent/scripts/agent-cli.sh        # Linux/Mac
powershell .agent/scripts/agent-cli.ps1 # Windows
```

---

## ๐Ÿ”„ Workflows (AI-Powered)

Tell your AI assistant to run these workflows:

| 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 |

> ๐Ÿ“ Workflow files: `.agent/workflows/`

---

## ๐Ÿ”ง Supported Editors

| Editor | Status |
|--------|--------|
| **VSCode + GitHub Copilot** | โœ… |
| **Cursor AI** | โœ… |
| **Kiro AI** | โœ… |
| **Windsurf Editor** | โœ… |
| **Antigravity (Gemini/Claude)** | โœ… |

---

## โš ๏ธ Critical Gotchas

> **Your knowledge base starts here!** Add gotchas as you discover them.

### Example Format:

```markdown
### [Short Title] ๐Ÿšจ

**Problem:** What went wrong
**Solution:** How to fix it

// Code example if applicable
```

### Your Gotchas:

<!-- Add your gotchas below as you discover them -->

---

## โœ… Patterns That Work

> Save patterns that work well in your project.

### Example Format:

```markdown
### [Pattern Name]

**When to use:** Condition
**How:** Implementation

// Code example
```

### Your Patterns:

<!-- Add your patterns below -->

---

## ๐Ÿ“ Architecture Decisions

> Document important decisions and why you made them.

### Example Format:

```markdown
### [Decision Title]

**Decision:** What was decided
**Reason:** Why this choice
**Date:** YYYY-MM-DD
```

### Your Decisions:

<!-- Add your decisions below -->

---

## ๐Ÿ“ Coding Conventions

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

### Language-Specific

| 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

### โš ๏ธ 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 to production

### ๐Ÿšซ Sensitive Files (No Access):
```
.env, .env.*, *.env
*.pem, *.key, id_rsa
config/database.php
credentials/*, secrets/*
```

---

## ๐Ÿ“‚ File Organization

> Keep your project clean!

| 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 |

### โŒ Don't create files in project root unless necessary!

---

## ๐Ÿง  Memory System

Your AI's knowledge is stored in:

```
.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
```

### Adding Knowledge

```bash
# Via script
python .agent/scripts/save-knowledge.py --category gotchas "Your learning here"

# Or create file manually
# .agent/memory/entries/gotchas/your-gotcha.md
```

---

## ๐Ÿ’ก Getting Started

1. **Run environment detection:**
   ```bash
   python .agent/scripts/detect-environment.py
   ```

2. **Try the interactive CLI:**
   ```bash
   bash .agent/scripts/agent-cli.sh
   ```

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

4. **Run maintenance weekly:**
   ```bash
   python .agent/scripts/validate-index.py --fix
   python .agent/scripts/backup-memory.py
   ```

---

## ๐Ÿ“š Learn More

- **README:** Project overview and installation
- **Workflows:** `.agent/workflows/` - Detailed workflow instructions
- **Scripts:** `.agent/scripts/README.md` - Script documentation

---

*Made with โค๏ธ by [andy-universal-agent-rules](https://github.com/andiupn/andy-universal-agent-rules)*