vikingowl
5170c73dac
Top-level docs were stale and the .gitea/ issue templates referenced a workflow that is no longer in use. - README: rewrite around the current feature set (SLM routing, profiles, plugin TOFU, SafeProvider boundary, current model defaults). Add a pre-built-binary install section plus Docker (ghcr.io) install path for users without a Go toolchain. Document the GitHub mirror. - CONTRIBUTING: drop the dead issue-template reference, note Gitea upstream + GitHub mirror split, expand the package map and test-target table. - AGENTS: rebuild as a domain glossary (Elf / Arm / Turn / SafeProvider / Incognito / Profile) plus non-obvious conventions an outside agent needs and would not infer from the code. - TODO: trim completed waves into a History section, fix a broken link to the never-written Wave 3 plan file, surface active backlog. - docs/essentials/INDEX: add ADR-004 (PostToolUse hook ordering) to the ADR list. - LICENSE + NOTICE: adopt Apache License 2.0. Patent grant matters because gnoma bundles SDKs from Anthropic / OpenAI / Google / Mistral and ships derivative tooling that runs untrusted MCP servers. - Delete .gitea/issue_template/ and gemma-integration-analysis.md (latter is obsolete per its own preamble — Node.js-specific notes that don't apply to the Go implementation).
76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# 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`
|