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).
84 lines
2.8 KiB
Markdown
84 lines
2.8 KiB
Markdown
# Contributing to gnoma
|
|
|
|
The upstream repository lives at
|
|
<https://somegit.dev/Owlibou/gnoma> and is mirrored to
|
|
<https://github.com/VikingOwl91/gnoma>. PRs are accepted on the upstream
|
|
(Gitea) instance; the GitHub mirror is read-only.
|
|
|
|
## Setup
|
|
|
|
```sh
|
|
git clone https://somegit.dev/Owlibou/gnoma && cd gnoma
|
|
make build # requires Go 1.26+
|
|
make test
|
|
make lint # requires golangci-lint
|
|
```
|
|
|
|
## Development workflow
|
|
|
|
1. Branch from `main`.
|
|
2. Write tests first (TDD). Table-driven where possible, `t.TempDir()` for
|
|
filesystem tests, `testing/synctest` for concurrent ones.
|
|
3. `make check` (fmt + vet + lint + test) must pass.
|
|
4. Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`,
|
|
`chore:`. **No co-signing or "Generated-by" trailers.**
|
|
|
|
## Code style
|
|
|
|
- Go 1.26 idioms (`new(expr)`, `errors.AsType[E]`, `sync.WaitGroup.Go`).
|
|
- Structured logging with `log/slog`.
|
|
- `json.RawMessage` for tool schemas (zero-cost passthrough).
|
|
- Functional options for complex configuration.
|
|
- Short, lowercase package names — no underscores.
|
|
- Discriminated unions via struct + type discriminant, not interfaces.
|
|
- Pull-based stream iterators: `Next() / Current() / Err() / Close()`.
|
|
|
|
## Testing
|
|
|
|
| Command | What it runs |
|
|
|---|---|
|
|
| `make test` | unit tests |
|
|
| `make test-integration` | tests behind `//go:build integration` — requires real API keys |
|
|
| `make cover` | coverage → `coverage.html` |
|
|
| `make lint` | `golangci-lint run ./...` |
|
|
| `make check` | fmt + vet + lint + test |
|
|
| `go test -bench=. ./internal/router/` | router benchmarks |
|
|
|
|
Integration tests are skipped by default.
|
|
|
|
## Architecture
|
|
|
|
Read [`docs/essentials/INDEX.md`](docs/essentials/INDEX.md) before changing
|
|
architectural boundaries. Key packages:
|
|
|
|
| Package | Purpose |
|
|
|---|---|
|
|
| `internal/engine` | Agentic loop (stream → tool → re-query) |
|
|
| `internal/router` | Multi-armed bandit arm selection |
|
|
| `internal/provider` | LLM provider adapters |
|
|
| `internal/tool` | Tool interface + registry |
|
|
| `internal/mcp` | MCP client (JSON-RPC over stdio) |
|
|
| `internal/plugin` | Plugin manifest, loader, manager |
|
|
| `internal/elf` | Sub-agent (elf) system |
|
|
| `internal/security` | SafeProvider boundary, firewall, output scanner |
|
|
| `internal/skill` | Skill registry and templating |
|
|
| `internal/slm` | Small-language-model classifier + arm |
|
|
| `internal/tui` | Bubble Tea v2 terminal UI |
|
|
|
|
ADRs live in [`docs/essentials/decisions/`](docs/essentials/decisions/).
|
|
|
|
## Reporting issues
|
|
|
|
File issues on the upstream Gitea instance with:
|
|
|
|
- A short reproduction (commands, prompts, configs that triggered the bug).
|
|
- Expected vs. actual behavior.
|
|
- `gnoma --version` output and OS / architecture.
|
|
- Provider and model in use, if relevant.
|
|
- `--verbose` log output if it sheds light.
|
|
|
|
## License
|
|
|
|
By contributing you agree your work is licensed under the
|
|
[Apache License 2.0](LICENSE).
|