# Antigravity Swarm (v3.5)

A professional multi-agent orchestration system built on the native **Antigravity engine** (invoked via `agy` or `gemini`), leveraging **Gemini 3.5/3.1** and **Model Context Protocol (MCP)** integration.

> [!NOTE]
> **Architecture Migration Notice:** This workspace has been fully migrated from the legacy `.gemini/` CLI-centric configuration format to the modern `.agents/` Antigravity architecture.

## 🚀 Overview

This repository houses the core of the **Antigravity Swarm**, a "Hub-and-Spoke" agentic team optimized for software engineering, deep research, and architectural design. The swarm utilizes advanced reasoning (Thinking mode), native subagent delegation, and massive context caching to deliver surgical code changes and verifiable results.

## 🧠 Swarm Architecture (Spec-Driven Development)

The swarm operates under a rigid **Spec-Driven Development (SDD)** pipeline based on `github/spec-kit` standards:

1. **Research & Requirements (`oracle`)**: Uses external tools (Tavily/Exa) and internal help to establish the project `constitution.md` and `spec.md`.
2. **Design & Planning (`prometheus`)**: Consumes the specifications and designs the technical implementation in `plan.md` and a checklist of user stories in `tasks.md`.
3. **Surgical Implementation (`junior` / `jules` / `frontend` / `stitch`)**: Execution agents who implement features step-by-step. `junior` and `jules` focus on backend/logic, while `frontend` and `stitch` coordinate visual styling and design-to-code compiler pipelines.
4. **Validation & Audit (`quality-validator`)**: Final gatekeeper. Audits all changes against specifications and runs the test suite.
5. **Codebase Exploration (`librarian`)**: Maps the project structure, performs semantic searches, and assists in telemetry diagnostics.

## ☁️ Jules Integration (Cloud Coding Agent)

Previously, the swarm used a legacy `julesServer` MCP server python stub as a placeholder that always returned "PENDING". This has been replaced with a real integration with **Google's autonomous cloud coding agent** ([Jules](https://jules.google)).

### How it works within the Swarm:
1. **Dispatcher Pattern**: The local `jules` subagent no longer clones repositories or edits code directly. Instead, it acts as a dispatcher sending tasks directly to Google's cloud infrastructure using the native `jules` CLI (installed at `/usr/bin/jules` with credentials at `/root/.jules/cache/`).
2. **Action-Context-Verification (ACV) Specification**: The CEO briefs `jules` using a mandatory ACV-formatted prompt (Action, Context, Verification) defining clear deliverables, dependencies, and validation criteria.
3. **Execution in Cloud VM**: Jules executes the task within its own remote cloud environment, performing deep analysis and multiline codebase refactors. You can monitor active sessions via:
   ```bash
   jules remote list --session
   ```
4. **Pulling the Results**: When the task is complete, the `jules` subagent pulls the code, applies the patch locally, or opens a GitHub Pull Request:
   ```bash
   jules remote pull --session <id> --apply
   ```
For more information, refer to the [official Jules documentation](https://jules.google/docs) and [CLI reference](https://jules.google/docs/cli/reference).

## 🛠️ Key Technologies & Configurations

- **Engine**: [Antigravity CLI / Gemini CLI](https://antigravity.google/docs/)
- **Protocol**: [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- **Jules Cloud Integration**: Google's autonomous coding agent ([Jules](https://jules.google)). Legacy fake Python stub (`julesServer`) has been completely replaced with a direct dispatcher calling the native `jules` CLI.
- **Features**:
  - **Cognitive Routing**: Task complexity routing to appropriate subagent (oracle/prometheus for deep, junior/librarian for fast).
  - **Context Compression**: Subagent responses compressed before passing to next agent to preserve context window.
  - **Telemetry Logging**: Centralized error and execution monitoring via `.agents/telemetry.log`.
  - **Policy Isolation**: Subagent tool constraints are defined using the Antigravity Policy Engine.
    > [!IMPORTANT]
    > **TOML Policy Engine Bug:** Due to a known issue ([issue #18186](https://github.com/google-gemini/gemini-cli/issues/18186)), workspace-level policies inside `.agents/policies/` are bypassed. Policies must be placed at the User-level: `~/.gemini/policies/` to remain active.

## 📂 Project Structure

- `.agents/agents/`: Native agent registration files (`junior.md`, `prometheus.md`, etc.).
- `.agents/skills/`: Native skill definitions (Custom logic, cognitive router, context manager).
- `Gemini_Swarm_Core/`: Sub-project containing Swarm Orchestrator rules, status boards, specs, and execution files.
- `Gemini_Swarm_Core/swarm/`: Reusable agent instructions and role prompts.
- `Gemini_Swarm_Core/GEMINI.md`: Root configuration and routing logic for the orchestrator (CEO).
- `Gemini_Swarm_Core/SWARM_ROADMAP.md`: Master reference map and project evolution roadmap.

## 🔧 Setup & Operations

1. **Authentication & Profile Setup**:
   Ensure your `~/.gemini/config.toml` includes your API credentials and preferred model settings.
2. **Checking Model Limits**:
   To inspect the limits, usage quotas, and configurations of active models, run:
   ```bash
   gemini model
   # or inside the interactive CLI session:
   /model
   ```
3. **Running the Swarm**:
   Start the interactive CLI session:
   ```bash
   agy
   ```
   Or delegate tasks using the agy dynamic subagent pattern:
   ```
   # Example: CEO delegating search to built-in research agent
   invoke_subagent("research", task="Locate all database connection references.")

   # Or define a custom subagent first:
   define_subagent(name="librarian", system_prompt="...", tools=["grep_search", "glob"])
   invoke_subagent("librarian", task="Locate all database connection references.")
   ```

---

*Built with ❤️ using Gemini 3.5 and Antigravity principles.*