bc98c65956
Agent: huffman Compaction Summary: - Lines: 576 → 477 (-17%) - Chars: 36,372 → 26,173 (-28%) - Entries: 45 → 37 (merged 8) Transformations: - Removed 1 exact duplicate (Datalog Program Generation x2) - Collapsed 6 log-style bug narratives to current-state declarations - Merged Plan Verification into Plan Mode entry - Merged Rulespec Changes into Invariants entry (current state only) - Updated 12 stale char ranges against actual file positions - Removed 13 references to deleted code (extraction.rs, shadow_datalog_verify, save/load_compiled_rulespec, display_welcome_message, OutputMode, etc.) - Moved Skills System Entry Points from AGENTS.md to memory (was duplicate) - AGENTS.md: removed 20-line skills table, kept rules/invariants only
88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
# AGENTS.md - Machine Instructions for g3
|
|
|
|
**Purpose**: Machine-specific instructions for AI agents working with this codebase.
|
|
**For code locations**: See Workspace Memory (loaded automatically)
|
|
**For project overview**: See [README.md](README.md)
|
|
|
|
## Critical Invariants
|
|
|
|
### MUST Hold
|
|
|
|
1. **Tool calls must be valid JSON** - The streaming parser expects well-formed tool calls
|
|
2. **Context window limits must be respected** - Exceeding limits causes API errors
|
|
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
|
|
8. **String slicing must be UTF-8 safe** - Use `chars().take(n)` or `char_indices()`, never byte slicing like `&s[..n]` on user-facing strings
|
|
|
|
### MUST NOT Do
|
|
|
|
1. **Never block the async runtime** - Use `tokio::spawn` for CPU-intensive work
|
|
2. **Never store secrets in logs** - API keys are redacted in error logs
|
|
3. **Never modify files outside working directory without explicit permission**
|
|
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
|
|
|
|
## Adding Features
|
|
|
|
- **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 skill**: Create `skills/<name>/SKILL.md`, optionally add to `embedded.rs` for binary inclusion
|
|
- **New config option**: Add to `g3-config` structs
|
|
|
|
## Dangerous Code Paths
|
|
|
|
These areas have subtle bugs if modified incorrectly:
|
|
|
|
| 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 |
|
|
| **Skill extraction** | Version hash mismatch causes stale scripts; path issues on Windows |
|
|
|
|
## 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
|
|
- ✅ Keep functions under 80 lines
|
|
|
|
### Don't
|
|
- ❌ Add blocking code in async contexts
|
|
- ❌ Store sensitive data in plain text
|
|
- ❌ Ignore error handling
|
|
- ❌ Create deeply nested conditionals (>6 levels)
|
|
- ❌ Add external dependencies for simple tasks
|
|
|
|
## Common Incorrect Assumptions
|
|
|
|
1. **"All providers support tool calling"** - Embedded models use JSON fallback
|
|
2. **"Context window is unlimited"** - Each provider has limits (4k-200k tokens)
|
|
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` | Canonical dependency graph with nodes (crates, files) and edges (imports) |
|
|
| `graph.summary.md` | One-page overview with metrics, entrypoints, and top fan-in/fan-out nodes |
|
|
| `sccs.md` | Strongly connected components (dependency cycles) analysis |
|
|
| `layers.observed.md` | Observed layering structure derived from dependency direction |
|
|
| `hotspots.md` | Files with disproportionate coupling (high fan-in or fan-out) |
|
|
| `limitations.md` | What could not be observed and what may invalidate conclusions |
|
|
|
|
These artifacts are useful for understanding coupling, planning refactors, and identifying architectural boundaries.
|
|
|