speckle-server/.agent/rules/copilot-instructions.md

Antigravity Agent Kit — Instructions for GitHub Copilot

This file teaches Copilot how to use the .agent/ toolkit installed in this workspace.

---

What is .agent/?

This workspace contains an AI capability expansion toolkit at .agent/. It provides:

• Agents (.agent/agents/*.md) — Specialist AI personas (frontend, backend, security, etc.)
• Skills (.agent/skills/*/SKILL.md) — Domain-specific knowledge modules
• Workflows (.agent/workflows/*.md) — Step-by-step procedures triggered by slash commands

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

---

Agent Routing Protocol

Before writing 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)
5. Apply the agent's rules when generating your response

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. To use a skill:

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

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

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

---

Rules Priority

When rules conflict, apply this priority:

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

---

Code Standards

• Follow clean-code skill for all code
• 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

---

Important Paths

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

---

🛡️ Auto-Protection Rules (Always Active)

These rules are always enforced. No configuration needed.

Forbidden Directories

NEVER read or explore these directories — they waste context and provide no useful information:

node_modules/, .git/, dist/, build/, out/, bin/, obj/, packages/, .vs/, .idea/, __pycache__/, .next/, .nuxt/, .turbo/, vendor/, target/, coverage/

Instead: use package.json or *.csproj for dependency info. Use git commands for version control. Read source files, not build outputs.

Sensitive Files

Always ask the user before reading: .env, .env.*, *.key, *.pem, *.crt, *secret*, *credential*, appsettings.*.json, Web.config, launchSettings.json, *.pfx, *.p12

When approved: never echo passwords or API keys in responses. Replace with [REDACTED].

Context Efficiency

• Search for specific content before reading entire files
• Don't re-read files already seen in the conversation
• For large files, read focused ranges (50-100 lines) instead of all at once
• Use package.json or *.csproj/*.sln instead of exploring dependency directories

Naming Conventions

• C# source files: PascalCase (UserService.cs)
• JS/TS source files: kebab-case (user-service.ts)
• Components: PascalCase (UserProfile.tsx, NavMenu.razor)
• Tests (JS): {name}.test.{ext} | Tests (C#): {Name}Tests.cs
• KEY: Always match the project's existing naming convention

Communication Style

Adapt based on user's expertise level. Default: Senior (code-first, minimal explanation). If user asks basic questions, shift to teaching mode. If user gives terse instructions, respond with pure code.