antigravity-ai-kit 2.1.0 → 3.0.1

package/.agent/skills/i18n-localization/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: i18n-localization
+description: Internationalization and localization patterns for multi-language applications
+triggers:
+  [
+    i18n,
+    internationalization,
+    localization,
+    l10n,
+    translation,
+    multi-language,
+    locale,
+    rtl,
+  ]
+---
+
+# Internationalization & Localization
+
+## Overview
+
+This skill provides patterns and best practices for building multi-language applications with proper internationalization (i18n) and localization (l10n) support.
+
+## Core Principles
+
+1. **Separate content from code**: All user-facing strings must be externalized
+2. **Use ICU message format**: Support plurals, gender, and context
+3. **Plan for RTL**: Layout should adapt to right-to-left languages
+4. **Locale-aware formatting**: Dates, numbers, currencies must respect locale
+5. **Fallback strategy**: Always have a default language fallback chain
+
+## Recommended Libraries
+
+### React / Next.js
+
+| Library                     | Use Case                              |
+| --------------------------- | ------------------------------------- |
+| `next-intl`                 | Next.js App Router (recommended)      |
+| `react-intl` / `formatjs`   | React apps with ICU support           |
+| `i18next` + `react-i18next` | Feature-rich, plugin ecosystem        |
+| `lingui`                    | Compile-time extraction, small bundle |
+
+### React Native / Expo
+
+| Library                     | Use Case                      |
+| --------------------------- | ----------------------------- |
+| `i18next` + `react-i18next` | Cross-platform (web + native) |
+| `expo-localization`         | Device locale detection       |
+| `react-native-localize`     | Native locale detection       |
+
+### Backend (Node.js)
+
+| Library         | Use Case                 |
+| --------------- | ------------------------ |
+| `i18next`       | Server-side translations |
+| `messageformat` | ICU message compilation  |
+| `globalize`     | CLDR-based formatting    |
+
+## File Structure
+
+```
+src/
+├── locales/
+│   ├── en/
+│   │   ├── common.json       # Shared translations
+│   │   ├── auth.json          # Auth-related strings
+│   │   ├── dashboard.json     # Dashboard strings
+│   │   └── errors.json        # Error messages
+│   ├── tr/
+│   │   ├── common.json
+│   │   ├── auth.json
+│   │   ├── dashboard.json
+│   │   └── errors.json
+│   └── de/
+│       └── ...
+├── i18n/
+│   ├── config.ts              # i18n configuration
+│   ├── types.ts               # Type-safe key definitions
+│   └── middleware.ts          # Locale detection middleware
+```
+
+## Translation Key Naming Convention
+
+```json
+{
+  "namespace.component.element": "Translation",
+
+  "auth.login.title": "Sign In",
+  "auth.login.emailLabel": "Email Address",
+  "auth.login.passwordLabel": "Password",
+  "auth.login.submitButton": "Sign In",
+  "auth.login.forgotPassword": "Forgot your password?",
+
+  "errors.validation.required": "{field} is required",
+  "errors.validation.minLength": "{field} must be at least {min} characters",
+  "errors.network.timeout": "Request timed out. Please try again."
+}
+```
+
+## Key Patterns
+
+### 1. Type-Safe Translations (TypeScript)
+
+```typescript
+// types.ts — Generate from default locale JSON
+type TranslationKeys = keyof typeof import('./locales/en/common.json');
+
+// Usage with next-intl
+import { useTranslations } from 'next-intl';
+
+function LoginForm() {
+  const t = useTranslations('auth.login');
+  return <h1>{t('title')}</h1>; // Type-checked!
+}
+```
+
+### 2. Pluralization (ICU Format)
+
+```json
+{
+  "notifications.count": "{count, plural, =0 {No notifications} one {# notification} other {# notifications}}"
+}
+```
+
+### 3. Date/Number Formatting
+
+```typescript
+// Always use Intl API or library formatters
+const formatted = new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "long",
+  day: "numeric",
+}).format(date);
+
+const price = new Intl.NumberFormat(locale, {
+  style: "currency",
+  currency: "EUR",
+}).format(amount);
+```
+
+### 4. RTL Support
+
+```css
+/* Use logical properties instead of physical */
+.container {
+  padding-inline-start: 1rem; /* Not padding-left */
+  margin-inline-end: 2rem; /* Not margin-right */
+  border-inline-start: 2px solid;
+}
+```
+
+### 5. Next.js App Router Integration
+
+```typescript
+// middleware.ts
+import createMiddleware from "next-intl/middleware";
+
+export default createMiddleware({
+  locales: ["en", "tr", "de"],
+  defaultLocale: "en",
+  localeDetection: true,
+});
+
+export const config = {
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+## Quality Checklist
+
+- [ ] All user-facing strings externalized (no hardcoded text)
+- [ ] Pluralization rules applied for countable items
+- [ ] Date/time/number formatting uses locale-aware APIs
+- [ ] RTL layout tested (if supporting RTL languages)
+- [ ] Fallback language chain configured
+- [ ] Translation keys are descriptive and namespaced
+- [ ] Missing translation handling defined (fallback vs error)
+- [ ] SEO: `<html lang="">` and `hreflang` tags set
+- [ ] URL structure supports locale (`/en/about` or subdomain)
+
+## Anti-Patterns to Avoid
+
+❌ Hardcoding strings in components
+❌ Using string concatenation for translated sentences
+❌ Assuming left-to-right layout
+❌ Using physical CSS properties (left/right) instead of logical (start/end)
+❌ Formatting dates/numbers without locale context
+❌ Storing translations in code instead of separate files
+
+---
+
+> **Source**: Antigravity AI Kit — [besync-labs/antigravity-ai-kit](https://github.com/besync-labs/antigravity-ai-kit)

package/.agent/skills/mcp-integration/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: mcp-integration
+description: Model Context Protocol (MCP) integration patterns for extending AI capabilities with external tools and data sources.
+version: 1.0.0
+triggers: [mcp, tool, server, protocol, integration, external]
+---
+
+# MCP Integration Skill
+
+> **Purpose**: Guide the integration and effective use of Model Context Protocol (MCP) servers to extend AI agent capabilities with external tools, data sources, and services.
+
+---
+
+## Overview
+
+The Model Context Protocol (MCP) is an open standard that connects AI systems with external tools and data sources through a unified interface. MCP servers act as capability providers — each server exposes a set of tools that the AI can invoke to perform actions beyond its native abilities.
+
+This skill ensures that MCP integrations follow Trust-Grade principles: secure, reliable, and properly governed.
+
+---
+
+## Core Concepts
+
+### MCP Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│    AI Agent      │────▶│   MCP Client     │────▶│   MCP Server    │
+│  (LLM + Kit)    │◀────│  (IDE/Runtime)   │◀────│  (Tool Provider)│
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                                         │
+                                                    ┌────┴────┐
+                                                    │ External │
+                                                    │ Service  │
+                                                    └─────────┘
+```
+
+### Key Components
+
+| Component | Role | Example |
+|:----------|:-----|:--------|
+| **MCP Server** | Exposes tools via protocol | GitHub MCP, GitKraken MCP, Database MCP |
+| **MCP Client** | Connects AI to servers | VS Code extension, Cursor, IDE runtime |
+| **Tools** | Individual capabilities | `create_issue`, `git_commit`, `run_query` |
+| **Resources** | Data endpoints | File contents, database schemas, API docs |
+| **Prompts** | Reusable templates | Code review template, deployment checklist |
+
+---
+
+## Integration Patterns
+
+### Pattern 1: Git Operations via MCP
+
+**When to use**: Git operations that benefit from structured API access rather than raw CLI commands.
+
+**Available servers**: GitKraken MCP, GitHub MCP
+
+```
+Preferred for:
+- Creating branches, commits, PRs (structured data)
+- Reading git status, blame, diff (parsed output)
+- Managing issues and reviews (API access)
+
+Still use CLI for:
+- Complex git operations (rebase, cherry-pick)
+- Local-only operations (stash, worktree)
+- Performance-critical batch operations
+```
+
+### Pattern 2: Issue and Project Management
+
+**When to use**: Creating, updating, and querying issues across platforms.
+
+```
+GitHub MCP Server provides:
+- issue_write (create/update issues)
+- issue_read (get details, comments, labels)
+- search_issues (query with GitHub syntax)
+- list_issues (paginated browsing)
+
+Best practices:
+- Use search_* for targeted queries with criteria
+- Use list_* for broad retrieval with pagination
+- Batch reads in groups of 5-10 items
+```
+
+### Pattern 3: Code Search and Analysis
+
+**When to use**: Finding code patterns across repositories.
+
+```
+GitHub MCP provides:
+- search_code (cross-repo code search)
+- get_file_contents (read specific files)
+- get_commit (commit details with diff)
+
+Usage guidance:
+- Use search_code for finding symbols, functions, patterns
+- Use get_file_contents for reading specific known files
+- Combine with local grep_search for current workspace
+```
+
+### Pattern 4: Pull Request Workflow
+
+**When to use**: Full PR lifecycle management.
+
+```
+Workflow:
+1. create_branch → Create feature branch
+2. push_files → Push code changes
+3. create_pull_request → Open PR
+4. request_copilot_review → Automated review
+5. pull_request_read(get_status) → Check CI status
+6. merge_pull_request → Merge when ready
+
+Trust-Grade rules:
+- Always create PR (never push directly to main)
+- Always request review before merge
+- Always check CI status before merge
+```
+
+---
+
+## Security Guidelines
+
+### Authentication
+
+- MCP servers use token-based authentication
+- Tokens are managed by the IDE/runtime, never by the AI agent
+- Never log, display, or store authentication tokens
+- Verify server identity before sending sensitive operations
+
+### Permission Model
+
+| Operation Type | Risk Level | Verification Required |
+|:---------------|:-----------|:---------------------|
+| Read (list, get, search) | Low | None |
+| Create (new issue, branch, file) | Medium | Confirm with user |
+| Modify (update, edit) | Medium | Confirm with user |
+| Delete (remove file, close issue) | High | Explicit user approval |
+| Deploy (merge, publish) | Critical | Double confirmation |
+
+### Data Handling
+
+- Never pass secrets through MCP tool parameters
+- Sanitize user data before including in tool calls
+- Respect repository visibility (public vs private)
+- Log operations for audit trail (session-context.md)
+
+---
+
+## Server Selection Guide
+
+| Task | Recommended Server | Why |
+|:-----|:-------------------|:----|
+| Git operations (commit, branch, status) | GitKraken MCP | Richer git-specific tools |
+| GitHub issues and PRs | GitHub MCP | Native GitHub API access |
+| Code review and analysis | GitHub MCP | PR review tools |
+| Repository management | GitHub MCP | Repo CRUD operations |
+| Complex git workflows | GitKraken MCP | Worktree, stash, blame |
+
+---
+
+## Error Handling
+
+### Common MCP Errors
+
+| Error | Cause | Resolution |
+|:------|:------|:-----------|
+| `ENEEDAUTH` | Token expired/missing | Re-authenticate via IDE settings |
+| `403 Forbidden` | Insufficient permissions | Check token scopes |
+| `404 Not Found` | Resource doesn't exist | Verify owner/repo/branch names |
+| `422 Unprocessable` | Invalid parameters | Check required fields and formats |
+| `Rate Limited` | Too many requests | Implement exponential backoff |
+
+### Fallback Strategy
+
+When an MCP server is unavailable:
+1. Log the failure in session context
+2. Fall back to CLI equivalent if available
+3. Notify user of degraded capability
+4. Continue with remaining available tools
+
+---
+
+## Integration with Antigravity AI Kit
+
+### Loading Rules Integration
+
+MCP capabilities are registered in `engine/loading-rules.json` under domain rules:
+
+```json
+{
+  "domain": "git-operations",
+  "keywords": ["git", "commit", "branch", "pr", "merge"],
+  "loadAgents": ["devops-engineer"],
+  "loadSkills": ["git-workflow", "mcp-integration"],
+  "mcpServers": ["GitKraken", "github-mcp-server"]
+}
+```
+
+### Session Context Tracking
+
+Log MCP operations in session context for continuity:
+
+```markdown
+## MCP Operations This Session
+- Created branch `feature/auth` via GitKraken MCP
+- Opened PR #42 via GitHub MCP
+- Requested Copilot review via GitHub MCP
+```
+
+### Workflow State Integration
+
+MCP operations map to workflow phases:
+
+| Phase | MCP Operations |
+|:------|:--------------|
+| EXPLORE | `search_code`, `get_file_contents`, `list_issues` |
+| PLAN | `issue_write` (create tracking issue) |
+| IMPLEMENT | `create_branch`, `push_files` |
+| VERIFY | `pull_request_read(get_status)` |
+| REVIEW | `request_copilot_review`, `pull_request_review_write` |
+| DEPLOY | `merge_pull_request` |

