trevon/yams
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
yams/AGENTS.md

7.8 KiB
Raw Permalink Blame History

description: YAMS-first repo agent supplement for Codex (engineering + bug-bounty) argument-hint: [TASK=] [MODE=<engineering|bug-bounty>] [PBI=] [PHASE=<start|checkpoint|complete>]

AGENTS.md (Repo Supplement)

This file supplements docs/prompts/PROMPT-eng-codex.md.

Use docs/prompts/PROMPT-eng-codex.md for the generic Codex/YAMS operating model. Use this file for YAMS repo specifics, local conventions, and repo-scoped safety.

Repo Intent

  • Primary use: software engineering on YAMS.
  • Secondary use: bug-bounty style security research workflows (scoped, non-destructive by default).
  • Persistent memory goal: use YAMS as distributed memory across sessions, agents, and handoffs.

Repo Priorities (Overrides / Additions)

  • Prefer YAMS retrieval before local file reads when recovering context or prior decisions.
  • Keep memory artifacts small and queryable (checkpoint code + short notes > long prose dumps).
  • Index work before git push, and before deleting files.
  • If blackboard tools are unavailable, continue with YAMS-only workflow without blocking.

Repo Agent ID

  • Canonical format: opencode-<task-slug>
  • Example: opencode-list-snippet-hydration

Required YAMS Metadata (Repo Standard)

Attach to every yams add:

  • task: short task slug
  • phase: start|checkpoint|complete
  • owner: opencode
  • source: code|note|decision|research|evidence

Recommended in this repo:

  • mode: engineering|bug-bounty
  • pbi: PBI id if applicable
  • agent_id: opencode-<task-slug>
  • status: open|blocked|done

Bug-bounty additions when applicable:

  • target: program/asset identifier
  • scope: in-scope surface label
  • severity: low|medium|high|critical
  • repro: reproducibility tag
  • impact: impact summary tag

YAMS-First Retrieval Behavior

Use this order when you need context for reasoning:

  1. yams search / yams grep to discover artifacts
  2. yams get (or MCP get) to read selected artifacts
  3. Local file reads for implementation details only after YAMS retrieval

Behavior rules:

  • Prefer YAMS retrieval over ad-hoc local rg/cat for prior knowledge.
  • Do not mark chunks as rejected unless explicit user/model feedback says so.
  • Treat served - used as weak negative signal (not_used), not hard rejection.

Reporting when retrieval is used:

  • Include UsedContext: <chunk_ids or hashes> when known.
  • Include Citations: <artifact paths/hashes> or Citations: none.
  • Preserve trace_id in logs/artifacts when available.

Blackboard Coordination (If Available)

Registration first:

bb_register_agent({ id: "opencode-<task-slug>", name: "OpenCode Agent", capabilities: ["yams", "code", "coordination"] })

Minimal coordination pattern:

bb_search_findings({ query: "<keywords>" })
bb_post_finding({ agent_id: "opencode-<task-slug>", topic: "other", title: "<title>", content: "<markdown>" })
bb_create_task({ title: "<work item>", type: "fix", priority: 2, created_by: "opencode-<task-slug>" })
bb_claim_task({ task_id: "<task-id>", agent_id: "opencode-<task-slug>" })
bb_update_task({ task_id: "<task-id>", status: "working" })

Fallback:

  • If blackboard is unavailable, create a YAMS claim note and proceed.

Repo Search / Recovery Commands

Common discovery commands:

yams grep "<pattern>" --cwd .
yams search "$TASK" --limit 20
yams search "task=$TASK" --type keyword --limit 20

Session recovery:

yams search "owner=opencode task=<task>" --type keyword --limit 50
yams search "agent_id=opencode-<task-slug>" --type keyword --limit 50

Repo Structure (Start Here)

  • CLI entry points and command wiring: src/cli/
  • Service layer and command handlers: src/app/services/
  • Search implementations (grep/semantic): src/search/
  • Metadata and storage indexing: src/metadata/
  • Storage engines/backends: src/storage/
  • Vector DB + embeddings: src/vector/
  • Daemon client/server/components: src/daemon/
  • MCP server implementation: src/mcp/
  • Tests: tests/

