Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (72 loc) · 5.13 KB

AGENTS.md

File metadata and controls

86 lines (72 loc) · 5.13 KB

AI agents guide — Relavium

All AI agents working on this repository should read this file first.

The canonical agent guide is CLAUDE.md — written with Claude-based tooling in mind, but its rules apply to every AI agent regardless of model or runner. This file is the open-standard (AGENTS.md) entry point and a condensed mirror; CLAUDE.md is the source of truth.

Relavium is a multi-surface, local-first AI agent platform (a HodeTech product): start as an agent, ship the workflow, own every run. You begin in a conversational agent session — a first-class engine entry point on every surface (CLI relavium chat, a desktop chat tab, a VS Code coding-assistant) — and graduate it into a multi-agent, multi-model workflow authored as git-committable YAML. Both entry points (AgentSession and WorkflowEngine) sit on one pure-TypeScript engine shared by a Tauri desktop app, a VS Code extension, and a CLI (ADR-0024, ADR-0026). It is a Turborepo + pnpm monorepo (packages/shared, packages/llm, packages/core, packages/db, packages/ui; apps/desktop, apps/cli, apps/vscode-extension; apps/api + the control-plane apps/portal are Phase 2). A run executes in one of three execution modes behind the one LLMProvider seam — local (BYOK, Phase-1 default), cloud (BYOK-central, Phase 2), and managed (Relavium's own keys via a metered egress gateway; engine stays local, Phase 2) — split across build phase 5 (managed inference) and phase 6 (cloud execution + portal); the engine is identical across all three (ADR-0012..0015). Status: Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); @relavium/llm (the seam + all three adapters) is landed and green. Phase 0 (M0) landed the monorepo + @relavium/shared + CI + @relavium/db. The @relavium/core engine has since landed the full run-loop + node stack — parser, interpolation, DAG/RunPlan, the run loop + RunEventBus, the tool registry, the AgentRunner, the six node-type handlers, the human gate, checkpoint/resume, node retry, the expression sandbox, and the pre-egress budget governor — plus the agent-first AgentSession (1.V), completing milestone 1.m4 (PRs #13–#26); then the 1.U end-to-end Node harness landed (PR #27, 2026-06-16), reaching milestone M2 (the engine runs end-to-end) — the Phase-1 engine critical path is complete, and Phase 2 (the CLI) is unblocked. The remaining Phase-1 work is the additive agent-first + multimodal sub-spines; see docs/roadmap/current.md for live status.

The non-negotiable rules

  1. TypeScript-first, strict. No any, no unsafe as.
  2. Build in-house; minimize deps. No new runtime dependency without an ADR. Never the Vercel AI SDK or LangChain — Relavium owns @relavium/llm. Never reinvent security-critical primitives (crypto/TLS/keychain).
  3. No vendor SDK type crosses the @relavium/llm LLMProvider seam (ADR-0011).
  4. The engine (packages/core) has zero platform-specific imports.
  5. Local-first, secure by default. API keys live in the OS keychain — never plaintext, never in logs, never sent to the frontend (ADR-0006). (Phase-2 managed mode) Relavium's own keys live in a KMS-backed master-key vault + key pools, attached only inside the gateway and never crossing the seam (ADR-0013).
  6. The desktop app is an agent-management center, not an IDE. A conversational chat tab (an agent capability) is allowed and co-equal with the canvas; the forbidden boundary is the IDE shell — no code editor, file-tree, or terminal (ADR-0007, refined not reversed by ADR-0025).
  7. One canonical home per artifact — specs live in docs/reference/; link, don't restate.
  8. Decisions are ADRs in docs/decisions/, condensed MADR, append-only (supersede, never rewrite).
  9. English, kebab-case, relative links, Mermaid, Conventional Commits.

Before you start

  1. Read README.md, then CLAUDE.md in full.
  2. Read docs/glossary.md and docs/roadmap/current.md.
  3. Read the ADRs in docs/decisions/ in numerical order.
  4. Read the docs/standards/ relevant to your task.
  5. If the task matches a skill in .claude/skills/, follow that skill's procedure step by step.

Build, test, lint

pnpm install
pnpm turbo run lint typecheck test
pnpm turbo run build

Never npm or yarn. workspace:* for inter-package deps; no circular deps.

Git workflow

  • Trunk-based on main; short-lived feature branches via PR.
  • Conventional Commits with a per-package scope (feat(core):, fix(llm):, docs(decisions):). Reference the ADR or task the change advances. See docs/standards/commit-style.md.

Escalation

If a requested change would violate any rule above, stop and ask before proceeding.