Antigravity Architect is the definitive Agent-First project engine. It is a modular, zero-dependency Python package that generates Living Repositories—complete development environments designed from the ground up to be self-describing, self-protecting, and self-evolving for AI coding agents like Gemini, Claude, and GPT-4.

Traditional scaffolding tools generate files and walk away. Antigravity generates an entire Intelligence Layer: a declarative governance system, a semantic repository map, autonomic memory management, background security sentinels, cross-repository context bridges, and a full suite of agent rules, workflows, and executable skills. The result is a repository that doesn't just contain code—it teaches the AI how to work on itself.

• Zero Runtime Dependencies: Built entirely on the Python standard library. No pip install surprises.
• Agent-First Architecture: Every generated file is designed to be consumed by an AI agent, not just a human developer.
• Modular Plugin System: Extend generation capabilities without touching the core engine.
• Cross-Platform Intelligence: Automatically adapts to Windows, macOS, and Linux environments.
• Protocol-Driven: All agent behavior is governed by a versioned manifest (protocol: 3.0.0) ensuring reproducibility and auditability.

git clone https://github.com/pkeffect/antigravity-architect.git
cd antigravity-architect
pip install -e .

# Interactive mode - guided step-by-step
antigravity-architect

# CLI one-liner
antigravity-architect --name my-project --stack python,react,docker

# With a brain dump specification file
antigravity-architect --name my-project --brain-dump ./specs.md --safe

# Apply a specialized blueprint
antigravity-architect --name my-api --stack python --blueprint fastapi

# Preview what would be generated without writing files
antigravity-architect --name my-project --stack python --dry-run

Open the generated folder in any AI-ready IDE (VS Code with Gemini Code Assist, Cursor, Windsurf, or Google Project IDX) and type:

"Read BOOTSTRAP_INSTRUCTIONS.md and start."

The v3.0 release transforms every generated repository into a self-describing, declarative intelligence layer for AI agents.

Every generated project includes a tool permission matrix that explicitly restricts what an AI agent can and cannot do. Tools are classified into three tiers:

• Safe: Read-only operations (e.g., list_dir, view_file, grep_search)
• Sensitive: Write operations requiring caution (e.g., write_to_file, run_command)
• Restricted: Destructive operations with hard limits (e.g., delete_file with a configurable max deletion count)

Built-in guardrails prevent agents from modifying protected paths (.git/, .venv/, private/).

A pre-computed, human-readable YAML digest of the entire repository's structure and intent. Instead of burning tokens on recursive directory listing (ls -R), agents read a single file to understand what every directory and key file does. Generated automatically during project creation.

AI agents accumulate task history in .agent/memory/scratchpad.md. Rule 11 enforces an automated compaction protocol:

• Trigger: When scratchpad.md exceeds 100 lines or 10 completed tasks.
• Action: Summarize completed tasks into a high-level history block, consolidate sub-tasks, and purge stale notes.
• Goal: Maintain a high signal-to-noise ratio in the agent's context window.

Automatically discovers sibling projects in the parent directory and scans for global knowledge lakes at ~/.antigravity/knowledge_lake/. The generated context/links.md file provides cross-repository architectural syncing, enabling agents to understand the broader ecosystem a project lives in.

The .agent/manifest.json tracks repository maturity through explicit lifecycle states:

• INIT: Freshly generated; agent operates with maximum caution.
• STABLE: Production-ready; agent can operate with full autonomy.
• ARCHIVED: Read-only; agent should not make modifications.

All generated Markdown templates include machine-readable <!-- ID: [name] --> HTML comment tags in their headers. This enables LLMs to surgically extract or modify specific documentation sections without parsing entire files.

Antigravity operates on a dynamic sidecar plugin architecture managed by the PluginManager class.

1. Auto-Discovery: On startup, the PluginManager scans for any Python file matching the ag_plugin_*.py naming convention.
2. Lifecycle Hooks: Plugins register hooks (e.g., post_generation) that execute at specific points in the generation pipeline.
3. Graceful Degradation: If a plugin's dependencies are missing, it logs a warning and skips execution—never crashing the engine.
4. User-Extensible: Drop a new ag_plugin_*.py into your project's ag_plugins/ directory and it will be loaded automatically.

Blueprints are pre-configured project templates that override default directory structures, inject extra dependencies, and apply domain-specific rules.

