@rafaelghif/aac-core

v5.3.1

Published

12 hours ago

Autonomous engineering framework for Google Antigravity

0High
0Medium
0Low

aac aac-core antigravity antigravity-agents-core google-antigravity agentic-ai gemini gemini-flash pair-programming mcp skills

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

⚡ 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-core 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

Upgrading an Existing Workspace

If you are already running an earlier version of AAC (e.g. v5.0.3 or v5.1.0), safely update core rules, skills, plugins, and lifecycle hooks with zero risk to your custom domain work:

# Universal NPX (recommended):
npx @rafaelghif/aac-core upgrade

# Windows PowerShell:
powershell -ExecutionPolicy Bypass -File install.ps1 -Upgrade

# Linux / macOS:
bash install.sh --upgrade

[!TIP] Strict Upgrade Protections:
🔒 Domain Glossary & Architecture: Existing CONTEXT.md is strictly preserved and never overwritten.
🔒 Workspace Secrets: Existing .agents/mcp_config.json API tokens and MCP settings remain untouched.
🔄 Smart Hooks Merging: Updates framework lifecycle hooks while preserving all user-added custom hooks and toggle states (enabled: false/true).
📁 Scratchpad Continuity: Existing .scratch/ session handoffs are fully preserved.
🛡️ Zero Pollution: Guaranteed never to create or mutate package.json in your project.

[!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

📜 Always-On Operational Rules

AAC enforces deterministic engineering quality, communication brevity, and security through modular rules loaded into Antigravity context on every turn (trigger: always_on):

| Rule | Protocol / Philosophy | Core Directives | Primary File | | :--- | :--- | :--- | :--- | | architecture-and-flow | Techstack, Topology & Flow Protocol | Mandatory discovery of workspace manifests, Clean/Hexagonal boundaries, deep module seams, zero cyclic imports, and end-to-end data/execution flow tracing. | architecture-and-flow.md | | production-integrity | Zero Assumptions & Anti-Mock Standard | Strict ban on dummy/fake/mock data in production code (src/, lib/, app/). Zero speculation; mandatory clarification via /grill-me or ask_question; test fixture isolation. | production-integrity.md | | ponytail | 7-Rung Minimalist Code Ladder | Laziest senior dev mode: YAGNI → Existing Helpers → Standard Library → Platform Native → Installed Dep → One-Liner → Minimal Diff. Fix root causes, not symptoms. | ponytail.md | | caveman | Ultra-Compressed Communication | Eliminates conversational fluff, polite filler, and tool narration. Delivers 100% technical substance, exact code, commands, and file links. | caveman.md | | coding-standards | Production Code Quality & SRP | Single Responsibility Principle, fail-fast boundary validation, explicit error handling, and targeted single-block file modifications. | coding-standards.md | | git-workflow | Conventional Commits & Atomic History | Enforces conventional commit prefixes (feat:, fix:, chore:, etc.) and single-unit atomic changes without mixing cosmetic and functional diffs. | git-workflow.md | | memory-management | 5-Tier Context Isolation | Manages working context across 5 tiers: intra-session, workspace directives, domain models, cross-session handoff (.scratch/handoff.md), and issue task graphs. | memory-management.md |

📂 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 Git, GitHub, Gitea, and Database MCPs
│   ├── plugins/                       # Workspace plugins packaging tools & sidecars
│   │   └── workspace-integrations/    # Workspace integrations bundle
│   ├── rules/                         # Workspace-level rules with 'trigger: always_on'
│   │   ├── architecture-and-flow.md   # Dynamic techstack discovery, topology & flow protocol
│   │   ├── 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
│   │   ├── memory-management.md       # 5-tier memory hierarchy & cross-session protocol
│   │   ├── ponytail.md                # 7-rung minimalist code ladder (YAGNI to one-liners)
│   │   └── production-integrity.md    # Zero assumptions, anti-dummy policy & production realism
│   └── 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/                        # Master skill directory, issue tracker, domain layout
│   │   ├── skill-directory.md         # Canonical 64-skill routing directory & quality manifesto
│   │   ├── domain.md                  # Domain docs layout and consumption rules
│   │   ├── issue-tracker.md           # Issue tracker configuration standards
│   │   └── triage-labels.md           # Canonical 5-role triage label definitions
│   ├── 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)
│   └── lifecycle-guardrails-and-engines.test.mjs # Universal hook and engine test suite
├── 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 (64 Verified Skills)

Skills extend agent capabilities via progressive disclosure: only names and descriptions are exposed in the initial context. When a user intent or slash command matches, the agent reads the target SKILL.md directly via view_file.

For full operational procedures, decision trees, and quality invariants, see skill-directory.md.

🧠 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)
└─────────────────────────────────────────────────────────────┘

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

🛡️ Lifecycle Hooks & Security Guardrails

AAC integrates with the native Antigravity lifecycle hook engine configured in .agents/hooks.json across PreInvocation, PreToolUse, and Stop events:

1. Git Command Guardrail (`PreToolUse`)

Intercepts run_command to block destructive git operations (git push, git reset --hard, git clean -f, git branch -D, git checkout .) before terminal execution using cross-platform Node.js (hooks/block-dangerous-git.cjs).

2. Security & Secret Scanner (`PreToolUse`)

Intercepts run_command, write_to_file, and replace_file_content. Blocks destructive commands and scans content for exposed credentials (API tokens, AWS keys, private keys, high-entropy secrets).

3. Quality Code & Production Integrity Guard (`PreToolUse`)

Intercepts write_to_file and replace_file_content to enforce production-integrity.md. Blocks fake tokens, dummy IDs, throw new Error("stub"), placeholder API URLs, and incomplete TODO stubs in production files, while permitting fixtures in test folders (tests/, *.test.*).

