# Antigravity Agent Kit — Windsurf Rules

> This workspace has an AI toolkit at `.agent/`. Read `.agent/ARCHITECTURE.md` first.

## System Overview

- **Agents** (`.agent/agents/*.md`): Specialist AI personas — read the matching agent file before responding
- **Skills** (`.agent/skills/*/SKILL.md`): Domain knowledge modules — read selectively based on task
- **Workflows** (`.agent/workflows/*.md`): Step-by-step procedures for slash commands

## Agent Routing (MANDATORY)

Before writing any code:
1. Identify the domain (Frontend, Backend, Security, etc.)
2. Read the matching agent file from `.agent/agents/`
3. Load skills listed in the agent's `skills:` frontmatter field
4. Apply agent rules when generating code

Quick reference:
- Web UI → `frontend-specialist.md` (skills: frontend-design, react-best-practices)
- API/Backend → `backend-specialist.md` (skills: api-patterns, nodejs-best-practices)
- Database → `database-architect.md` (skills: database-design)
- Mobile → `mobile-developer.md` (skills: mobile-design)
- Security → `security-auditor.md` (skills: vulnerability-scanner)
- Testing → `test-engineer.md` (skills: testing-patterns, webapp-testing)
- Debugging → `debugger.md` (skills: systematic-debugging)
- Planning → `project-planner.md` (skills: brainstorming, plan-writing)
- Complex/multi-domain → `orchestrator.md` (skills: parallel-agents)

## Skill Loading

Read `SKILL.md` inside the skill folder. Only read sections relevant to current task.
Global mandatory: `.agent/skills/clean-code/SKILL.md` — applies to ALL code.

Skill structure:
```
.agent/skills/{name}/
├── SKILL.md        # Main instructions (read first)
├── scripts/        # Validation scripts (optional)
├── references/     # Templates (optional)
```

## Workflow Annotations

When reading `.agent/workflows/*.md`, recognize these markers:
- `$ARGUMENTS` — placeholder for user input after the slash command
- `// turbo` — next step can auto-execute without confirmation
- `// turbo-all` — all subsequent steps in this section can auto-execute

## Rules Priority

P0 (this file / GEMINI.md) > P1 (agent .md) > P2 (skill SKILL.md)

## Code Standards

- ALL code follows `clean-code` skill rules
- English for code/comments/variables; respond in user's language
- Check file dependencies before modifying; update all affected files together

## Paths

```
.agent/
├── ARCHITECTURE.md     # READ FIRST
├── agents/             # 20 agents
├── skills/             # 38 skills
├── workflows/          # 16 workflows
├── rules/              # IDE instruction files
└── scripts/            # Validation scripts
```

## 🛡️ Auto-Protection (Always Active)

**Scout Block — NEVER read:** `node_modules/`, `.git/`, `dist/`, `build/`, `out/`, `bin/`, `obj/`, `packages/`, `.vs/`, `__pycache__/`, `.next/`, `vendor/`, `coverage/`
→ Use `package.json`/`*.csproj` for deps. Use `git` CLI for version control. Read source not outputs.

**Privacy — ASK before reading:** `.env`, `*.key`, `*.pem`, `*secret*`, `appsettings.*.json`, `Web.config`, `launchSettings.json`, `*.pfx`
→ Never echo passwords/API keys. Replace with `[REDACTED]`.

**Post-Edit** — After 5+ file edits, suggest complexity/duplication review.

**Context Efficiency** — Search before reading full files. Don't re-read files already seen. Read focused ranges (50-100 lines). Use `package.json`/`*.csproj`/`*.sln` for dep info.

**Naming** — C#: `PascalCase`. JS/TS: `kebab-case`. Components: `PascalCase`. Match existing project convention.

**Coding Level** — Default: Senior. Auto-detect from user signals. Beginner=explain, Expert=pure code zero explanation.

<!-- ANTIGRAVITY_WORKSPACE_START -->

# Antigravity Agent Kit — Antigravity Rules

> This workspace has an AI toolkit at .agent/. Read .agent/ARCHITECTURE.md first.

---

## What is .agent/?

This workspace contains the Antigravity AI capability expansion toolkit. It provides:

