AAC (Antigravity Agent Core)

Minimalist autonomous engineering framework for Google Antigravity.
Engineered for Gemini 3.8 Flash (High) • Native Progressive Disclosure • Lifecycle Hooks • Multi-Agent Workspaces

Quick Start • Architecture • Repository Layout • Skill Catalog • Memory System • Lifecycle Hooks • MCP Setup

⚡ Overview

AAC (Antigravity Agent Core) is a minimalist autonomous engineering framework built for the Google Antigravity Customization Architecture. It provides focused pair programming, autonomous multi-agent task execution, and progressive context disclosure without token waste or hallucinated tooling.

⚡ Quick Start (Multi-Platform)

Install AAC into any existing project (Python, Go, Rust, Node, Java, PHP, C++) with a single command:

Option 1: Universal NPX (Any OS with Node.js)

# Via npm registry:
npx @rafaelghif/aac init

# Or directly from GitHub:
npx github:rafaelghif/antigravity-agents-core init

Option 2: Standalone Windows PowerShell (Zero Node.js Prerequisite)

irm https://raw.githubusercontent.com/rafaelghif/antigravity-agents-core/main/install.ps1 | iex

Option 3: Standalone Linux / macOS (Zero Node.js Prerequisite)

curl -fsSL https://raw.githubusercontent.com/rafaelghif/antigravity-agents-core/main/install.sh | bash

[!IMPORTANT]
Zero Package.json Pollution Guarantee: The installer will NEVER create, overwrite, or mutate package.json in your target repository. It cleanly scaffolds .agents/, AGENTS.md, and CONTEXT.md, and appends ignore rules to your .gitignore.

🏗️ Architecture Overview

The framework coordinates context precedence, lifecycle hooks, autonomous subagent graphs, and memory tiers:

flowchart TD
    User(["👤 User Request / Slash Command"]) --> Antigravity["Google Antigravity Engine (CLI / 2.0 / IDE)"]

    subgraph ContextHierarchy ["🧠 Context Precedence (AGENTS.md)"]
        AGENTS["1. AGENTS.md (Root Guidelines, ≤12k chars)"]
        Rules["2. .agents/rules/*.md (trigger: always_on)"]
        Hooks["3. .agents/hooks.json (PreToolUse, PostToolUse, Stop)"]
        Plugins["4. .agents/plugins/ (Packaged MCP & Sidecars)"]
        MCP["5. .agents/mcp_config.json (GitHub & Gitea Tools)"]
        Skills["6. .agents/skills/ (Progressive Disclosure)"]
    end

    Antigravity --> ContextHierarchy

    subgraph LifecycleEngine ["⚡ Lifecycle Event Hooks Engine"]
        PreTool["PreToolUse Hook (git-guardrails: blocks push / reset / clean)"]
        PostTool["PostToolUse Hook (automated linting & validation)"]
        StopHook["Stop Quality Gate (blocks exit on failing tests)"]
    end

    Antigravity --> LifecycleEngine

    subgraph SubagentsGraph ["🤖 Autonomous Subagents (invoke_subagent)"]
        Investigator["cavecrew-investigator (TypeName: research, Model: flash)"]
        Builder["cavecrew-builder (TypeName: self, Workspace: branch)"]
        Reviewer["cavecrew-reviewer / code-review (Two-Axis Reviewers)"]
    end

    Antigravity --> SubagentsGraph

    subgraph SidecarsEngine ["⚙️ Background Sidecars & Scheduled Tasks"]
        Sidecars["repo-health (Periodic git & branch hygiene monitor)"]
        CronSchedule["schedule tool (One-shot and recurring timers)"]
    end

    Antigravity --> SidecarsEngine

📂 Repository Layout

antigravity-agents/
├── assets/                            # Framework visual assets & documentation banners
│   └── banner.png                     # Vector branding banner
├── .agents/                           # Workspace configuration (Strictly isolated)
│   ├── hooks.json                     # Antigravity lifecycle hooks (PreToolUse, Stop)
│   ├── hooks/                         # Cross-platform hooks (block-dangerous-git.cjs, verify-on-stop.cjs)
│   ├── plugins.json                   # Explicit workspace plugin registration
│   ├── skills.json                    # Explicit workspace skills registration (64 skills)
│   ├── mcp_config.example.json        # Sanitized template for Gitea and GitHub MCP
│   ├── plugins/                       # Workspace plugins packaging tools & sidecars
│   │   └── workspace-integrations/    # Workspace integrations bundle
│   ├── rules/                         # Workspace-level rules with 'trigger: always_on'
│   │   ├── caveman.md                 # Ultra-compressed token communication protocol
│   │   ├── coding-standards.md        # SRP, fail-fast, and targeted replacement rules
│   │   ├── git-workflow.md            # Conventional Commits and atomic changes
│   │   ├── ponytail.md                # 7-rung minimalist code ladder (YAGNI to one-liners)
│   │   └── memory-management.md       # 5-tier memory hierarchy & cross-session protocol
│   └── skills/                        # 64 On-demand skills (Progressive disclosure)
├── bin/                               # Universal CLI executable
│   └── cli.mjs                        # Multi-platform installer (init, audit, doctor, list)
├── docs/                              # Framework documentation & decision records
│   ├── adr/                           # Architectural Decision Records (0001-memory, 0002-node-hooks)
│   ├── agents/                        # Skill specifications (issue-tracker, domain, triage-labels)
│   ├── templates/                     # Standardized session handoff template
│   └── audit-checklist-64-skills.md   # Persistent 8-dimension audit checklist for all 64 skills
├── tests/                             # Automated verification suites (node --test)
│   ├── memory-system.test.mjs         # Verified 64-skill criteria and memory architecture
│   └── cli.test.mjs                   # CLI tests (including zero-package.json pollution test)
├── install.ps1                        # Standalone Windows PowerShell 1-liner installer (Zero Node)
├── install.sh                         # Standalone Linux/macOS curl 1-liner installer (Zero Node)
├── package.json                       # Framework manifest for npm/npx distribution
├── .scratch/                          # Local session scratchpad & handoff staging (gitignored)
├── AGENTS.md                          # Root instructions unconditionally loaded per turn (<12k chars)
├── GEMINI.md                          # Pointer alias to AGENTS.md
└── CONTEXT.md                         # Living domain glossary & architectural boundaries

