Skip to content

AGENTS.md

Latest commit

 

History

History
24 lines (19 loc) · 1.98 KB

AGENTS.md

File metadata and controls

24 lines (19 loc) · 1.98 KB
Raw

Agent Instructions for sfai

This file contains high-signal context and rules for AI agents working in this repository. For more exhaustive architectural details, refer to CLAUDE.md.

Commands & Verification

  • Test (Unit): just test (runs safe tests without external dependencies)
  • Test (Integration): just test-all (runs tests requiring a running Ollama model via -tags integration)
  • Verify: just verify (runs fmt, tidy, test, and build). Always run this before completing a task.
  • Build: just build (outputs binary to bin/sfai)

Strict Dependency Rules

  • pkg/ packages import ONLY other pkg/ packages.
  • internal/ packages import ONLY pkg/ packages. Never import other internal/ packages.
  • cmd/ is the ONLY layer allowed to import both pkg/ and internal/ to wire them together.

Architecture Boundaries

  • pkg/model: The LLM abstraction. Pure interface (Model.Query). No domain knowledge here.
  • pkg/sfai: The application aggregator. When adding a new utility, add its interface and field to the SFai struct here.
  • internal/iohttp: HTTP server built on huma v2. Endpoint validation is automatic from Input and Output struct tags. No manual validation code needed for HTTP routes.
  • CLI IO Convention: Utilities resolve input by checking if the argument is a file path (reads lines), a raw string (single text), or empty (reads from stdin pipe). Output is JSONL.

Workflow Quirks

  • Adding New Utilities: To add a new capability (e.g., coords), define domain types in pkg/coords/, interface in pkg/sfai/sfai.go, implementation in internal/iocoords/ (which owns the system prompt), wire them together in cmd/root.go, and add hooks in cmd/coords.go and internal/iohttp/coords.go.
  • Configuration: Uses Viper with precedence: CLI flags > Env vars (SFAI_*) > config file > defaults. Persistent fields round-trip via config.ToOptions(). Do NOT persist runtime-only config fields or HomeDir.