docs(AGENTS): update repo status to reflect Go source code exists

- Change status from 'design/spec only' to actual implementation
- Add pkg/*/README.md as a reference in the docs table
- Update build/test section for existing codebase
- Add test coverage summary table
- Update testing conventions with current mock types
- Add ErrPersonaNotFound and ErrConfigNotFound to sentinel errors
This commit is contained in:
Victor Hugo Vargas Servin 2026-07-03 14:22:46 -07:00
parent 2eed2033f0
commit bffaecb579

View file

@ -1,6 +1,6 @@
# AGENTS.md — Working in rony-llm-agent
## Repo status: **Design/spec only** — no Go source exists yet. All code described in docs (architecture.md, components.md, phase2.md) is aspirational. The README explicitly states this library hasn't been implemented; once `harness/` ships, the lib will be extracted as real code following these specs.
## Repo status: **Go source code exists.** The library is implemented across `pkg/agent`, `pkg/config`, `pkg/llm`, `pkg/persona`, `pkg/rag`, and `pkg/tools`. All public interfaces are defined, core adapters for OpenAI, llama.cpp, ChromaDB, and Ollama embeddings are in place. Tests exist for the agent loop, sandbox, config loader, persona loader, RAG memory, tool registry, and LLM clients.
## What to read first
@ -9,10 +9,11 @@
| Package layout and entrypoints | [`docs/architecture.md`](./docs/architecture.md) |
| Per-package boundaries | [`docs/components.md`](./docs/components.md) |
| Features not yet planned | [`docs/phase2.md`](./docs/phase2.md) — Phase 2 backlog |
| A specific package's API | [`pkg/<name>/README.md`](./pkg/*/README.md) — mirrors docs; check code for actual signatures |
These three docs are the source of truth. **Read them before writing any code.** The `pkg/*/README.md` files mirror content from these docs; they're convenient but architecture.md is canonical.
## How to build and test (once Go code exists)
## How to build and test
```bash
# Requires Go 1.26+ — required for os.Root, iter.Seq2, unique.Handle
@ -21,7 +22,7 @@ go test ./... # all packages
go test -race ./... # race detector (always use in CI once implemented)
```
No Makefile, no linters configured yet. Once code exists: lint → typecheck → test is the expected order. Run `golangci-lint` if installed.
Run `golangci-lint` if installed. No Makefile configured yet.
## Key constraints to never break
@ -43,17 +44,30 @@ The library is designed around Go 1.23+'s `iter.Seq2[T, error]` for streaming LL
### Sandbox uses `os.Root` (Go 1.24+)
Filesystem sandboxing must use `os.Root`, not path string prefix checks. This is non-negotiable for security — naive prefix checks can't handle symlinks, TOCTOU, or path encoding attacks.
## Testing conventions (when code exists)
## Testing conventions
- Use `pkg/llm/mock.MockLLMClient` for deterministic tests that don't call real APIs.
- Use `pkg/rag/mock.MockMemory` for memory tests.
- Use `pkg/llm/mock.MockLLMClient` (or its constructors `New()`, `NewWithGenerate()`, `NewWithStream()`, `NewWithMatch()`) for deterministic tests that don't call real APIs.
- Use `pkg/rag/embeddings/mock.MockEmbedder` for embedding tests.
- All public API must be concurrent-safe (documented in architecture.md).
- Every function that can block takes `ctx context.Context` as the first parameter.
### Current test coverage
| Package | Test file | Purpose |
|---|---|---|
| `pkg/agent` | `loop_test.go`, `integration_test.go` | Agent loop iterations, tool execution, streaming |
| `pkg/config` | `config_test.go` | YAML loading, defaults, precedence |
| `pkg/llm/providers/openai` | `client_test.go` | OpenAI HTTP client |
| `pkg/llm/providers/llamacpp` | `client_test.go` | llama.cpp server adapter |
| `pkg/persona` | `persona_test.go` | Persona loading, system prompt assembly |
| `pkg/rag` | `memory_test.go` | Add/search/forget operations |
| `pkg/tools` | `registry_test.go`, `sandbox/sandbox_test.go` | Tool registration, sandbox validation |
| `pkg/rag/backends/chroma` | `chroma_test.go` | ChromaDB upsert and search |
## Code style conventions
- Interfaces end with capability names: `LLMClient`, `Loop`, `Embedder`, `Memory`.
- Sentinel errors prefixed with `Err`: `ErrToolNotFound`, `ErrSandboxViolation`.
- Sentinel errors prefixed with `Err`: `ErrToolNotFound`, `ErrSandboxViolation`, `ErrPersonaNotFound`, `ErrConfigNotFound`.
- Constructors use `New` for the primary and `NewXxx` for variants.
- Error wrapping uses `%w`, never lossy formatting.
@ -71,4 +85,4 @@ Reusable skills for any AI agent live in `.agents/skills/<name>/SKILL.md` — th
## Phase 2 awareness
Phase 2 features (MCP server/client, full RAG pipeline, skills system, sub-agents, observability) are planned but not in scope for initial implementation. Do not start implementing phase 2 code unless explicitly asked. Reference `docs/phase2.md` for spec when needed.
Phase 2 features (MCP server/client, full RAG pipeline with Qdrant/sqlite-vec backends, skills system, sub-agents, observability) are planned but not in scope for initial implementation. Do not start implementing phase 2 code unless explicitly asked. Reference `docs/phase2.md` for spec when needed.