Fetch any community blueprint directly from a Git URL:

antigravity-architect --name my-app --blueprint https://github.com/user/my-custom-blueprint

The engine clones the repository, reads the antigravity_blueprint.json manifest, and merges the blueprint's directories, files, and rules with the standard Antigravity output.

Every generated project includes a layered, priority-ordered rule system in .agent/rules/. Rules are conditionally loaded based on the detected tech stack—a Python project won't receive Node.js linting rules.

The _generate_priority_list() function dynamically reorders and filters rules based on the project's tech stack. Security-heavy stacks (e.g., docker, cloud) automatically promote security rules to higher priority. Minimal stacks suppress verbose rules to reduce token overhead.

The --personality flag adjusts the agent's behavioral tone:

• startup: Favors speed and iteration over perfection.
• enterprise: Enforces strict compliance, extensive documentation, and change management.
• minimal: Strips non-essential rules for lightweight projects.

Pre-built, actionable routines that agents can invoke by command:

Skills are executable Python scripts that agents can run directly for automation tasks:

A daemon script that watches critical repository files (.env, security rules, cli.py, sentinel.py itself). If unauthorized modifications are detected, it triggers an immediate --doctor audit with auto-fix.

Generate a Software Bill of Materials in CycloneDX 1.4 format:

antigravity-architect --sbom ./my-project

The AntigravityGovernance.generate_sbom() method scans requirements.txt for pinned dependencies and produces a machine-readable JSON SBOM.

AntigravityGovernance.scan_licenses() scans dependency files for known GPL-incompatible licenses and flags potential conflicts before they become legal issues.

AntigravityGovernance.validate_env_schema() enforces .env.schema compliance: if a project defines required environment variables in .env.schema, the governance module verifies they exist in the actual .env file.

The Assimilator transforms unstructured specification documents into structured, categorized agent knowledge.

antigravity-architect --name my-project --brain-dump ./specs.md

1. Archive: The raw brain dump is saved to context/raw/master_brain_dump.md for reference.
2. Tech Detection: detect_tech_stack() scans the text using primary keywords and 50+ aliases (e.g., "Django" → python, "Kubernetes" → docker) to identify the project's technology stack.
3. Deep-Dive Generation: build_tech_deep_dive() produces a docs/TECH_STACK.md with primary technologies, contextual observations (API surfaces, security requirements, database layers), and technical debt tracking.
4. Heuristic Classification: Each section is scored against keyword rules for rules, workflows, skills, and docs to determine the correct .agent/ subdirectory.
5. Distribution: Classified sections are written to their appropriate locations with <!-- Auto-Assimilated Source --> provenance tags.

Validate and repair any Antigravity-generated project's structural health:

# Diagnose issues
antigravity-architect --doctor ./my-project

# Diagnose and auto-fix
antigravity-architect --doctor ./my-project --fix

Doctor mode checks for:

• Missing .agent/ directories (rules, workflows, skills, memory)
• Missing or corrupted critical files (manifest, identity rule, security rule)
• Structural drift from the expected Antigravity protocol
• Auto-generates missing files from templates when --fix is applied

Save and reuse complex CLI configurations:

# Save current arguments as a preset
antigravity-architect --name api --stack python,docker --blueprint fastapi --save-preset my-api

# Load and run a saved preset
antigravity-architect --preset my-api

# List all saved presets
antigravity-architect --list-presets

Presets are stored in ~/.antigravity/presets/ as JSON files, enabling team-wide standardization of project generation.

The AntigravityEngine provides hardened, cross-platform file I/O:

• Path Traversal Protection: sanitize_name() strips ../, ./, null bytes, and special characters from all project names.
• SHA-256 Smart Overwrite: write_file() computes content hashes before writing. If the file hasn't changed, the write is skipped entirely—preventing unnecessary Git diffs.
• Unified Diff Analysis: get_diff() produces unified diffs for drift detection in Doctor mode.
• Lazy Template Loading: The LazyTemplateDict class defers template file I/O until first access, reducing startup time for large template directories.

