From e2fffaab94b0c6e3d36ea6ae8410ec84889de529 Mon Sep 17 00:00:00 2001 From: "Dhanji R. Prasanna" Date: Tue, 6 Jan 2026 12:46:40 +1100 Subject: [PATCH] Slim down AGENTS.md and update lamport.md for machine-specific output AGENTS.md changes: - Removed redundant sections that duplicated README.md: - System Overview (crate table) - File Structure Quick Reference - Testing Strategy - Pointers to Documentation - Architecture Decisions - Kept unique machine-specific sections: - Critical Invariants (merged Performance Constraints) - Recommended Entry Points - Dangerous/Subtle Code Paths - Do's and Don'ts for Automated Changes - Common Incorrect Assumptions - Dependency Analysis Artifacts - Reduced from ~220 lines to ~116 lines lamport.md changes: - Rewrote AGENTS.md section with explicit instructions - Added REQUIRED sections list (5 sections only) - Added DO NOT include list to prevent README duplication - AGENTS.md now points to README for architecture/usage --- AGENTS.md | 111 ++-------------------------------------------- agents/lamport.md | 52 +++++++++++++++++----- 2 files changed, 46 insertions(+), 117 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b454a79..0a5ce05 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,7 @@ # AGENTS.md - Machine Instructions for G3 -**Last updated**: January 2025 -**Purpose**: Enable AI agents to work safely and effectively with this codebase - -## System Overview - -G3 is an AI coding agent built in Rust. It uses LLM providers to execute tasks through a tool-based interface. The codebase is organized as a Cargo workspace with 9 crates. - -### Quick Reference - -| Crate | Purpose | Stability | -|-------|---------|----------| -| `g3-core` | Agent engine, tools, context management | Stable | -| `g3-providers` | LLM provider abstractions | Stable | -| `g3-cli` | Command-line interface | Stable | -| `g3-config` | Configuration management | Stable | -| `g3-execution` | Code execution | Stable | -| `g3-computer-control` | Computer automation | Experimental | -| `g3-planner` | Planning mode | Stable | -| `g3-ensembles` | Multi-agent (flock) mode | Experimental | -| `g3-console` | Web monitoring console | Experimental | +**Purpose**: Machine-specific instructions for AI agents working with this codebase. +**For project overview, architecture, and usage**: See [README.md](README.md) ## Critical Invariants @@ -30,6 +12,8 @@ G3 is an AI coding agent built in Rust. It uses LLM providers to execute tasks t 3. **Provider trait implementations must be Send + Sync** - Required for async runtime 4. **Session IDs must be unique** - Used for log file paths and TODO scoping 5. **File paths in tools support tilde expansion** - `~` expands to home directory +6. **Streaming is preferred** - Non-streaming requests block UI +7. **Tool results are size-limited** - Large outputs are truncated or thinned automatically ### MUST NOT Do @@ -87,40 +71,6 @@ G3 is an AI coding agent built in Rust. It uses LLM providers to execute tasks t - Different configs for interactive vs autonomous mode - **Risk**: Aggressive retries can hit rate limits harder -## Performance Constraints - -1. **Streaming is preferred** - Non-streaming requests block UI -2. **Tool results are size-limited** - Large outputs are truncated or thinned -3. **Concurrent tool calls** - Enabled by `allow_multiple_tool_calls` config -4. **Background processes** - Long-running commands use `background_process` tool - -## Testing Strategy - -### Test Locations - -- Unit tests: `crates/*/tests/` -- Integration tests: `crates/*/tests/` -- Test fixtures: `examples/test_code/` - -### Running Tests - -```bash -# All tests -cargo test - -# Specific crate -cargo test -p g3-core - -# With output -cargo test -- --nocapture -``` - -### Test Considerations - -- Provider tests may require API keys -- Computer control tests require OS permissions -- WebDriver tests require browser setup - ## Do's and Don'ts for Automated Changes ### Do @@ -150,59 +100,6 @@ cargo test -- --nocapture 4. **"Sessions persist across runs"** - Sessions are ephemeral by default 5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility) -## Architecture Decisions - -See `DESIGN.md` for original design rationale. - -Key decisions: -- **Rust for performance and safety** - Async runtime, memory safety -- **Workspace structure** - Separation of concerns, independent compilation -- **Provider abstraction** - Swap providers without code changes -- **Tool-first philosophy** - Agent acts through tools, not just advice -- **Session-scoped state** - TODO lists, logs tied to sessions - -## File Structure Quick Reference - -``` -g3/ -├── src/main.rs # Entry point -├── crates/ -│ ├── g3-cli/src/ -│ │ ├── lib.rs # CLI logic (~112k chars) -│ │ └── retro_tui.rs # Retro TUI mode -│ ├── g3-core/src/ -│ │ ├── lib.rs # Agent struct (~3400 lines) -│ │ ├── context_window.rs # Context management -│ │ ├── tool_definitions.rs # Tool schemas -│ │ ├── tool_dispatch.rs # Tool routing -│ │ ├── tools/ # Tool implementations -│ │ ├── streaming_parser.rs # Response parsing -│ │ └── retry.rs # Retry logic -│ ├── g3-providers/src/ -│ │ ├── lib.rs # Provider trait -│ │ ├── anthropic.rs # Anthropic Claude -│ │ ├── databricks.rs # Databricks -│ │ ├── openai.rs # OpenAI -│ │ └── embedded.rs # Local models -│ ├── g3-config/src/lib.rs # Configuration -│ ├── g3-planner/src/ # Planning mode -│ ├── g3-ensembles/src/ # Flock mode -│ └── g3-computer-control/src/ # Automation -├── agents/ # Agent personas -├── docs/ # Documentation -└── logs/ # Session logs -``` - -## Pointers to Documentation - -- [Architecture](docs/architecture.md) - System design and data flow -- [Configuration](docs/configuration.md) - Config file format and options -- [Tools Reference](docs/tools.md) - All available tools -- [Providers Guide](docs/providers.md) - LLM provider setup -- [Control Commands](docs/CONTROL_COMMANDS.md) - Interactive commands -- [Code Search](docs/CODE_SEARCH.md) - Tree-sitter search guide -- [Flock Mode](docs/FLOCK_MODE.md) - Multi-agent development - ## Dependency Analysis Artifacts The `analysis/deps/` directory contains static analysis artifacts generated by the Euler agent: diff --git a/agents/lamport.md b/agents/lamport.md index 79bb8b9..09ce08d 100644 --- a/agents/lamport.md +++ b/agents/lamport.md @@ -268,16 +268,48 @@ you may create or update AGENTS.md. Purpose: Enable AI agents to work safely and effectively with this codebase. -Include: -- Machine-oriented system overview -- Stable vs volatile areas -- Recommended entrypoints -- Dangerous or subtle code paths -- Invariants that MUST hold -- Performance or correctness constraints -- Do’s and don’ts for automated changes -- Pointers to architecture and decision docs -- Explicit warnings about likely incorrect assumptions +CRITICAL: AGENTS.md must contain ONLY machine-specific instructions. +Do NOT duplicate content from README.md. + +AGENTS.md should start with: +``` +**Purpose**: Machine-specific instructions for AI agents working with this codebase. +**For project overview, architecture, and usage**: See [README.md](README.md) +``` + +REQUIRED sections (include ONLY these): + +1. **Critical Invariants** + - MUST hold constraints (e.g., "Tool calls must be valid JSON") + - MUST NOT do constraints (e.g., "Never block the async runtime") + - Performance constraints that affect correctness + +2. **Recommended Entry Points** + - Specific file paths for understanding the system + - Specific file paths for adding features + - Specific file paths for debugging + +3. **Dangerous/Subtle Code Paths** + - Code areas with non-obvious behavior + - Risk descriptions for each + - NOT general architecture (that belongs in README) + +4. **Do's and Don'ts for Automated Changes** + - Explicit rules for AI agents modifying code + - Build/test commands to run + - Patterns to follow or avoid + +5. **Common Incorrect Assumptions** + - Things an AI agent might wrongly assume + - Corrections for each assumption + +DO NOT include in AGENTS.md: +- Architecture overview (use README) +- Crate/module descriptions (use README) +- File structure diagrams (derivable from codebase) +- Documentation links (use README's Documentation Map) +- Testing instructions beyond "run cargo test" (trivial) +- How to use the project (use README) ------------------------------------------------------------ ACCURACY CHECKS