g3/AGENTS.md

# 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.

## Skills System Entry Points

The skills system (`crates/g3-core/src/skills/`) provides extensible agent capabilities:

| File | Purpose |
|------|--------|
| `mod.rs` | Public API: `Skill`, `discover_skills`, `generate_skills_prompt` |
| `parser.rs` | SKILL.md parsing with YAML frontmatter validation |
| `discovery.rs` | Multi-location discovery with priority ordering |
| `embedded.rs` | Compile-time skill embedding via `include_str!` |
| `extraction.rs` | Script extraction to `.g3/bin/` with version tracking |
| `prompt.rs` | Generates `<available_skills>` XML for system prompt |

**Key invariants for skills**:
- Skill names must be 1-64 chars, lowercase + hyphens only
- SKILL.md must have valid YAML frontmatter with `name` and `description`
- Embedded scripts are extracted lazily (on first use)
- Version tracking uses content hash, not timestamps
- Higher priority locations override lower (repo > workspace > global > embedded)
- Script extraction is Unix-only (chmod 755); Windows support is incomplete