usage: antigravity-architect [-h] [--version] [--name NAME] [--stack STACK]
                             [--brain-dump BRAIN_DUMP] [--safe] [--dry-run]
                             [--templates TEMPLATES] [--doctor PATH] [--fix]
                             [--list-keywords] [--license {mit,apache,gpl}]
                             [--blueprint BLUEPRINT] [--save-preset NAME]
                             [--preset NAME] [--list-presets]
                             [--list-blueprints]
                             [--ide {jetbrains,neovim,zed,fleet}]
                             [--ci {gitlab,azure}] [--docker]
                             [--personality {startup,enterprise,minimal}]
                             [--sbom PATH]

my-project/
├── .agent/                             # 🤖 THE AGENT BRAIN
│   ├── manifest.json                   #   Protocol version, capabilities, lifecycle state
│   ├── tools.json                      #   Declarative tool permissions (safe/sensitive/restricted)
│   ├── rules/                          #   Behavioral constraints and coding standards
│   │   ├── 00_identity.md              #     Agent persona and primary safety directives
│   │   ├── 01_tech_stack.md            #     Dynamically generated stack-specific conventions
│   │   ├── 02_security.md              #     OWASP foundations and secret protection
│   │   ├── 03_git.md                   #     Conventional commits and branch strategies
│   │   ├── 04_reasoning.md             #     Chain-of-thought and step-by-step logic
│   │   ├── 05_architecture.md          #     Modular design and separation of concerns
│   │   ├── 05_environment.md           #     OS-specific behaviors and adaptations
│   │   ├── 06_ux.md                    #     User experience guidelines
│   │   ├── 07_security_expert.md       #     Advanced threat modeling persona
│   │   ├── 08_boundaries.md            #     Agent autonomy limits and safeguards
│   │   ├── 09_cross_repo.md            #     Multi-repository context sharing
│   │   ├── 10_evolution.md             #     Self-improvement and tech debt tracking
│   │   ├── 11_self_learning.md         #     Autonomic compaction protocol
│   │   └── 99_model_dispatch.md        #     Model-specific optimizations
│   ├── workflows/                      #   Actionable agent routines
│   │   ├── plan.md                     #     Task breakdown and context gathering
│   │   ├── bootstrap.md                #     Full project initialization
│   │   ├── commit.md                   #     Conventional commit workflow
│   │   ├── review.md                   #     Code review with quality gates
│   │   ├── save.md                     #     Checkpoint state to memory
│   │   ├── sync.md                     #     Cross-repo context synchronization
│   │   ├── evolve.md                   #     Background refactoring identification
│   │   ├── doctor.md                   #     Structural health validation
│   │   ├── compress.md                 #     Memory compaction trigger
│   │   └── help.md                     #     Command reference
│   ├── skills/                         #   Executable automation scripts
│   │   ├── bridge/SKILL.md             #     Inter-agent communication handler
│   │   ├── secrets_manager/SKILL.md    #     Entropy-based secret scanner
│   │   ├── env_context/SKILL.md        #     Dynamic OS and environment detection
│   │   └── git_automation/SKILL.md     #     Automated Git operations
│   └── memory/                         #   Agent state tracking
│       ├── scratchpad.md               #     Short-term focus, active tasks, immediate roadmap
│       └── evolution.md                #     Long-term tech debt and refactoring goals
├── AGENT_MAP.yaml                      # 🗺️ Semantic repository digest for zero-cost discovery
├── BOOTSTRAP_INSTRUCTIONS.md           # 📖 The first file the AI reads to initialize
├── context/                            # 🌉 Neural Bridge
│   ├── raw/                            #     Archived brain dump source material
│   └── links.md                        #     Sibling project and knowledge lake references
├── docs/                               # 📚 Architectural documentation
│   ├── imported/                       #     Assimilated external specifications
│   ├── TECH_STACK.md                   #     Auto-generated technology deep-dive
│   └── SBOM.json                       #     CycloneDX software bill of materials
├── scripts/                            # 🛡️ DevOps utilities
│   └── sentinel.py                     #     Background file modification watchdog
├── .github/                            # 🐙 GitHub Actions and templates (via plugin)
│   ├── workflows/ci.yml                #     Automated CI/CD pipeline
│   ├── ISSUE_TEMPLATE/                 #     Bug report and feature request templates
│   └── dependabot.yml                  #     Automated dependency updates
├── .vscode/                            # 🛠️ VS Code workspace (via plugin)
│   ├── settings.json                   #     Hardened editor settings
│   └── extensions.json                 #     Recommended extensions for the stack
├── .devcontainer/                      # 📦 Dev Containers configuration
├── src/                                # 💻 Primary source code
├── tests/                              # 🧪 Test suite scaffolding
├── .gitignore                          #     Stack-aware exclusion patterns
├── .env.example                        #     Environment variable template
├── .pre-commit-config.yaml             #     Pre-commit hook configuration
├── pyproject.toml                      #     Python package metadata (or equivalent)
├── docker-compose.yml                  #     Container orchestration (if --docker)
├── README.md                           #     Professional README with badges
├── CHANGELOG.md                        #     Versioned change log
├── CONTRIBUTING.md                     #     Contributor guidelines
├── CODE_OF_CONDUCT.md                  #     Community standards
├── SECURITY.md                         #     Vulnerability reporting policy
├── AUDIT.md                            #     Security and quality audit report
└── LICENSE                             #     MIT, Apache, or GPL license

