rony-llm-agent/.agents/skills/add-feature/SKILL.md

---
name: add-feature
description: >-
  Use ONLY when adding new features to rony-llm-agent or its downstream products
  (rony-harness, rony-chat-bot). This skill enforces adherence to the architecture
  spec and asks probing questions before any implementation. Trigger when the user
  says "add feature", "implement X", "build Y", or describes a new capability not
  yet in scope.
---

# Add Feature — Architecture-First Agent Skill

## Purpose

Guide the addition of new features to `rony-llm-agent` (or its consumers) while
**strictly following** [`docs/architecture.md`](../../docs/architecture.md).

Before writing any code, you **must ask questions** about every aspect of the feature
that could affect: package boundaries, interfaces, dependencies, or security model.

## Pre-Implementation Checklist

### 1. Scope & Package Placement

Read first, in this order:
1. `docs/architecture.md` — hexagonal layers, core interfaces, security model
2. `docs/components.md` — per-package boundaries and public APIs
3. `docs/phase2.md` — check if the feature overlaps or conflicts with Phase 2 backlog
4. `AGENTS.md` — code conventions (naming, errors, context usage)

Then answer **before** proposing implementation:

- [ ] Which package(s) need new interfaces vs existing ones?
- [ ] Does this create a new top-level `pkg/<name>/` or fit inside an existing one?
- [ ] What is the public-facing interface (port)? Can it be written as a pure Go interface?
- [ ] Is there an existing adapter that can extend, or does it need a new one?

### 2. Interface Design

For every new or modified interface:

- Does the interface name follow capability naming? (`LLMClient`, `Loop`, `Embedder`, `Memory`)
- Does every method take `ctx context.Context` as first parameter?
- Are return types Go-native (structs, `iter.Seq2` for streams), not callbacks?
- Is the interface minimal — only what consumers actually need?

### 3. Dependencies & Package Layers

- Does the domain package (`pkg/<name>/`) import anything external except stdlib?
  **NO.** External SDKs live in adapters under `internal/`.
- If a new package is needed, does its `import` path follow `github.com/VictorVargas/rony-llm-agent/pkg/<name>`?
- Are adapters isolated behind interfaces? No adapter should leak into domain code.

### 4. Security Model

Refer to `docs/architecture.md` §4 — "Modelo de Seguridad":

- Does the feature introduce new filesystem access? → Must use `os.Root` sandbox, never raw paths.
- Does it execute external commands? → Command validation needed; delegate to products.
- Does it accept user input into LLM prompts? → Consider `<untrusted_content>` wrapping (Phase 2).
- Are there permission implications for tools? → Use `Permission: Allow | Ask | Deny` policy.
- Is the feature compliant with least-privilege principle?

### 5. Testing Strategy

Before implementation, identify:

- What existing mock can be reused? (`mock.MockLLMClient`, `mock.MockMemory`)
- Are there critical-path tests to add? See `docs/architecture.md` §6 — "Tabla de tests críticos"
- Is the test deterministic (no network calls) or integration (real provider/backend)?
- If streaming, does it properly consume the full `iter.Seq2` channel without goroutine leaks?

### 6. Concurrency & Context Propagation

- Does every blocking call take a context?
- Are contexts properly cancelled on timeout/interrupt?
- Is the new code safe for concurrent use by multiple products simultaneously?

## Questioning Protocol

**Never assume.** If an answer isn't explicitly in architecture.md, components.md, or phase2.md, ask:

1. "Where does this belong architecturally?" — before writing anything
2. "What interface does this consume or provide?" — define ports first
3. "How does this interact with the sandbox/security model?" — always check permissions
4. "Which existing package depends on this?" — verify no circular deps
5. "What's the failure mode and error path?" — use `ErrXXX` sentinels + `%w` wrapping

## Constraints (Never Break)

| Constraint | Why |
|---|---|
| Go 1.26+ required | Uses `os.Root`, `iter.Seq2`, `unique.Handle` |
| No reflection, no codegen, no DSLs | "Zero magic" principle |
| Ports first, implementations second | Hexagonal architecture — ports are pure interfaces |
| All blocking takes `ctx context.Context` | Cancellation and timeout support |
| Sandbox with `os.Root`, not path prefix checks | Kernel-level guarantee against symlinks, TOCTOU, encoding attacks |
| Downstream-first validation | Check what harness/chat-bot does before implementing |

## When to Defer to Phase 2

Do NOT implement these unless explicitly requested:

- MCP server/client protocol
- Full RAG pipeline (beyond existing `pkg/rag/`)
- Skills system for agent behavior customization
- Sub-agents and hierarchical prompting
- Observability/tracing/export

Reference `docs/phase2.md` if the feature overlaps.

## Implementation Checklist

After questions are answered:

1. Define interfaces at top of package (`pkg/<name>/interface.go` or similar)
2. Create domain logic in `pkg/<name>/` (no external deps)
3. Implement adapters in `pkg/<name>/internal/` or provider-specific dirs
4. Add tests using mocks where possible
5. Run `go vet ./...`, then `go test ./...` once code exists
6. Document public interfaces in package-level godoc