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

name	description
add-feature	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.

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