- **Agents** (.agent/agents/*.md) — 20 specialist AI personas (frontend, backend, security, etc.)
- **Skills** (.agent/skills/*/SKILL.md) — 37 domain-specific knowledge modules
- **Workflows** (.agent/workflows/*.md) — 12 step-by-step procedures triggered by slash commands

**Read .agent/ARCHITECTURE.md first** to understand the full system map.

---

## Agent Routing Protocol (MANDATORY)

Before writing any code or making design decisions:

1. **Identify the domain** of the user's request (Frontend, Backend, Security, Database, etc.)
2. **Select the matching agent** from .agent/agents/
3. **Read that agent's .md file** to understand its rules, persona, and linked skills
4. **Load linked skills** listed in the agent file's frontmatter (skills: field) — read SKILL.md first, then only sections matching the task
5. **Apply the agent's rules** when generating your response
6. **Announce**: State which agent expertise is being applied

### Agent Selection Guide

| Domain | Agent File | Key Skills |
|--------|-----------|------------|
| Web UI/UX | frontend-specialist.md | frontend-design, react-best-practices |
| API/Backend | backend-specialist.md | api-patterns, nodejs-best-practices |
| Database | database-architect.md | database-design |
| Mobile | mobile-developer.md | mobile-design |
| Security | security-auditor.md | vulnerability-scanner |
| Testing | test-engineer.md | testing-patterns, webapp-testing |
| Debugging | debugger.md | systematic-debugging |
| Planning | project-planner.md | brainstorming, plan-writing |
| Multi-domain | orchestrator.md | parallel-agents |

---

## Skill Loading Protocol

Skills are modular knowledge packages inside .agent/skills/.

1. Read SKILL.md inside the skill folder (e.g., .agent/skills/clean-code/SKILL.md)
2. Only read the sections relevant to the current task (**selective reading**)
3. If the skill has a scripts/ folder, those scripts can be executed for validation

### Skill Structure

```
.agent/skills/{skill-name}/
├── SKILL.md           # Main instructions (REQUIRED — read this first)
├── scripts/           # Runnable validation scripts (optional)
├── references/        # Templates and docs (optional)
└── assets/            # Images, resources (optional)
```

### Global Mandatory Skill

**clean-code** applies to ALL code output. Always follow .agent/skills/clean-code/SKILL.md.

---

## Workflow Conventions

Workflow files in .agent/workflows/*.md are triggered by slash commands (e.g., /debug, /deploy, /ins-develop).

### Special Annotations

When reading workflow files, understand these Antigravity-specific markers:

| Marker | Meaning |
|--------|---------|
| $ARGUMENTS | Placeholder for user-provided arguments after the slash command |
| // turbo | The NEXT step can be auto-executed without user confirmation |
| // turbo-all | ALL subsequent steps in this section can be auto-executed |

### Available Workflows (12)

| Command | Purpose |
|---------|---------|
| /brainstorm | Socratic discovery |
| /create | Create new features |
| /debug | Systematic debugging |
| /deploy | Production deployment |
| /enhance | Improve existing code |
| /ins-develop | INS Module development lifecycle |
| /orchestrate | Multi-agent coordination |
| /plan | Task breakdown |
| /preview | Preview changes |
| /status | Check project status |
| /test | Run tests |
| /ui-ux-pro-max | UI design with 50+ styles |

---

## Request Classification

Before any action, classify the request type:

| Request Type | Trigger | Action |
|-------------|---------|--------|
| **Question** | "what is", "explain" | Text response only |
| **Survey** | "analyze", "overview" | Research, no file changes |
| **Simple Code** | "fix", "add" (single file) | Direct inline edit |
| **Complex Code** | "build", "implement", "refactor" | Plan first, then implement |
| **Design/UI** | "design", "page", "dashboard" | Agent routing + plan required |
| **Slash Command** | /command | Read matching workflow file |

---

## Rules Priority

When rules conflict, apply this priority:

1. **P0** — This rules file (global)
2. **P1** — Agent-specific rules (from .agent/agents/*.md)
3. **P2** — Skill-specific rules (from .agent/skills/*/SKILL.md)

---

## Code Standards

- ALL code follows clean-code skill rules — no exceptions
- Use **English** for code, comments, and variable names
- Respond in the **user's language** for explanations
- Before modifying files, check for dependencies and update all affected files together
- For complex requests: **ask questions first** before implementing (Socratic Gate)

---

## Important Paths

```
.agent/
├── ARCHITECTURE.md     # System overview — READ THIS FIRST
├── agents/             # 20 specialist agent definitions
├── skills/             # 37 knowledge modules
├── workflows/          # 12 slash command procedures
├── rules/              # IDE-specific instruction files
└── scripts/            # Master validation scripts
```

---

## Validation Scripts

| Script | Purpose | When |
|--------|---------|------|
| checklist.py | Priority-based project audit | Development, pre-commit |
| verify_all.py | Comprehensive verification | Pre-deployment |

```bash
python .agent/scripts/checklist.py .
python .agent/scripts/verify_all.py . --url http://localhost:3000
```

