refactor(docs): Refactor GEMINI.md file

AGENTS.md

@@ -0,0 +1,3 @@
+Always check @./GEMINI.md for the full instruction list.
+
+This file exists for compatibility with tools that look for AGENTS.md.

GEMINI.md

@@ -1,20 +1,25 @@
-**A2A specification:** https://a2a-protocol.org/latest/specification/
+# Agent Command Center
 
-## Project frameworks
-- uv as package manager
+## 1. Project Overview & Purpose
+**Primary Goal**: This is the Python SDK for the Agent2Agent (A2A) Protocol. It allows developers to build and run agentic applications as A2A-compliant servers. It handles complex messaging, task management, and communication across different transports (REST, gRPC, JSON-RPC).
+**Specification**: [A2A-Protocol](https://a2a-protocol.org/latest/specification/)
 
-## Code style and mandatory checks
-1. Whenever writing python code, write types as well.
-2. After making the changes run ruff to check and fix the formatting issues
-   ```
-   uv run ruff check --fix
-   uv run ruff format
-   ```
-3. Run mypy type checkers to check for type errors
-   ```
-   uv run mypy src
-   ```
-4. Run the unit tests to make sure that none of the unit tests are broken.
-  ```
-  uv run pytest
-  ```
+## 2. Technology Stack & Architecture
+
+- **Language**: Python 3.10+
+- **Package Manager**: `uv`
+- **Lead Transports**: FastAPI (REST/JSON-RPC), gRPC
+- **Data Layer**: SQLAlchemy (SQL), Pydantic (Logic/Legacy), Protobuf (Modern Messaging)
+- **Key Directories**:
+    - `/src`: Core implementation logic.
+    - `/tests`: Comprehensive test suite.
+    - `/docs`: AI guides.
+
+## 3. Style Guidelines & Mandatory Checks
+- **Style Guidelines**: Follow the rules in @./docs/ai/coding_conventions.md for every response involving code.
+- **Mandatory Checks**: Run the commands in @./docs/ai/mandatory_checks.md after making any changes to the code and before committing.
+
+## 4. Mandatory AI Workflow for Coding Tasks
+1. **Required Reading**: You MUST read the contents of @./docs/ai/coding_conventions.md and @./docs/ai/mandatory_checks.md at the very beginning of EVERY coding task.
+2. **Initial Checklist**: Every `task.md` you create MUST include a section for **Mandatory Checks** from @./docs/ai/mandatory_checks.md.
+3. **Verification Requirement**: You MUST run all mandatory checks before declaring any task finished.

docs/ai/coding_conventions.md

@@ -0,0 +1,21 @@
+### Coding Conventions & Style Guide
+
+Non-negotiable rules for code quality and style.
+
+1. **Python Types**: All Python code MUST include type hints. All function definitions MUST include return types.
+2. **Type Safety**: All code MUST pass `mypy` and `pyright` checks.
+3. **Formatting & Linting**: All code MUST be formatted with `ruff`.
+
+#### Examples:
+
+**Correct Typing:**
+```python
+async def get_task_status(task: Task) -> TaskStatus:
+    return task.status
+```
+
+**Incorrect (Do NOT do this):**
+```python
+async def get_task_status(task): # Missing type hints for argument and return value
+    return task.status
+```

docs/ai/mandatory_checks.md

@@ -0,0 +1,26 @@
+### Test and Fix Commands
+
+Exact shell commands required to test the project and fix formatting issues.
+
+1. **Formatting & Linting**:
+   ```bash
+   uv run ruff check --fix
+   uv run ruff format
+   ```
+
+2. **Type Checking**:
+   ```bash
+   uv run mypy src
+   uv run pyright src
+   ```
+
+3. **Testing**:
+   ```bash
+   uv run pytest
+   ```
+
+4. **Coverage**:
+Only run this command after adding new source code and before committing.
+   ```bash
+   uv run pytest --cov=src --cov-report=term-missing
+   ```