Skip to content

docs: update diagrams, docs and instructions#289

Merged
yarolegovich merged 2 commits intomainfrom
yarolegovich/ai-docs
Mar 20, 2026
Merged

docs: update diagrams, docs and instructions#289
yarolegovich merged 2 commits intomainfrom
yarolegovich/ai-docs

Conversation

@yarolegovich
Copy link
Copy Markdown
Member

@yarolegovich yarolegovich commented Mar 20, 2026

  • Made AGENTS.md the primary model instructions file.
  • Added ./docs/ai/REQUEST_PROCESSING.md which is actually a very high-quality description of the current execution concurrency design decisions. It was derived from an exported session with a long exploration of a test race condition done by the model.
  • Refreshed an outdated diagram of local task execution.
  • Pulled a new diagram from this discussion.
  • Added a diagram to showcase how optimistic concurrency control works.

As an experiment:

  • Merged TESTING.md into the primary instructions file and instructed model to follow red-green-blue tdd.
  • Added an instruction for creating new files under ./docs/ai/ after deriving insights about the codebase.
  • Added an instruction for adding new entries to AGENTS.md based on user follow-ups.

@yarolegovich yarolegovich requested review from a team and ishymko March 20, 2026 13:28
@gemini-code-assist
Copy link
Copy Markdown
Contributor

gemini-code-assist bot commented Mar 20, 2026

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the project's documentation, particularly for AI agents and system concurrency. It centralizes agent instructions, introduces a detailed explanation of request processing and optimistic concurrency control, and updates system diagrams for clarity. These changes aim to improve understanding of complex system behaviors and streamline the development process for AI-driven features.

Highlights

  • Documentation Centralization: The AGENTS.md file has been promoted to the primary instruction file, consolidating various guidelines including general instructions, code style, and test writing, and deprecating GEMINI.md and TESTING.md.
  • Concurrency Model Documentation: A new, high-quality document, docs/ai/REQUEST_PROCESSING.md, was added to provide a detailed explanation of the server's execution concurrency design decisions, covering local and cluster modes, and optimistic concurrency control.
  • Diagram Updates: Outdated diagrams for local task execution were refreshed, and new Mermaid diagrams illustrating distributed execution and optimistic concurrency control were introduced for better clarity.
  • Development Workflow Guidance: New instructions were added for following a red-green-blue TDD approach, creating new documentation under ./docs/ai/ after deriving insights, and updating AGENTS.md with 'AI learnings' based on user feedback.
  • Performance Tuning: The defaultBufferSize for the internal event pipe was reduced from 1024 to 256, potentially optimizing memory usage or responsiveness in certain scenarios.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

@yarolegovich yarolegovich requested a review from lbobinski March 20, 2026 13:29
gemini-code-assist[bot]
gemini-code-assist bot reviewed Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request significantly updates the project's documentation, centralizing instructions in AGENTS.md and introducing a detailed REQUEST_PROCESSING.md for the concurrency model. New diagrams enhance understanding of the execution flows. A key change is the reduction of the eventpipe buffer size, which requires careful consideration regarding its impact on system behavior and consistency with documentation. The new REQUEST_PROCESSING.md is a high-quality addition, providing crucial insights into the system's design and highlighting potential pitfalls, including critical issues related to panic handling that must adhere to established repository rules.

lbobinski
lbobinski approved these changes Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown

@lbobinski lbobinski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good

@yarolegovich yarolegovich merged commit ed33c7a into main Mar 20, 2026
4 checks passed
@yarolegovich yarolegovich deleted the yarolegovich/ai-docs branch March 20, 2026 15:41
@a2a-bot a2a-bot mentioned this pull request Mar 20, 2026
Merged
yarolegovich pushed a commit that referenced this pull request Mar 24, 2026
@a2a-bot
chore(main): release 2.0.1 (#288)
6108e34 
🤖 I have created a release *beep* *boop*
---


## [2.0.1](v2.0.0...v2.0.1)
(2026-03-24)


### Features

* **a2acompat:** add HTTP+JSON REST support to a2av0 compat layer
([#280](#280))
([bac00e7](bac00e7))
* agent executor cleaner
([#276](#276))
([9c95980](9c95980))


### Bug Fixes

* ensure correct concurrent cancellation results
([#287](#287))
([d0f8981](d0f8981)),
closes [#245](#245)


### Documentation

* **a2aclient:** add Example_* test functions for pkg.go.dev
documentation ([#263](#263))
([f8dae97](f8dae97))
* update diagrams, docs and instructions
([#289](#289))
([ed33c7a](ed33c7a))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@lbobinski lbobinski lbobinski approved these changes

@ishymko ishymko Awaiting requested review from ishymko

+1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@yarolegovich @lbobinski