Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (59 loc) · 3.28 KB

AGENTS.md

File metadata and controls

75 lines (59 loc) · 3.28 KB

AGENTS.md

Conventions for AI assistants working in this repository. CLAUDE.md covers Go style, commits, and TDD policy; this file adds gnoma-specific domain knowledge those rules do not capture.

Domain glossary

Term Meaning
Elf A sub-agent instance, spawned via spawn_elfs.
Turn One complete stream → tool → re-query cycle in the engine.
Arm A (provider, model) pair the router can select. Registered with cost and capability metadata.
Router Multi-armed-bandit selector that picks an Arm per Turn from the registered set.
SLM Small language model running locally for prompt classification and trivial-task execution.
Stream Event Discriminated-union update emitted while a provider streams: EventTextDelta, EventToolCallStart, EventToolResult, etc. See internal/stream/event.go.
SafeProvider The sealed boundary that gates outbound provider calls — every Provider implementation embeds the unexported marker. See internal/security.
Incognito Per-turn mode that disables session persistence and router learning.
Profile A named config overlay under ~/.config/gnoma/profiles/. Switches keys, models, and per-profile router quality data.

Build & test targets (beyond standard)

Target Purpose
make test-v Verbose unit tests
make test-integration Runs //go:build integration tests (real API calls)
make check fmt + vet + lint + test (use before committing)
go test -bench=. ./internal/router/ Router benchmarks

Provider env vars

Provider Primary Alternative
Anthropic ANTHROPIC_API_KEY ANTHROPICS_API_KEY
OpenAI OPENAI_API_KEY —
Google GEMINI_API_KEY GOOGLE_API_KEY
Mistral MISTRAL_API_KEY —

GNOMA_PROVIDER and GNOMA_MODEL override the resolved config.

Non-obvious conventions

  • Discriminated unions are structs with a Type field and pointer payloads — not Go interfaces. See internal/stream/event.go and internal/message.
  • Pull-based iterators follow the Next() / Current() / Err() / Close() shape. Streams in internal/provider/*/stream.go are the canonical examples.
  • json.RawMessage flows through tool.Definition.Parameters and tool arguments untouched — never marshal/unmarshal in the middle.
  • Capabilities and ContextWindow come from internal/provider inferXxxModelCapabilities per provider; updating model lists also updates these tables and the ratelimits.go map.
  • Hook ordering matters for PostToolUse. See ADR-004.
  • Plugin trust is TOFU pinning — see internal/plugin/pinstore.go and ADR-003.

Sub-agent (elf) etiquette

When spawning elfs:

  • One spawn_elfs call for all parallel work; never spawn one at a time.
  • Read-only tasks on disjoint files parallelize cleanly.
  • Writes to the same file must be sequenced into one elf.
  • Cap each batch at 5–7 elfs.

See internal/skill/skills/batch.md for the canonical batching template.

Reference docs

  • Architecture map: docs/essentials/INDEX.md
  • ADRs: docs/essentials/decisions/
  • Profiles: docs/profiles.md
  • SLM backends: docs/slm-backends.md
  • Plugin trust: docs/plugins-trust.md
  • Router benchmarks: docs/benchmarks/README.md