97 lines
4.5 KiB
Markdown
97 lines
4.5 KiB
Markdown
---
|
|
description: YAMS repo supplement — conventions, structure, and repo-scoped rules
|
|
argument-hint: [TASK=<description>] [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.
|