src/antigravity_architect/
├── __init__.py                         # Package version exposure
├── cli.py                              # CLI entrypoint, argument parsing, interactive/doctor modes
├── core/
│   ├── __init__.py                     # Core module exports
│   ├── assimilator.py                  # Brain dump parsing, tech detection, heuristic classification
│   ├── builder.py                      # Dynamic config generators and project orchestration
│   ├── engine.py                       # Sanitized file I/O, presets, blueprints, diffing
│   └── governance.py                   # SBOM generation, license scanning, env schema validation
├── plugins/
│   ├── __init__.py                     # Plugin module exports
│   ├── manager.py                      # Dynamic plugin discovery, lifecycle hooks, error isolation
│   ├── ag_plugin_vscode.py             # VS Code / Cursor workspace generator
│   ├── ag_plugin_github.py             # GitHub Actions, templates, and Dependabot
│   ├── ag_plugin_gitea.py              # Gitea CI pipeline generator
│   └── ag_plugin_idx.py                # Google Project IDX environment generator
└── resources/
    ├── __init__.py                     # Resource module exports
    ├── constants.py                    # VERSION, directory names, tech aliases, classification rules
    ├── templates.py                    # Lazy template loader and common template accessors
    └── templates/                      # Raw template files
        ├── rules/          (14 files)  #   Agent behavioral rule templates
        ├── workflows/      (10 files)  #   Agent workflow templates
        ├── skills/         (4 dirs)    #   Agent skill SKILL.md templates
        ├── blueprints/     (14 files)  #   Project blueprint JSON definitions
        ├── memory/                     #   Agent memory file templates
        ├── agent/                      #   Manifest and tools.json templates
        ├── common/         (13 files)  #   Shared templates (gitignore, licenses, sentinel, etc.)
        ├── docs/                       #   Documentation templates
        ├── ide/                        #   IDE configuration templates
        └── pipelines/                  #   CI/CD pipeline templates

The package is backed by 111 passing tests across 8 test modules with 100% code coverage.

# Install development dependencies
pip install -e .[dev]

# Run the full suite
pytest tests/ -v

# Run with coverage reporting
pytest tests/ --cov=antigravity_architect --cov-report=term-missing

# Linting
ruff check src/antigravity_architect/

# Type checking
mypy src/antigravity_architect/

# Formatting
black --check src/antigravity_architect/

Traditional scaffolding generates dead code. Once the tool runs, you're on your own. There's no ongoing governance, no health checks, no way for an AI to understand how to work on the project. Antigravity generates the code and the instruction manual for the AI that will maintain it.

IDE-level AI assistants are powerful but operate on generic, global settings. They don't understand your project's specific security posture, architectural boundaries, or quality requirements. Antigravity embeds those constraints inside the repository itself, so any agent—regardless of IDE—must conform to the project's rules.

Agent frameworks orchestrate what agents do at runtime. Antigravity Architect prepares where agents work. They are complementary: use Antigravity to generate the governed, self-describing repository, then use any framework to run agents within it.

This project was built using a hybrid AI development workflow. The following AI systems contributed significantly to the architecture, code, testing, and documentation:

We welcome community blueprints and core engine improvements! Please review our Contribution Guide to understand our "Agent-First" development workflow and branch strategies.

This project is licensed under the MIT License - see the LICENSE file for details.