121 lines
No EOL
5.2 KiB
Markdown
121 lines
No EOL
5.2 KiB
Markdown
---
|
|
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 |