From 9a998e201a39de4f9c4a1f8bb381373785e124bd Mon Sep 17 00:00:00 2001 From: "Dhanji R. Prasanna" Date: Thu, 29 Jan 2026 11:13:25 +1100 Subject: [PATCH] Tighten AGENTS.md: remove redundant content covered by Memory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed sections that duplicate Workspace Memory: - Recommended Entry Points (Memory has precise file/line locations) - For Debugging paths (Memory has session/error log details) - Dependency Analysis Artifacts (reference info, not actionable) Kept essential guardrails: - Critical Invariants (MUST/MUST NOT rules) - Dangerous Code Paths (risk warnings, not locations) - Do/Dont coding standards - Common Incorrect Assumptions Reduction: 125 lines → 69 lines (~45% smaller, ~650 tokens saved) --- AGENTS.md | 90 +++++++++++-------------------------------------------- 1 file changed, 17 insertions(+), 73 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dde928f..247e89a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,8 @@ # AGENTS.md - Machine Instructions for g3 **Purpose**: Machine-specific instructions for AI agents working with this codebase. -**For project overview, architecture, and usage**: See [README.md](README.md) +**For code locations**: See Workspace Memory (loaded automatically) +**For project overview**: See [README.md](README.md) ## Critical Invariants @@ -24,77 +25,35 @@ 4. **Never assume tool results fit in context** - Large results are thinned automatically 5. **Never use byte-index string slicing on text with potential multi-byte characters** - Causes panics on emoji, CJK, box-drawing chars -## Recommended Entry Points +## Adding Features -### For Understanding the System +- **New tool**: Add definition in `tool_definitions.rs`, implement in `tools/`, add dispatch case +- **New provider**: Implement `LLMProvider` trait in `g3-providers` +- **New CLI mode**: Add to CLI args, implement handler in `g3-cli` +- **New config option**: Add to `g3-config` structs -1. `src/main.rs` - Entry point (trivial) -2. `crates/g3-cli/src/lib.rs` - CLI logic and execution modes -3. `crates/g3-core/src/lib.rs` - Agent struct and orchestration -4. `crates/g3-providers/src/lib.rs` - Provider trait definition +## Dangerous Code Paths -### For Adding Features +These areas have subtle bugs if modified incorrectly: -1. **New tool**: `crates/g3-core/src/tool_definitions.rs` → `crates/g3-core/src/tools/` -2. **New provider**: `crates/g3-providers/src/` → implement `LLMProvider` trait -3. **New CLI mode**: `crates/g3-cli/src/lib.rs` -4. **New config option**: `crates/g3-config/src/lib.rs` +| Area | Risk | +|------|------| +| **Context window management** | Incorrect token estimates cause context overflow | +| **Streaming parser** | Partial JSON across chunks causes parsing failures | +| **Tool dispatch** | Missing dispatch cases cause silent failures | +| **Retry logic** | Aggressive retries hit rate limits harder | +| **Parser sanitization** | Inline JSON can trigger false tool call detection | -### For Debugging - -1. Session logs: `.g3/sessions//session.json` -2. Error logs: `.g3/errors/` -3. Context state: Use `/stats` command in interactive mode - -## Dangerous/Subtle Code Paths - -### Context Window Management (`g3-core/src/context_window.rs`) - -- **Thinning**: Automatically replaces large tool results with file references -- **Summarization**: Compresses conversation history at 80% capacity -- **Token estimation**: Uses character-based heuristics, not exact tokenization -- **Risk**: Incorrect token estimates can cause context overflow - -### Streaming Parser (`g3-core/src/streaming_parser.rs`) - -- Parses LLM responses in real-time for tool calls -- Must handle partial JSON across chunk boundaries -- **Risk**: Malformed responses can cause parsing failures - -### Tool Dispatch (`g3-core/src/tool_dispatch.rs`) - -- Routes tool calls to implementations -- Handles both native and JSON-based tool calling -- **Risk**: Missing dispatch cases cause silent failures - -### Retry Logic (`g3-core/src/retry.rs`) - -- Exponential backoff with jitter -- Different configs for interactive vs autonomous mode -- **Risk**: Aggressive retries can hit rate limits harder - -### Parser Sanitization (`g3-core/src/streaming_parser.rs`) - -- Sanitizes inline tool-call JSON patterns to prevent parser poisoning -- Replaces `{` with fullwidth `｛` (U+FF5B) when patterns appear inline (not on their own line) -- Real tool calls from LLMs always appear on their own line -- **Risk**: Inline JSON examples in prose can trigger false tool call detection without sanitization - -## Do's and Don'ts for Automated Changes +## Do's and Don'ts ### Do - - ✅ Run `cargo check` after modifications - ✅ Run `cargo test` before committing - ✅ Update tool definitions when adding tools - ✅ Add tests for new functionality -- ✅ Use existing patterns for similar features - ✅ Keep functions under 80 lines -- ✅ Update documentation for user-facing changes ### Don't - -- ❌ Modify `Cargo.toml` dependencies without justification - ❌ Add blocking code in async contexts - ❌ Store sensitive data in plain text - ❌ Ignore error handling @@ -108,18 +67,3 @@ 3. **"Tool results are always small"** - File reads can return megabytes 4. **"Sessions persist across runs"** - Sessions are ephemeral by default 5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility) - -## Dependency Analysis Artifacts - -The `analysis/deps/` directory contains static analysis artifacts generated by the Euler agent: - -| File | Purpose | -|------|--------| -| `graph.json` | Raw dependency graph data (crate and file-level edges with evidence) | -| `graph.summary.md` | Overview metrics: crate counts, edge counts, fan-in/fan-out rankings | -| `sccs.md` | Strongly Connected Components analysis (cycle detection via Tarjan's algorithm) | -| `layers.observed.md` | Mechanically-derived layer diagram showing crate hierarchy and intra-crate module structure | -| `hotspots.md` | Coupling hotspots: files/crates with disproportionate fan-in or fan-out (>2× average) | -| `limitations.md` | Known limitations of the static analysis (conditional compilation, macros, re-exports) | - -These artifacts are useful for understanding coupling, planning refactors, and identifying architectural boundaries.