speckle-server/.agent/rules/antigravityrules

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