trevon/yams
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
yams/AGENTS.md
trvon 5b8d3e452b
 docs: prompt updates
2026-06-10 10:58:36 -04:00

4.5 KiB
Raw Permalink Blame History

description: YAMS repo supplement — conventions, structure, and repo-scoped rules argument-hint: [TASK=] [MODE=<engineering|bug-bounty>] [PHASE=<start|checkpoint|complete>]

AGENTS.md (Repo Supplement)

Operating model (retrieval contract, execution loop, metadata, handoff, ask-first list): docs/prompts/PROMPT-eng-codex.md. C++ design/TDD/assertion/ profiling flow: docs/prompts/PROMPT-yams-cpp-workflow.md. This file holds only what is specific to this repository.

Repo Intent

Engineering on YAMS itself, plus scoped non-destructive bug-bounty research. Dogfood YAMS as the distributed memory across sessions, agents, and handoffs — yams grep/search/graph before local discovery, always (see the retrieval contract in the prompt; the graph here is rich: function-level nodes with calls/defined_in edges, so "who uses X" is one yams graph --explore).

CLI Philosophy

  • Clean default behavior over feature flags and one-off env vars.
  • Add an env knob only when it materially improves usability/debugging/perf.
  • Auto-select behavior when safe rather than exposing another switch.
  • Remove temporary diagnostics once product behavior is clear.

Tuning Surfaces

  • Tuning lives in typed config, not env vars: new search/topology/daemon knobs go on the relevant config struct (SearchEngineConfig, TopologyConfig, …) with a TOML key resolved through ConfigResolver (include/yams/daemon/components/ConfigResolver.h).
  • Benches/tests/callers set the typed field directly or write a per-test config.toml (DaemonHarnessOptions::configPath) — never a fresh YAMS_* env var. Existing YAMS_SEARCH_TOPOLOGY_* / YAMS_EMBED_* overlays are test-only; keep them working, do not grow them.
  • Reaching for std::getenv for a tunable is the warning sign.

Repo Structure (Start Here)

  • CLI entry points: src/cli/ · services: src/app/services/
  • Search (grep/semantic): src/search/ · metadata/indexing: src/metadata/
  • Storage engines: src/storage/ · vector DB/embeddings: src/vector/
  • Daemon client/server/components: src/daemon/ · MCP: src/mcp/
  • Tests: tests/ · vendored libs: third_party/ (own git repos)

Conventions (Condensed)

  • Formatting is mechanical: .clang-format (LLVM base, 4-space, 100-col).
  • Naming: functions/vars camelCase; types PascalCase; constants kPascalCase; members trailing _; files snake_case.
  • Result<T> for fallible operations, explicit propagation.
  • Prefer YAMS_HAS_* gates from include/yams/core/cpp23_features.hpp.

Engineering Quality Loop (C++)

  1. Design the seam first: observable behavior, boundary, smallest testable seam.
  2. Red before green: failing Catch2 test through public/repo-stable APIs; characterize existing behavior before refactors.
  3. Assertions: recoverable failures stay in Result<T>; YAMS_ASSERT/ YAMS_PRECONDITION/YAMS_POSTCONDITION for always-on invariants; YAMS_DCHECK for debug-only consistency; expressions side-effect free.
  4. Refactor under green tests; no broad rewrites without seam/test evidence.
  5. Measure before optimizing: workload + KPI + baseline, change one thing, re-measure. YAMS_* profiling macros only with a clear question.

Testing Conventions

  • Catch2 v3; files end _catch2_test.cpp; live in tests/unit/<subsystem>/; registered in tests/meson.build; targets named without _exe.
  • Compile: meson compile -C build/debug -j4 <target> — never run parallel meson compiles (build-dir lock contention).
  • Run: build/debug/tests/<target> or meson test -C build/debug <name>.
  • -DYAMS_TESTING=1 gates testing_* helpers in production headers.
  • RAII guards for global state (ProfileGuard, EnvGuard, HwGuard); reset atomics/overrides between cases.
  • DynamicCap sentinel: UINT32_MAX = unset (use it when resetting, not 0).

Patterns To Reuse (High Signal)

  • TuneAdvisor: static inline atomics, relaxed reads for advisory knobs.
  • InternalEventBus: typed channels keyed by string names.
  • ResourceGovernor: check admission before heavy work.
  • profiling.h: YAMS_* macros, no-op without Tracy.
  • Daemon async paths: Boost.Asio coroutines (boost::asio::awaitable<…>).

Bug-Bounty (Repo Use)

Scoped targets only; read-only/low-impact validation first; no persistence, destructive payloads, or exfiltration; redact secrets before yams add; index evidence as short reproducible notes (source=evidence).

Keep This File Lean

Generic agent behavior belongs in docs/prompts/PROMPT-eng-codex.md. No session-specific skill catalogs here.