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
This commit is contained in:
Dhanji R. Prasanna
111
AGENTS.md
111
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:
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user