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

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