🎯 Autonomous Skills Suite

Skills are loaded into Antigravity via progressive disclosure: only names and descriptions are exposed in the initial context. When a user intent or slash command is matched, the agent reads the target SKILL.md directly via view_file.

🧠 5-Tier Memory Management

To maintain crisp context without attention degradation or token bloat, AAC partitions memory across five distinct tiers:

┌─────────────────────────────────────────────────────────────┐
│ Tier 1: Ephemeral Working Context (Intra-Session)           │ -> Context window & transcript.jsonl
├─────────────────────────────────────────────────────────────┤
│ Tier 2: Workspace Directives (Cross-Session Deterministic)  │ -> AGENTS.md (<12k chars), .agents/rules/*.md
├─────────────────────────────────────────────────────────────┤
│ Tier 3: Domain & Architectural Knowledge (Living Docs)      │ -> CONTEXT.md, docs/adr/*.md
├─────────────────────────────────────────────────────────────┤
│ Tier 4: Session Bridge Handoff (Inter-Session State)        │ -> .scratch/handoff.md via handoff skill
├─────────────────────────────────────────────────────────────┤
│ Tier 5: External Task Graph (Durable Frontier)              │ -> GitHub / Gitea Issues (to-tickets)
└─────────────────────────────────────────────────────────────┘

1. Intra-Session (Tier 1): Ephemeral working context managed via progressive disclosure.
2. Workspace Directives (Tier 2): Core guidelines in AGENTS.md and rules in .agents/rules/ (trigger: always_on).
3. Domain Knowledge (Tier 3): Living domain glossary in CONTEXT.md and immutable decisions in docs/adr/.
4. Session Bridge (Tier 4): Cold-start checkpoint saved to .scratch/handoff.md before exit. Rehydrated in new sessions via @handoff.md.
5. Durable Task Graph (Tier 5): External source of truth for work items managed via GitHub or Gitea issues.

🛡️ Lifecycle Hooks & Security

AAC integrates with the native Antigravity lifecycle hook engine configured in .agents/hooks.json:

1. Git Guardrails (PreToolUse)

Blocks destructive git commands before run_command executes:

# Cross-platform Node.js hook (Windows, macOS, Linux):
echo '{"toolCall":{"name":"run_command","args":{"CommandLine":"git push origin main"}}}' | node .agents/hooks/block-dangerous-git.cjs
# Output: {"decision":"deny","reason":"BLOCKED: 'git push origin main' matches dangerous git pattern '\\bgit\\s+push\\b'..."}

2. Quality Gate (Stop)

Prevents terminating an agent session if automated tests fail:

{
  "quality-gate": {
    "enabled": true,
    "Stop": [
      {
        "type": "command",
        "command": "node hooks/verify-on-stop.cjs",
        "timeout": 15
      }
    ]
  }
}

🔌 Model Context Protocol (MCP)

AAC natively supports workspace-scoped MCP servers with credential sandboxing.

Copy .agents/mcp_config.example.json to .agents/mcp_config.json (gitignored):

cp .agents/mcp_config.example.json .agents/mcp_config.json

Configure local Gitea (stdio) and remote GitHub (SSE) connections:

{
  "mcpServers": {
    "github": {
      "serverUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    },
    "gitea": {
      "command": "gitea-mcp",
      "args": ["-t", "stdio"],
      "env": {
        "GITEA_HOST": "https://gitea.com",
        "GITEA_ACCESS_TOKEN": "YOUR_GITEA_PAT"
      }
    }
  }
}

🧪 Verification & Testing

Every commit and installer is validated against a comprehensive automated test suite:

npm test

✔ frontmatter has valid Antigravity name and description
✔ description specifies what it does and when to invoke
✔ body specifies Antigravity research subagent and native tools
✔ artifact carries no placeholder markers
✔ CLI --version prints v5.0.0
✔ CLI --help prints usage banner
✔ CLI list displays skills count
✔ CLI doctor performs environment health checks
✔ CLI init never creates or overwrites package.json in target directory
✔ AGENTS.md remains strictly below 12000 characters limit
✔ memory-management rule exists with trigger: always_on
✔ CONTEXT.md living domain document exists at root
✔ ADR 0001 records 5-tier memory decision
✔ docs/agents configuration files exist and are populated
✔ gitignore correctly ignores .scratch contents and preserves .gitkeep
✔ session handoff template exists
✔ all 64 skills comply with Antigravity operational criteria
ℹ pass 17, fail 0, duration_ms 443

📜 License

Distributed under the MIT License. See LICENSE for more information.

Developed by Muhammad Rafael Ghifari (@rafaelghif) for the Google Antigravity Ecosystem.