From 93ae9f3de84e63579b003d066e8fbc8b84d60f8b Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 17 Mar 2026 15:58:53 +0000 Subject: [PATCH 1/4] Refactor(docs): Refactor GEMINI.md file --- AGENTS.md | 3 +++ GEMINI.md | 42 ++++++++++++++++++++--------------- docs/ai/coding_conventions.md | 21 ++++++++++++++++++ docs/ai/mandatory_checks.md | 26 ++++++++++++++++++++++ 4 files changed, 74 insertions(+), 18 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/ai/coding_conventions.md create mode 100644 docs/ai/mandatory_checks.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..05b234a01 --- /dev/null +++ b/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. diff --git a/GEMINI.md b/GEMINI.md index e5b7cc586..f625a7de1 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,20 +1,26 @@ -**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 use `view_file` to 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. diff --git a/docs/ai/coding_conventions.md b/docs/ai/coding_conventions.md new file mode 100644 index 000000000..4a90764e6 --- /dev/null +++ b/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 and linted with `ruff`. + +#### Examples: + +**Correct Typing:** +```python +async def get_task_status(task: Task) -> TaskStatus: + return task.status +``` + +**Incorrect (Do NOT do this):** +```python +def get_task(task): # Missing type hints + return task.status # Potential None return without handling +``` diff --git a/docs/ai/mandatory_checks.md b/docs/ai/mandatory_checks.md new file mode 100644 index 000000000..a64d6b54a --- /dev/null +++ b/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 + ``` From 985254ed292eb134907b576d8963f133b117fefb Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 17 Mar 2026 16:06:26 +0000 Subject: [PATCH 2/4] fix --- docs/ai/coding_conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai/coding_conventions.md b/docs/ai/coding_conventions.md index 4a90764e6..20df34aa5 100644 --- a/docs/ai/coding_conventions.md +++ b/docs/ai/coding_conventions.md @@ -4,7 +4,7 @@ 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 and linted with `ruff`. +3. **Formatting & Linting**: All code MUST be formatted with `ruff`. #### Examples: From 62743b13a1a57ef7517293e64a3da008b7d40282 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 17 Mar 2026 16:08:37 +0000 Subject: [PATCH 3/4] fix formating --- GEMINI.md | 1 - docs/ai/coding_conventions.md | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index f625a7de1..eace138a5 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -19,7 +19,6 @@ - **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 use `view_file` to 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. diff --git a/docs/ai/coding_conventions.md b/docs/ai/coding_conventions.md index 20df34aa5..2d1f9490c 100644 --- a/docs/ai/coding_conventions.md +++ b/docs/ai/coding_conventions.md @@ -16,6 +16,6 @@ async def get_task_status(task: Task) -> TaskStatus: **Incorrect (Do NOT do this):** ```python -def get_task(task): # Missing type hints - return task.status # Potential None return without handling +async def get_task_status(task): # Missing type hints for argument and return value + return task.status ``` From 588d1deb17cced73d2a0ed707a851e1116df89ff Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 17 Mar 2026 16:21:20 +0000 Subject: [PATCH 4/4] remove redundant "view_file" from GEMINI.md --- GEMINI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GEMINI.md b/GEMINI.md index eace138a5..aaab0bf66 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -20,6 +20,6 @@ - **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 use `view_file` to read the contents of @./docs/ai/coding_conventions.md and @./docs/ai/mandatory_checks.md at the very beginning of EVERY coding task. +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.