74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
# 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.
|