seamless AGENTS.md

AGENTS.md

Coding conventions for AI agents working in the Seamless repository. For the project overview, structure, and commands, see CLAUDE.md.

Go style rules

General

• Go 1.25+. No CGO. Pure-Go SQLite driver (modernc.org/sqlite).
• Never use emojis in code or comments. Never include attribution/credit lines in commits, PRs, or code.
• Format with gofmt. No exceptions. Prefer modern stdlib (slices, maps, strings.SplitSeq, iterators) in new code.

Package structure

Each domain package under internal/ follows a consistent layout:

• service.go -- business logic (the public API of the package)
• store.go -- SQLite data access
• handler.go -- HTTP handlers (only for packages with an HTTP surface)
• {feature}.go -- pure functions (parsers, ranking, frontmatter, etc.)
• *_test.go -- tests alongside source

Strict layering, no circular imports. cmd/ wires everything; no package imports cmd/ and no domain package imports another's HTTP layer:

cmd/seamlessd, cmd/seam, cmd/seambench, cmd/demoseed, cmd/docsgen
  -> internal/{mcp,hooks,console}         (API surfaces)
    -> internal/{retrieve,lifecycle,gardener,files,capture,bench,demokit} (domains)
      -> internal/{store,events,llm,core,config,validate}          (foundations)

(The dependency-aware ready-queue and lease-based claiming live in internal/store/tasks*.go; there is no internal/tasks package.)

Naming

• Interfaces: role nouns (Store, Recorder, Embedder), not IStore.
• Constructors: New{Type}(deps) *Type (or (*Type, error) when it can fail).
• Domain errors: package-level var Err{Condition} = errors.New(...) sentinels, checked with errors.Is.
• Tests: Test{Unit}_{Scenario} or table-driven with t.Run.
• IDs: ULID everywhere (github.com/oklog/ulid/v2) via core.NewID(). Never UUID.

Error handling

• Wrap with context and %w: fmt.Errorf("pkg.Service.Method: %w", err).
• Sentinel errors via errors.New; reserve fmt.Errorf for wrapping (with %w).
• Either log or return an error, never both. Fatal to the operation -> return it; non-fatal (graceful degradation) -> slog.Warn/Debug and continue.