From 69e2d8c7ae97b502e768f8cf18dca2c8ffe2978d Mon Sep 17 00:00:00 2001 From: Sandy Tao Date: Tue, 17 Mar 2026 12:51:23 -0700 Subject: [PATCH] docs: distribute package-specific GEMINI.md context to each package (#22734) --- GEMINI.md | 11 ++---- packages/a2a-server/GEMINI.md | 22 ++++++++++++ packages/cli/GEMINI.md | 2 +- packages/core/GEMINI.md | 47 +++++++++++++++++++++++++ packages/sdk/GEMINI.md | 18 ++++++++++ packages/test-utils/GEMINI.md | 16 +++++++++ packages/vscode-ide-companion/GEMINI.md | 23 ++++++++++++ 7 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 packages/a2a-server/GEMINI.md create mode 100644 packages/core/GEMINI.md create mode 100644 packages/sdk/GEMINI.md create mode 100644 packages/test-utils/GEMINI.md create mode 100644 packages/vscode-ide-companion/GEMINI.md diff --git a/GEMINI.md b/GEMINI.md index f7017eab40..c08e486b22 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -22,9 +22,10 @@ powerful tool for developers. rendering. - `packages/core`: Backend logic, Gemini API orchestration, prompt construction, and tool execution. - - `packages/core/src/tools/`: Built-in tools for file system, shell, and web - operations. - `packages/a2a-server`: Experimental Agent-to-Agent server. + - `packages/sdk`: Programmatic SDK for embedding Gemini CLI capabilities. + - `packages/devtools`: Integrated developer tools (Network/Console inspector). + - `packages/test-utils`: Shared test utilities and test rig. - `packages/vscode-ide-companion`: VS Code extension pairing with the CLI. ## Building and Running @@ -58,10 +59,6 @@ powerful tool for developers. ## Development Conventions -- **Legacy Snippets:** `packages/core/src/prompts/snippets.legacy.ts` is a - snapshot of an older system prompt. Avoid changing the prompting verbiage to - preserve its historical behavior; however, structural changes to ensure - compilation or simplify the code are permitted. - **Contributions:** Follow the process outlined in `CONTRIBUTING.md`. Requires signing the Google CLA. - **Pull Requests:** Keep PRs small, focused, and linked to an existing issue. @@ -69,8 +66,6 @@ powerful tool for developers. `gh` CLI. - **Commit Messages:** Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard. -- **Coding Style:** Adhere to existing patterns in `packages/cli` (React/Ink) - and `packages/core` (Backend logic). - **Imports:** Use specific imports and avoid restricted relative imports between packages (enforced by ESLint). - **License Headers:** For all new source code files (`.ts`, `.tsx`, `.js`), diff --git a/packages/a2a-server/GEMINI.md b/packages/a2a-server/GEMINI.md new file mode 100644 index 0000000000..34e487e3bb --- /dev/null +++ b/packages/a2a-server/GEMINI.md @@ -0,0 +1,22 @@ +# Gemini CLI A2A Server (`@google/gemini-cli-a2a-server`) + +Experimental Agent-to-Agent (A2A) server that exposes Gemini CLI capabilities +over HTTP for inter-agent communication. + +## Architecture + +- `src/agent/`: Agent session management for A2A interactions. +- `src/commands/`: CLI command definitions for the A2A server binary. +- `src/config/`: Server configuration. +- `src/http/`: HTTP server and route handlers. +- `src/persistence/`: Session and state persistence. +- `src/utils/`: Shared utility functions. +- `src/types.ts`: Shared type definitions. + +## Running + +- Binary entry point: `gemini-cli-a2a-server` + +## Testing + +- Run tests: `npm test -w @google/gemini-cli-a2a-server` diff --git a/packages/cli/GEMINI.md b/packages/cli/GEMINI.md index 5518696d60..e98ca81376 100644 --- a/packages/cli/GEMINI.md +++ b/packages/cli/GEMINI.md @@ -5,7 +5,7 @@ - Always fix react-hooks/exhaustive-deps lint errors by adding the missing dependencies. - **Shortcuts**: only define keyboard shortcuts in - `packages/cli/src/config/keyBindings.ts` + `packages/cli/src/ui/key/keyBindings.ts` - Do not implement any logic performing custom string measurement or string truncation. Use Ink layout instead leveraging ResizeObserver as needed. - Avoid prop drilling when at all possible. diff --git a/packages/core/GEMINI.md b/packages/core/GEMINI.md new file mode 100644 index 0000000000..a297aebedb --- /dev/null +++ b/packages/core/GEMINI.md @@ -0,0 +1,47 @@ +# Gemini CLI Core (`@google/gemini-cli-core`) + +Backend logic for Gemini CLI: API orchestration, prompt construction, tool +execution, and agent management. + +## Architecture + +- `src/agent/` & `src/agents/`: Agent lifecycle and sub-agent management. +- `src/availability/`: Model availability checks. +- `src/billing/`: Billing and usage tracking. +- `src/code_assist/`: Code assistance features. +- `src/commands/`: Built-in CLI command implementations. +- `src/config/`: Configuration management. +- `src/confirmation-bus/`: User confirmation flow for tool execution. +- `src/core/`: Core types and shared logic. +- `src/fallback/`: Fallback and retry strategies. +- `src/hooks/`: Hook system for extensibility. +- `src/ide/`: IDE integration interfaces. +- `src/mcp/`: MCP (Model Context Protocol) client and server integration. +- `src/output/`: Output formatting and rendering. +- `src/policy/`: Policy enforcement (e.g., tool confirmation policies). +- `src/prompts/`: System prompt construction and prompt snippets. +- `src/resources/`: Resource management. +- `src/routing/`: Model routing and selection logic. +- `src/safety/`: Safety filtering and guardrails. +- `src/scheduler/`: Task scheduling. +- `src/services/`: Shared service layer. +- `src/skills/`: Skill discovery and activation. +- `src/telemetry/`: Usage telemetry and logging. +- `src/tools/`: Built-in tool implementations (file system, shell, web, MCP). +- `src/utils/`: Shared utility functions. +- `src/voice/`: Voice input/output support. + +## Coding Conventions + +- **Legacy Snippets:** `src/prompts/snippets.legacy.ts` is a snapshot of an + older system prompt. Avoid changing the prompting verbiage to preserve its + historical behavior; however, structural changes to ensure compilation or + simplify the code are permitted. +- **Style:** Follow existing backend logic patterns. This package has no UI + dependencies — keep it framework-agnostic. + +## Testing + +- Run tests: `npm test -w @google/gemini-cli-core` +- Run a specific test: + `npm test -w @google/gemini-cli-core -- src/path/to/file.test.ts` diff --git a/packages/sdk/GEMINI.md b/packages/sdk/GEMINI.md new file mode 100644 index 0000000000..d9a8429dfe --- /dev/null +++ b/packages/sdk/GEMINI.md @@ -0,0 +1,18 @@ +# Gemini CLI SDK (`@google/gemini-cli-sdk`) + +Programmatic SDK for embedding Gemini CLI agent capabilities into other +applications. + +## Architecture + +- `src/agent.ts`: Agent creation and management. +- `src/session.ts`: Session lifecycle and state management. +- `src/tool.ts`: Tool definition and execution interface. +- `src/skills.ts`: Skill integration. +- `src/fs.ts` & `src/shell.ts`: File system and shell utilities. +- `src/types.ts`: Public type definitions. + +## Testing + +- Run tests: `npm test -w @google/gemini-cli-sdk` +- Integration tests use `*.integration.test.ts` naming convention. diff --git a/packages/test-utils/GEMINI.md b/packages/test-utils/GEMINI.md new file mode 100644 index 0000000000..56f64c0291 --- /dev/null +++ b/packages/test-utils/GEMINI.md @@ -0,0 +1,16 @@ +# Gemini CLI Test Utils (`@google/gemini-cli-test-utils`) + +Shared test utilities used across the monorepo. This is a private package — not +published to npm. + +## Key Modules + +- `src/test-rig.ts`: The primary test rig for spinning up end-to-end CLI + sessions with mock responses. +- `src/file-system-test-helpers.ts`: Helpers for creating temporary file system + fixtures. +- `src/mock-utils.ts`: Common mock utilities. + +## Usage + +Import from `@google/gemini-cli-test-utils` in test files across the monorepo. diff --git a/packages/vscode-ide-companion/GEMINI.md b/packages/vscode-ide-companion/GEMINI.md new file mode 100644 index 0000000000..6825e11575 --- /dev/null +++ b/packages/vscode-ide-companion/GEMINI.md @@ -0,0 +1,23 @@ +# Gemini CLI VS Code Companion (`gemini-cli-vscode-ide-companion`) + +VS Code extension that pairs with Gemini CLI, providing direct IDE workspace +access to the CLI agent. + +## Architecture + +- `src/extension.ts`: Extension activation and lifecycle. +- `src/ide-server.ts`: Local server exposing IDE capabilities to the CLI. +- `src/diff-manager.ts`: Diff viewing and application. +- `src/open-files-manager.ts`: Tracks and exposes open editor files. +- `src/utils/`: Shared utility functions. + +## Development + +- Requires VS Code `^1.99.0`. +- Build: `npm run build` (uses esbuild). +- Launch via VS Code's "Run Extension" debug configuration. + +## Testing + +- Run tests: `npm test -w gemini-cli-vscode-ide-companion` +- Tests use standard Vitest patterns alongside VS Code test APIs.