rony-llm-agent/AGENTS.md

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
Per-package boundaries	docs/components.md
Features not yet planned	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)

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