rony-llm-agent/AGENTS.md

# AGENTS.md — Working in rony-llm-agent

## 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

| If you need... | Read... |
|---|---|
| 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

```bash
# Requires Go 1.26+ — required for os.Root, iter.Seq2, unique.Handle
go mod tidy          # resolves imports, creates go.sum
go test ./...         # all packages
go test -race ./...   # race detector (always use in CI once implemented)
```

Run `golangci-lint` if installed. No Makefile configured yet.

## Key constraints to never break

### Go version
Requires **Go 1.26+**. The module declares it in go.mod. Using older Go will not compile because of `os.Root`, `iter.Seq2`, `unique.Handle`.

### Hexagonal architecture — package boundaries
- Interfaces (ports) live at the top level of each `pkg/<name>/` directory. These define the public API.
- Implementations (adapters) go in `pkg/<name>/internal/` or subdirectories like `pkg/llm/providers/openai/`, `pkg/rag/backends/chroma/`.
- Package names are lowercase, singular (`agent`, `tools`, `llm`, `rag`, `persona`).
- No external dependencies in domain packages — only stdlib and SDKs of providers (in adapters).

### Module path
`github.com/VictorVargas/rony-llm-agent` — imported as-is by downstream products.

### Streaming uses `iter.Seq2`
The library is designed around Go 1.23+'s `iter.Seq2[T, error]` for streaming LLM output. When implementing or reading code, this is the primary stream pattern.

### 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

- 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`, `ErrPersonaNotFound`, `ErrConfigNotFound`.
- Constructors use `New` for the primary and `NewXxx` for variants.
- Error wrapping uses `%w`, never lossy formatting.

## Relationship to downstream products

This library is consumed by:
- **rony-harness** — TUI agent for software development (the reference implementation that triggered this extraction)
- **rony-chat-bot** — HTTP chatbot for portfolios/websites

If you're unsure about behavior, check what harness or chat-bot does first. They are the real-world consumers driving design decisions.

## Agent skills

Reusable skills for any AI agent live in `.agents/skills/<name>/SKILL.md` — this is the canonical, tool-agnostic location read by OpenCode, Claude Code, Cursor, and other modern agents. Each skill's `SKILL.md` starts with a YAML frontmatter (`name`, `description`) followed by instructions. Do not mirror skills into `.opencode/skills/` — opencode reads `.agents/skills/` natively.

## Phase 2 awareness

**Phase 2 is now in progress** (started 2026-07-09). Sub-agents (`docs/phase2.md` §5) landed first: `pkg/agent.SubAgent`/`SubAgentRegistry` (`pkg/agent/subagent.go`) let a caller run a specialized, nested `agent.Loop` and get its final response back — the harness uses this for its `delegate` tool (builder/planner). MCP server/client, full RAG pipeline with Qdrant/sqlite-vec backends, skills system, and observability remain unimplemented; don't start those unless explicitly asked. Reference `docs/phase2.md` for spec when needed.