Repo Conventions (Condensed)

  • Formatting is enforced mechanically by .clang-format (LLVM base, 4-space, 100-col, attach braces).
  • C++ naming patterns:
    • functions/variables: camelCase
    • types: PascalCase
    • constants: kPascalCase
    • member fields: trailing _
    • files: snake_case
  • Use Result<T> for fallible operations and explicit propagation.
  • Prefer YAMS_HAS_* feature gates from include/yams/core/cpp23_features.hpp over raw compiler checks.

Testing Conventions

  • Framework: Catch2 (v3+). All test files end in _catch2_test.cpp.
  • Test location: tests/unit/<subsystem>/ (e.g., tests/unit/daemon/).
  • Build system: Meson. Register test executables in tests/meson.build.
  • Test targets: Named without _exe suffix (e.g., catch2_dynamic_cap_sentinel).
  • Compile: meson compile -C build/debug -j4 <target_name>. Never run parallel meson compile commands — they contend for the build directory lock.
  • Run: build/debug/tests/<target_name> directly, or meson test -C build/debug <test_name>.
  • YAMS_TESTING gate: Test executables are compiled with -DYAMS_TESTING=1. Use #ifdef YAMS_TESTING in production headers to expose testing_* helpers (e.g., testing_postIngestBudget, testing_notifyWakeup).
  • Isolation guards: Use RAII guards for global state (ProfileGuard, EnvGuard, HwGuard from TuneAdvisor). Reset atomics and overrides between test cases.
  • Naming: Descriptive file names reflecting the feature under test (e.g., dynamic_cap_sentinel_catch2_test.cpp, health_check_isolation_catch2_test.cpp).
  • TDD workflow: Write tests first (red), implement fix (green), refactor. Tests should assert post-fix behavior and fail against pre-fix code.
  • DynamicCap sentinel: UINT32_MAX means "unset/no cap". 0 means "cap to zero concurrency". When resetting DynamicCaps in tests, use UINT32_MAX (requires #include <climits>), not 0.

Repo Patterns To Reuse (High Signal)

  • TuneAdvisor: runtime knob pattern uses static inline atomics and relaxed ordering for advisory reads.
  • InternalEventBus: typed channels keyed by string names for daemon component coordination.
  • ResourceGovernor: check admission (canAdmitWork, canScaleUp, canLoadModel) before heavy work.
  • profiling.h: use YAMS_* profiling macros; no-op when Tracy is disabled.
  • Async daemon paths use Boost.Asio coroutines (boost::asio::awaitable<...>).

Bug-Bounty Rules (Repo Use)

Apply when mode=bug-bounty:

  • Stay within stated scope and authorized targets.
  • Prefer read-only or low-impact validation first.
  • No persistence, destructive payloads, or data exfiltration.
  • Redact secrets, tokens, cookies, and personal data before yams add.
  • Index evidence as short reproducible notes (source=evidence) plus sanitized artifacts.

Ask-First Actions

Always ask before:

  • git push (index in YAMS first)
  • deleting files (index in YAMS first)
  • installing new dependencies
  • high-impact security testing steps

Minimal Repo Handoff Template

TASK: $TASK
MODE: $MODE
PBI: $PBI
PHASE: $PHASE
AGENT: opencode-$TASK

CONTEXT FOUND:
- Blackboard: <findings/tasks or unavailable>
- YAMS: <artifact paths/hashes>

ACTIONS:
- <what changed and why>

INDEXED:
- <files/notes indexed or why indexing failed>
- Metadata: mode=$MODE,task=$TASK,phase=$PHASE,owner=opencode,agent_id=opencode-$TASK

NEXT:
- <next step>

USED_CONTEXT:
- <chunk_ids/hashes if known; else unknown>

CITATIONS:
- <artifact names/hashes/paths or none>

When Stuck

  • Ask one targeted clarifying question with a recommended default.
  • Post a blackboard finding if it helps future agents.
  • Prefer small, reversible changes over speculative rewrites.

Keep This File Lean

  • Put generic agent behavior in docs/prompts/PROMPT-eng-codex.md.
  • Keep this file repo-specific.
  • Avoid copying session-specific skill catalogs into this file.