package/.agent/skills/parallel-agents/SKILL.md

@@ -169,7 +169,7 @@ After all agents complete, synthesize findings:
 
 - [ ] Verify session state is current
 - [ ] Check for active blockers
-- [ ] Load relevant Meta-Directives
+- [ ] Load relevant governance rules
 - [ ] Confirm scope with user if complex
 
 ### Post-Orchestration Protocol

package/.agent/skills/shell-conventions/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: shell-conventions
+description: PowerShell shell conventions for Windows. Avoid bash-isms. Reference before running terminal commands.
+triggers: [powershell, terminal, shell, command, run, windows, cli]
+---
+
+# Shell Conventions — Windows PowerShell 5.x
+
+> **Environment**: Windows PowerShell 5.x (NOT PowerShell 7/Core)
+> **Scope**: All `run_command` tool calls across all workspaces
+
+---
+
+## 🔴 CRITICAL RULES
+
+1. **NEVER use `&&`** — It is NOT a valid operator in PowerShell 5.x
+2. **NEVER use `cd dir && command`** — Use the `Cwd` parameter on `run_command` instead
+3. **NEVER use `||`** as bash-style OR — Use `if (-not $?) { ... }` instead
+
+---
+
+## Operator Reference
+
+| Operator | Bash                       | PowerShell 5.x          | Notes                             |
+| -------- | -------------------------- | ----------------------- | --------------------------------- |
+| `&&`     | Sequential (conditional)   | ❌ **NOT SUPPORTED**    | Use `;` or `Cwd` param            |
+| `;`      | Sequential (unconditional) | ✅ Sequential execution | Runs next regardless of exit code |
+| `\|`     | Pipe stdout                | ✅ Pipe objects         | Different semantics than bash     |
+| `\|\|`   | OR (run on failure)        | ❌ **NOT SUPPORTED**    | Use `if (-not $?) { ... }`        |
+| `>`      | Redirect stdout            | ✅ Redirect output      | Same behavior                     |
+| `2>&1`   | Redirect stderr to stdout  | ✅ Merge streams        | Same behavior                     |
+
+---
+
+## Patterns
+
+### ❌ WRONG: Chaining with &&
+
+```bash
+cd src && npm test && npm run build
+```
+
+### ✅ RIGHT: Use Cwd parameter
+
+```powershell
+# Set Cwd to "src" on run_command, then just run:
+npm test
+```
+
+### ✅ RIGHT: Sequential with ;
+
+```powershell
+git status; git log --oneline -5
+```
+
+### ✅ RIGHT: Call operator for executables with spaces/special chars
+
+```powershell
+& ".venv\Scripts\ruff.exe" check app/
+& ".venv\Scripts\pytest.exe" tests/ -v
+```
+
+---
+
+## Common Patterns
+
+| Task                | PowerShell Command                          |
+| ------------------- | ------------------------------------------- |
+| Run Node.js tests   | `npm test`                                  |
+| Run Python tests    | `& ".venv\Scripts\pytest.exe" tests/ -q`    |
+| Run linter          | `npm run lint`                              |
+| Check git status    | `git status`                                |
+| Build project       | `npm run build`                             |
+| Install deps        | `npm install`                               |
+| List files          | `Get-ChildItem -Recurse`                    |
+| Find in files       | `Select-String -Pattern "text" -Path "*.md"`|
+
+---
+
+## Virtual Environment (Python)
+
+```powershell
+# Activate (PowerShell)
+& ".venv\Scripts\Activate.ps1"
+
+# Run without activation (preferred for tool calls)
+& ".venv\Scripts\python.exe" -m pytest tests/ -q
+& ".venv\Scripts\python.exe" -m ruff check app/
+```
+
+> [!TIP]
+> For `run_command` tool calls, prefer calling the executable directly with `&` rather than activating the virtual environment.