4. Context Rehydration & Memory Engine (`PreInvocation`)

Fires before model invocation returning { injectSteps: [{ ephemeralMessage: "..." }] } to rehydrate cold-start context from .scratch/handoff.md and track active session frontiers.

5. Universal Quality Gate (`Stop`)

Dynamically detects the host workspace's native test runner (npm test, pytest, go test ./..., cargo test, make test) and executes verification before session termination. If tests fail, returns {"decision": "continue"} to prevent concluding turns with regressions.

6. Automated Code Reviewer & Complexity Analyzer (`Stop`)

Evaluates git diff against coding standards, Fowler smells, and deep module ratios. Flags shallow wrappers and high-complexity functions before termination.

7. Task Orchestration & Wave Planner (`Stop`)

Calculates independent parallel execution waves for DAG tasks defined in .scratch/tasks.json using topological sorting, alerting if tasks remain incomplete at model stop.

8. Session Continuity & Auto-Handoff Guard (`Stop`)

Guards cross-session context continuity by automatically synthesizing a structured handoff document into .scratch/handoff.md whenever uncommitted code modifications are detected upon termination or step limits (max_steps_exceeded).

🛠️ CLI Subcommands & Tooling

AAC includes a complete command-line toolkit for local development and CI/CD automation:

# Security & secret scanning
npx @rafaelghif/aac-core scan [dir]

# Production realism & anti-dummy check
npx @rafaelghif/aac-core quality [dir]

# Multi-axis diff review (Standards, Security, Ponytail)
npx @rafaelghif/aac-core review

# Codebase metrics & deep module analyzer
npx @rafaelghif/aac-core analyze [dir]

# Task graph & wave planner (.scratch/tasks.json)
npx @rafaelghif/aac-core tasks summary
npx @rafaelghif/aac-core tasks waves
npx @rafaelghif/aac-core tasks next
npx @rafaelghif/aac-core tasks add <id> <title> [dep1,dep2]
npx @rafaelghif/aac-core tasks update <id> <status> [notes]

# 5-tier memory status, snapshot, and rehydration
npx @rafaelghif/aac-core memory status
npx @rafaelghif/aac-core memory snapshot
npx @rafaelghif/aac-core memory rehydrate

# Diagnostics & compliance audits
npx @rafaelghif/aac-core doctor
npx @rafaelghif/aac-core audit
npx @rafaelghif/aac-core list

🔌 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 Git, GitHub, Gitea, and database MCP connections:

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "gitea": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "gitea/gitea-mcp:v0.1.0"],
      "env": {
        "GITEA_HOST": "${GITEA_HOST}",
        "GITEA_ACCESS_TOKEN": "${GITEA_TOKEN}"
      }
    },
    "postgres": {
      "command": "bash",
      "args": [
        "-c",
        "npx -y @modelcontextprotocol/server-postgres postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT_PG}/${DB_NAME}"
      ]
    },
    "mysql": {
      "command": "bash",
      "args": [
        "-c",
        "npx -y mcp-server-mysql mysql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT_MYSQL}/${DB_NAME}"
      ]
    },
    "mssql": {
      "command": "bash",
      "args": [
        "-c",
        "npx -y @microsoft/mcp-sql-server \"Server=${DB_HOST},${DB_PORT_MSSQL};Database=${DB_NAME};User Id=${DB_USER};Password=${DB_PASSWORD};Encrypt=True;TrustServerCertificate=True;\""
      ]
    }
  }
}

🧪 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
✔ SKILL.md has valid frontmatter
✔ SKILL.md states the binding honesty rules
✔ SKILL.md covers the cavemem_offload move
✔ SKILL.md closes the longitudinal outcome loop honestly
✔ SKILL.md never turns a behavioral finding into an imperative
✔ SKILL.md has no placeholders
✔ CLI --version prints v5.3.1
✔ 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
﹣ install.ps1 scaffolds workspace with zero package.json pollution
✔ install.sh scaffolds workspace with zero package.json pollution
✔ lifecycle hook block-dangerous-git.cjs blocks dangerous git commands
✔ lifecycle hook verify-on-stop.cjs executes quality gate on model_stop
✔ lifecycle hook verify-on-stop.cjs returns continue when tests fail
✔ lifecycle hook handoff-reminder.cjs guards session continuity on model_stop
✔ CLI upgrade updates framework rules and directives while strictly preserving user CONTEXT.md and secrets
﹣ install.ps1 -Upgrade updates framework files while preserving CONTEXT.md
✔ install.sh --upgrade updates framework files while preserving CONTEXT.md
✔ distribution package contains zero hardcoded local machine paths
✔ security-scanner hook blocks dangerous commands and leaked secrets
✔ quality-guard hook enforces anti-dummy/mock policy on production files
✔ task-orchestrator computes DAG topological waves and handles dependencies
✔ code-analyzer accurately computes cyclomatic complexity and deep module ratio
✔ memory-engine tracks 5 tiers and creates snapshots
✔ CLI exposes new subcommands: scan, quality, review, analyze, tasks, memory
✔ code-analyzer detectTechStack detects workspace manifests, frameworks, and architecture
✔ quality-guard catches multi-language stubs in Python, Rust, and Go
✔ all local markdown links across repository resolve to existing files
✔ AGENTS.md, rules, and skills cross-references are synchronized
✔ AGENTS.md remains strictly below 12000 characters limit
✔ production-integrity rule exists with trigger: always_on
✔ memory-management rule exists with trigger: always_on
✔ architecture-and-flow 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
ℹ tests 45
ℹ pass 43
ℹ fail 0
ℹ skipped 2

📜 License

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme