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

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

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)

```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)
```

No Makefile, no linters configured yet. Once code exists: lint → typecheck → test is the expected order. Run `golangci-lint` if installed.

## 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 (when code exists)

- Use `pkg/llm/mock.MockLLMClient` for deterministic tests that don't call real APIs.
- Use `pkg/rag/mock.MockMemory` for memory 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.

## Code style conventions

- Interfaces end with capability names: `LLMClient`, `Loop`, `Embedder`, `Memory`.
- Sentinel errors prefixed with `Err`: `ErrToolNotFound`, `ErrSandboxViolation`.
- 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 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.