---

## 🛡️ AUTO-PROTECTION RULES (Always Active — Zero Config)

> These rules are **ALWAYS enforced automatically**. No configuration needed.

### Scout Block — Forbidden Directories

**NEVER read/list/explore:** node_modules/, .git/, dist/, build/, out/, __pycache__/, .next/, .nuxt/, .turbo/, vendor/, target/, coverage/, bin/, obj/, packages/, .vs/, .idea/

- Use package.json or *.csproj instead of reading node_modules or packages/
- Use git CLI instead of reading .git/
- Read source instead of build outputs
- If user insists → warn about context waste first

### Privacy Protection — Sensitive Files

**ASK before reading:** .env, .env.*, *.key, *.pem, *.crt, *secret*, *credential*, appsettings.*.json, Web.config, launchSettings.json, *.pfx, *.p12

> 🔒 "This file may contain sensitive data. Should I read it? I will NOT include secret values in my responses."

When approved: NEVER echo passwords/API keys. Replace with [REDACTED].

### Post-Edit Awareness

After editing **5+ files** in one session, suggest a review:
> 📝 "Should I review changes for: complexity, duplication, dead code, shared utilities?"

### Context Efficiency

- **Search before read** — find specific content first, read targeted lines second
- **Don't re-read** — remember info from earlier in conversation
- **Read ranges** — for large files, read 50-100 lines at a time
- **Batch reads** — read multiple files in parallel, not sequential turns
- **Use manifests** — read package.json or *.csproj/*.sln instead of exploring deps

### Naming Enforcement

- C# source: PascalCase (UserService.cs)
- JS/TS source: kebab-case (user-service.ts)
- Components: PascalCase (UserProfile.tsx, NavMenu.razor)
- Tests (JS): {name}.test.{ext} | Tests (C#): {Name}Tests.cs
- **KEY**: Match the project's existing convention. Never mix styles.
- Warn on vague names (Utils.cs → suggest StringUtils.cs)

### Coding Level Auto-Detection

| Signal | Level | Style |
|---|---|---|
| Asks "what is X?" | Beginner | Explain with analogies |
| Writes pseudo-code | Intermediate | Working code + WHY |
| Gives file paths, function names | Senior | Code-first, trade-offs |
| "just do it", terse | Expert | Zero explanation, pure code |

**Default: Senior.** Match user's language register and formality.


> **CRITICAL RULE - MCP ENFORCER (CLAUDE-MEM MECHANISM)**:
> 
> Để tiết kiệm tối đa Token và xây dựng bộ nhớ dự án (Project Memory) đồng bộ dài hạn, AI **BẮT BUỘC** phải tuân thủ nghiêm ngặt kỹ thuật sử dụng MCP Server. Nếu vi phạm, AI sẽ tích tụ token rác và bị coi là thao tác sai quy trình:
> 
> 1. THIẾT LẬP CONTEXT (Khởi động): Luôn gọi `GetWorkspaceContext` ĐẦU TIÊN để nhận thức được tiến độ và các Plan/Task đang tồn đọng từ Server. Đối với workspaceId này: c:\Users\huanld\.gemini\antigravity\scratch\antigravity-agent-kit.
> 2. KẾ HOẠCH & NOTE (Plan): Không lập kế hoạch vào trí nhớ ảo. **TUYỆT ĐỐI KHÔNG ghi ra các file markdown local (như implementation_plan.md)**. Mọi kế hoạch, kiến trúc tĩnh phải push LÊN SERVER bằng `SetWorkspacePlan` và LUÔN đọc từ Server.
> 3. QUẢN LÝ TASK (Ticketing): Không gạch đầu dòng công việc trên text chat. Khi có task mới -> gọi `UpsertTask` (nhớ gán status InProgress). Chuyển status -> Done khi hoàn tất. **TUYỆT ĐỐI KHÔNG ghi ra các file local (như task.md)**, chỉ đồng bộ với server để đảm bảo trí nhớ dài hạn.
> 4. TÀI LIỆU WORKSPACE (Docs): Request nội dung phức tạp hoặc spec dài phải lưu xuống Server thông qua `WriteWorkspaceDocument`, khi cần thì sử dụng `ReadWorkspaceDocument` để đọc thay vì đọc file local (như walkthrough.md).
> 5. TRA CỨU: Mọi câu hỏi kiến thức, lib syntax, coding standards đều bắt buộc tra cứu qua `SearchKnowledge` hoặc `SearchWorkspace` trên MCP, nghiêm cấm bịa hàm, tự đoán.


<!-- ANTIGRAVITY_WORKSPACE_END -->
