DOCSEARCHbyAlgolia
Submit Docs

AG Kit

repository·main·Indexed 27 days ago

https://github.com/vudovn/ag-kit

An agent engineering kit for the Google Antigravity runtime. It provides a structured workspace for managing agent rules, skills, workflows, orchestration, and persistent memory using Markdown-based patterns. The kit includes a CLI for safe updates and rollbacks, MCP configuration management via sync-mcp.mjs, and native safety hooks to intercept tool calls. It defines a runtime boundary within the .agents/ directory and provides a suite of slash commands for orchestration, such as /orchestrate, /coordinate, and /plan.

Tokens
12.6K
Snippets
31
Records
72
Agent score
92%

What's inside ag-kit

  1. Understand the AG Kit Runtime Boundary

    main

    AG Kit defines project behavior within the .agents/ directory. The Google Antigravity production runtime discovers and executes these definitions. The directory structure is organized as follows:

    • .agents/rules/: Persistent constraints.
    • .agents/skills/: Progressive domain context.
    • .agents/workflows/: Slash-command procedures.
    • .agents/agent/: Specialist role definitions.
    • .agents/memory/: Durable project context.

    Routing and orchestration are handled via direct specialist selection, /coordinate (parallel research and synthesis), or /orchestrate (plan → user approval → delegated implementation).

  2. Review system capabilities and supported frameworks

    main

    The system provides high coverage (~95% web/mobile + orchestration) using 20 agents and 47 skills.

    Supported Frameworks:

    • Frontend: React 19, Next.js 16, Vue, Nuxt 4, Astro 6
    • Backend: Node.js 24, FastAPI, Express 5, Rust
    • Mobile: React Native, Flutter
    • Database: Prisma, Drizzle, PostgreSQL
    • Testing: Jest, Vitest, Playwright, Cypress
    • DevOps: Docker, Vercel, AWS, GitHub Actions

    Orchestration Features:

    • Coordinator Mode (parallel orchestration)
    • Persistent Memory System (MEMORY.md)
    • Context Compression (auto-compact)
    • Conditional Skill Loading (when_to_use)
    • Verification by Execution (/verify)
    ┌──────────────────────────────────────────────────────────┐
│                    SYSTEM CAPABILITIES                    │
├──────────────────────────────────────────────────────────┤
│ Total Agents:              20                            │
│ Total Skills:              47                            │
│ Total Workflows:           13                            │
│ Master Scripts:            2 (checklist, verify_all)     │
│ Skill-Level Scripts:       16                            │
│ Coverage:                  ~95% web/mobile + orchestration│
│                                                          │
│ Orchestration & Memory:                                  │
│ ├─ Coordinator Mode (parallel orchestration)             │
│ ├─ Persistent Memory System (MEMORY.md)                  │
│ ├─ Context Compression (auto-compact)                    │
│ ├─ Conditional Skill Loading (when_to_use)                │
│ └─ Verification by Execution (/verify)                   │
│                                                          │
│ Supported Frameworks:                                    │
│ ├─ Frontend: React 19, Next.js 16, Vue, Nuxt 4, Astro 6 │
│ ├─ Backend: Node.js 24, FastAPI, Express 5, Rust        │
│ ├─ Mobile: React Native, Flutter                        │
│ ├─ Database: Prisma, Drizzle, PostgreSQL                │
│ ├─ Testing: Jest, Vitest, Playwright, Cypress          │
│ └─ DevOps: Docker, Vercel, AWS, GitHub Actions         │
└──────────────────────────────────────────────────────────┘

  3. Understand the Antigravity Runtime Layer

    main

    Google Antigravity is the production runtime for AG Kit. It provides a native integration layer located within the .agents/ directory of your workspace. The runtime consists of four primary components:

    • antigravity.json: Defines the machine-readable runtime contract.
    • hooks.json: Provides a native PreToolUse safety gate.
    • mcp_config.json: Acts as the workspace's source of truth for MCP (Model Context Protocol) servers.
    • Doctor: A tool for performing read-only integration diagnostics.

  5. Build and install the Antigravity plugin

    main
    You can package the AG Kit components into a local Antigravity plugin bundle. The bundle includes skills, agents, rules, workflow commands, the native hook, and an MCP example. After building, you can install it using the agy CLI.

  6. Sync MCP configuration

    main

    The .agents/mcp_config.json file serves as the source of truth for the workspace's MCP configuration. You can explicitly apply this configuration using the sync script. The synchronizer rejects placeholder credentials, preserves conflicting items by default, and backs up the destination before writing.

    node .agents/hooks/sync-mcp.mjs

  7. Install AG Kit into a project

    main

    You can initialize AG Kit in your project using npx for a one-time setup, or install the CLI globally to use the ag-kit command directly.

    Important: Do not add .agents/ to your project's .gitignore if you want Antigravity to index rules, skills, or workflows. To keep the directory local without disabling discovery, add .agents/ to .git/info/exclude instead.

    # Using npx
npx @vudovn/ag-kit init

# Or installing globally
npm install -g @vudovn/ag-kit
ag-kit init

  8. Configure MCP (Model Context Protocol) via sync-mcp

    main

    Use the sync-mcp.mjs script to manage MCP configurations without writing to your home directory.

    1. Use --check or --print to preview changes.
    2. Use --apply with a --target (e.g., suite or cli) to commit changes.

    Warning: Do not commit real MCP credentials to your repository.

    # Preview changes
node .agents/hooks/sync-mcp.mjs --check
node .agents/hooks/sync-mcp.mjs --print

# Apply changes to a specific target
node .agents/hooks/sync-mcp.mjs --apply --target suite
node .agents/hooks/sync-mcp.mjs --apply --target cli

  9. Verify the AG Kit workspace

    main

    After installation, use the following npm scripts to validate your workspace configuration and Antigravity integration. Note that check:antigravity is a read-only operation. If the default MCP example contains YOUR_API_KEY, the doctor will report a warning until you configure it. For strict validation after resolving all placeholders, use the --strict flag with the doctor script.

    npm run check:agents
npm run check:antigravity
npm run test:antigravity

# Strict mode validation
node .agents/hooks/antigravity-doctor.mjs --strict

  10. Skill Loading Protocol

    main

    Skills are loaded following a structured flow to ensure the agent has the necessary context and tools:

    1. Match Request to Skill: Keyword matching (e.g., "API" matches api-patterns).
    2. Load Skill Metadata: Reads instructions from .agents/skills/{skill-name}/SKILL.md.
    3. Load References: Reads supporting documentation (e.g., api-patterns/rest.md).
    4. Execute Scripts: The agent may suggest running validation scripts (e.g., scripts/api_validator.py). Note: Scripts are NOT auto-executed; the user must approve them.
    5. Apply Knowledge: The agent applies the loaded patterns, strategies, and templates.

  12. Adhere to Runtime Safety Rules

    main

    When using AG Kit, follow these safety protocols:

    • Permissions: Antigravity permission and workspace-trust controls remain active; AG Kit hooks supplement but do not replace them.
    • Destructive Actions: Destructive behavior must be tested with mocked payloads, never by executing real destructive commands.
    • MCP Writes: Require the explicit --apply flag. Unresolved placeholders will block the write.
    • Source of Truth: The .agents/ tree in the repository is the primary source of truth, even if a plugin bundle is installed.
    • Human Approval: Planning, deployment, destructive operations, and security-sensitive work require human approval gates.